حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

ملاحظة: المكتبات من جهة الخادم

توضّح هذه الصفحة المكتبة من جهة العميل المتاحة مع Maps JavaScript API. إذا أردت العمل مع خدمة الويب Places API على خادمك، يمكنك الاطّلاع على عميل Node.js لخدمات "خرائط Google". وتقدّم الصفحة على ذلك الرابط أيضًا عميل Java وعميل Python وعميل Go لخدمات "خرائط Google".

مقدمة

"الإكمال التلقائي" هي ميزة في "مكتبة الأماكن" ضمن Maps JavaScript API. يمكنك استخدام ميزة "الإكمال التلقائي" لتزويد تطبيقاتك بسلوك البحث أثناء الكتابة في حقل البحث في "خرائط Google". يمكن لخدمة الإكمال التلقائي مطابقة الكلمات الكاملة والسلاسل الفرعية، وتحليل أسماء الأماكن والعناوين ورموز Plus Codes. وبالتالي، يمكن للتطبيقات إرسال طلبات البحث أثناء كتابة المستخدم، لتقديم توقّعات فورية للأماكن. وفقًا لتعريف Places API، يمكن أن يكون "المكان" مؤسسة أو موقعًا جغرافيًا أو نقطة اهتمام بارزة.

الخطوات الأولى

قبل استخدام مكتبة الأماكن في Maps JavaScript API، تأكَّد أولاً من تفعيل Places API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:

انتقِل إلى وحدة تحكّم Google Cloud.
انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API وانقر على فتح.
من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Places API.
إذا ظهرت واجهة برمجة التطبيقات في القائمة، هذا يعني أنّه تم الانتهاء من الإعداد. ومع ذلك، فإنّ هذا المشروع في حالة "قديم". لمزيد من المعلومات حول المرحلة "القديمة" وكيفية نقل البيانات من الخدمات القديمة إلى الخدمات الأحدث، يُرجى الاطّلاع على المنتجات والميزات القديمة. يتوفّر استثناء لعناصر واجهة المستخدم الإكمال التلقائي وSearchBox، والتي لم تتوفّر بعد كمنتج GA في Places API (الإصدار الجديد).

تحميل المكتبة

خدمة "الأماكن" هي مكتبة قائمة بذاتها، منفصلة عن رمز Maps JavaScript API الرئيسي. لاستخدام الميزات المضمّنة في هذه المكتبة، عليك أولاً تحميلها باستخدام المَعلمة libraries في عنوان URL لبرنامج التمهيد في Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على المكتبات.

ملخّص الصفوف

تقدّم واجهة برمجة التطبيقات نوعَين من تطبيقات الإكمال التلقائي المصغّرة التي يمكنك إضافتها باستخدام الفئتَين Autocomplete وSearchBox على التوالي. بالإضافة إلى ذلك، يمكنك استخدام فئة AutocompleteService لاسترداد نتائج الإكمال التلقائي آليًا (راجِع مرجع واجهة برمجة التطبيقات Maps JavaScript: فئة AutocompleteService).

في ما يلي ملخّص للفئات المتاحة:

Autocomplete تضيف حقل إدخال نص إلى صفحة الويب، وتراقب هذا الحقل بحثًا عن إدخالات الأحرف. عندما يُدخل المستخدم نصًا، تعرض ميزة الإكمال التلقائي توقعات للأماكن في شكل قائمة منسدلة. عندما يختار المستخدم مكانًا من القائمة، يتم عرض معلومات عن المكان في عنصر الإكمال التلقائي، ويمكن لتطبيقك استردادها. يمكنك الاطّلاع على التفاصيل أدناه.

الشكل 1: حقل نصي للإكمال التلقائي وقائمة اختيار

الشكل 2: نموذج العنوان المكتمل
SearchBox يضيف حقل إدخال نص إلى صفحة الويب، بطريقة مشابهة جدًا لـ Autocomplete. في ما يلي الاختلافات:
- يكمن الاختلاف الرئيسي في النتائج التي تظهر في قائمة الاختيار. توفّر SearchBox قائمة موسّعة من عبارات البحث المقترَحة، والتي يمكن أن تتضمّن أماكن (على النحو المحدّد في Places API) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم "بيتزا في"، قد تتضمّن قائمة الاختيار عبارة "بيتزا في القاهرة" بالإضافة إلى أسماء مطاعم بيتزا مختلفة.
- يوفّر SearchBox خيارات أقل من Autocomplete لتقييد البحث. في الحالة الأولى، يمكنك توجيه البحث نحو LatLngBounds معيّن. في الحالة الأخيرة، يمكنك حصر البحث في بلد معيّن وأنواع أماكن معيّنة، بالإضافة إلى ضبط الحدود. لمزيد من المعلومات، يُرجى الاطّلاع على ما يلي.
الشكل 3: يعرض SearchBox عبارات البحث وتوقّعات الأماكن.

يمكنك الاطّلاع على التفاصيل أدناه.
يمكنك إنشاء كائن AutocompleteService لاسترداد التوقّعات آليًا. يمكنك استدعاء getPlacePredictions() لاسترداد الأماكن المطابقة، أو استدعاء getQueryPredictions() لاسترداد الأماكن المطابقة بالإضافة إلى عبارات البحث المقترَحة. ملاحظة: لا يضيف AutocompleteService أي عناصر تحكّم في واجهة المستخدم. بدلاً من ذلك، تعرض الطرق المذكورة أعلاه مصفوفة من عناصر التوقّعات. يحتوي كل عنصر توقّع على نص التوقّع، بالإضافة إلى معلومات مرجعية وتفاصيل حول كيفية مطابقة النتيجة لإدخال المستخدم. يمكنك الاطّلاع على التفاصيل أدناه.

إضافة تطبيق مصغّر للإكمال التلقائي

تنشئ أداة Autocomplete حقل إدخال نص على صفحة الويب، وتوفّر توقّعات للأماكن في قائمة اختيار ضمن واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لطلب getPlace(). يتوافق كل إدخال في قائمة الاختيار مع مكان واحد (على النحو المحدّد في Places API).

تتطلّب الدالة الإنشائية Autocomplete وسيطتَين:

عنصر HTML input من النوع text هذا هو حقل الإدخال الذي ستراقبه خدمة الإكمال التلقائي وستُرفق نتائجها به.
وسيطة AutocompleteOptions اختيارية يمكن أن تحتوي على السمات التالية:
- مصفوفة من بيانات fields سيتم تضمينها في استجابة Place Details لـ PlaceResult الذي اختاره المستخدم. إذا لم يتم ضبط السمة أو إذا تم تمرير ['ALL']، يتم عرض جميع الحقول المتاحة وتحصيل رسوم مقابلها (لا يُنصح بذلك لعمليات النشر في مرحلة الإنتاج). للاطّلاع على قائمة بالحقول، يُرجى مراجعة PlaceResult.
- مصفوفة من types تحدّد نوعًا صريحًا أو مجموعة أنواع، كما هو مُدرَج في الأنواع المتوافقة وفي حال عدم تحديد أي نوع، يتم عرض جميع الأنواع.
- ‫bounds هو عنصر google.maps.LatLngBounds يحدّد المنطقة التي يتم البحث فيها عن الأماكن. تكون النتائج منحازة إلى الأماكن المضمّنة ضمن هذه الحدود، ولكنها لا تقتصر عليها.
- ‫strictBounds هي boolean تحدّد ما إذا كان يجب أن تعرض واجهة برمجة التطبيقات الأماكن التي تقع ضمن المنطقة المحدّدة في bounds فقط. لا تعرض واجهة برمجة التطبيقات نتائج خارج هذه المنطقة حتى إذا كانت تتطابق مع البيانات التي أدخلها المستخدم.
  ملاحظة: لا يتم تطبيق حصر الموقع الجغرافي إلا على المسارات الكاملة، وقد يتم عرض نتائج اصطناعية تقع خارج حصر الموقع الجغرافي استنادًا إلى مسار يتداخل مع حصر الموقع الجغرافي.
- يمكن استخدام componentRestrictions لحصر النتائج بمجموعات معيّنة. يمكنك استخدام componentRestrictions للفلترة حسب 5 بلدان كحد أقصى. يجب إدخال البلدان كرمز بلد مكوّن من حرفَين ومتوافق مع معيار ISO 3166-1 Alpha-2. يجب تمرير بلدان متعددة كقائمة من رموز البلدان.
  ملاحظة: إذا تلقّيت نتائج غير متوقّعة باستخدام رمز بلد معيّن، تأكَّد من أنّك تستخدم رمزًا يتضمّن البلدان والأقاليم التابعة والمناطق الخاصة ذات الأهمية الجغرافية التي تريدها. يمكنك العثور على معلومات الرموز على Wikipedia: قائمة رموز البلدان حسب ISO 3166 أو منصة التصفّح على الإنترنت ISO.
- يمكن استخدام placeIdOnly لإرشاد تطبيق Autocomplete المصغّر لاسترداد أرقام تعريف الأماكن فقط. عند استدعاء getPlace() في العنصر Autocomplete، لن يتضمّن PlaceResult الذي تم توفيره سوى السمات place id وtypes وname. يمكنك استخدام رقم تعريف المكان الذي تم عرضه مع طلبات الحصول على خدمات "الأماكن" أو "الترميز الجغرافي" أو "الاتجاهات" أو "مصفوفة المسافات".
  ملاحظة: ستحتوي السمة name على description من عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي للأماكن". يمكنك الاطّلاع على مزيد من المعلومات حول description في مستندات AutocompleteService.
  
  ملاحظة: تم إيقاف placeIdOnly نهائيًا اعتبارًا من 15 يناير 2019، وسيتم إيقافه في 15 يناير 2020. استخدِم مصفوفة fields في واجهة AutocompleteOptions بدلاً من ذلك: fields: ['place_id', 'name', 'types'].

تقييد عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي"

تعرض ميزة "الإكمال التلقائي للأماكن" تلقائيًا جميع أنواع الأماكن، مع التركيز على التوقّعات القريبة من الموقع الجغرافي للمستخدم، وتجلب جميع حقول البيانات المتاحة للمكان الذي اختاره المستخدم. اضبط خيارات "الإكمال التلقائي للأماكن" لتقديم توقّعات أكثر صلة استنادًا إلى حالة الاستخدام.

ضبط الخيارات عند الإنشاء

تقبل دالة الإنشاء Autocomplete مَعلمة AutocompleteOptions لضبط القيود عند إنشاء التطبيق المصغّر. يضبط المثال التالي الخيارات bounds وcomponentRestrictions وtypes لطلب أماكن من النوع establishment، مع تفضيل الأماكن ضمن المنطقة الجغرافية المحدّدة وحصر التوقّعات بالأماكن داخل الولايات المتحدة فقط. يحدّد ضبط الخيار fields المعلومات التي سيتم عرضها عن المكان الذي اختاره المستخدم.

يمكنك استدعاء setOptions() لتغيير قيمة خيار في تطبيق مصغّر حالي.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);index.ts

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

تحديد حقول البيانات

حدِّد حقول البيانات لتجنُّب تحصيل رسوم منك مقابل رموز التخزين التعريفية لبيانات الأماكن التي لا تحتاج إليها. أدرِج السمة fields في AutocompleteOptions التي يتم تمريرها إلى الدالة الإنشائية للتطبيق المصغّر، كما هو موضّح في المثال السابق، أو استدعِ setFields() في كائن Autocomplete حالي.

autocomplete.setFields(["place_id", "geometry", "name"]);

تحديد الانحيازات وحدود منطقة البحث لميزة "الإكمال التلقائي"

يمكنك توجيه نتائج الإكمال التلقائي لتفضيل موقع جغرافي أو منطقة تقريبية بالطرق التالية:

اضبط الحدود عند إنشاء عنصر Autocomplete.
تغيير حدود Autocomplete حالي
اضبط الحدود على إطار عرض الخريطة.
لحصر البحث على الحدود
تقييد البحث ببلد معيّن

يوضّح المثال السابق كيفية ضبط الحدود عند الإنشاء. توضّح الأمثلة التالية أساليب التحيز الأخرى.

ملاحظة: إذا لم تقدّم أي حدود أو إطار عرض للخريطة، ستحاول واجهة برمجة التطبيقات رصد الموقع الجغرافي للمستخدم من عنوان IP الخاص به، وستعطي الأولوية للنتائج التي تتطابق مع هذا الموقع الجغرافي. اضبط حدودًا كلما أمكن ذلك. وإلا، قد يتلقّى مستخدمون مختلفون توقّعات مختلفة. أيضًا، لتحسين التوقّعات بشكل عام، من المهم توفير إطار عرض معقول مثل الإطار الذي تضبطه من خلال التحريك أو التكبير على الخريطة، أو إطار عرض يحدّده المطوّر استنادًا إلى الموقع الجغرافي للجهاز ونطاقه. عندما لا يتوفّر نصف قطر، يُعتبر 5 كيلومترات قيمة تلقائية معقولة لميزة "الإكمال التلقائي للأماكن". لا تضبط إطار عرض بنصف قطر صفر (نقطة واحدة)، أو إطار عرض يمتد لبضعة أمتار فقط (أقل من 100 متر)، أو إطار عرض يمتد على مستوى العالم.

تغيير حدود ميزة "الإكمال التلقائي" الحالية

يمكنك استدعاء setBounds() لتغيير منطقة البحث في Autocomplete حالي إلى حدود مستطيلة.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);index.ts

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.js

ضبط الحدود على إطار عرض الخريطة

استخدِم bindTo() لتوجيه النتائج إلى إطار العرض في الخريطة، حتى أثناء تغيُّر إطار العرض هذا.

TypeScript

autocomplete.bindTo("bounds", map);index.ts

JavaScript

autocomplete.bindTo("bounds", map);
index.js

استخدِم unbind() لإلغاء ربط عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي" بإطار العرض في الخريطة.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });index.ts

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });index.js

الاطّلاع على مثال

حصر البحث في الحدود الحالية

اضبط الخيار strictBounds لحصر النتائج بالحدود الحالية، سواء كانت مستندة إلى إطار عرض الخريطة أو الحدود المستطيلة.

autocomplete.setOptions({ strictBounds: true });

حصر التوقّعات ببلد معيّن

استخدِم الخيار componentRestrictions أو استدعِ setComponentRestrictions() لحصر بحث الإكمال التلقائي في مجموعة محدّدة من البلدان لا تزيد عن خمسة بلدان.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});index.ts

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

الاطّلاع على مثال

تقييد أنواع الأماكن

استخدِم الخيار types أو استدعِ setTypes() لحصر التوقّعات بأنواع أماكن معيّنة. يحدّد هذا القيد نوعًا أو مجموعة أنواع، كما هو موضّح في أنواع الأماكن. وفي حال عدم تحديد أي قيد، يتم عرض جميع الأنواع.

بالنسبة إلى قيمة الخيار types أو القيمة التي تم تمريرها إلى setTypes()، يمكنك تحديد أي مما يلي:

مصفوفة تحتوي على ما يصل إلى خمس قيم من الجدول 1 أو الجدول 2 من أنواع الأماكن. على سبيل المثال:
```
types: ['hospital', 'pharmacy', 'bakery', 'country']
```
أو:
```
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
```
أي فلتر واحد في الجدول 3 من أنواع الأماكن يمكنك تحديد قيمة واحدة فقط من الجدول 3.

سيتم رفض الطلب في الحالات التالية:

إذا حدّدت أكثر من خمسة أنواع
تحديد أي أنواع غير معروفة
يمكنك دمج أي أنواع من الجدول 1 أو الجدول 2 مع أي فلتر من الجدول 3.

توضّح النسخة التجريبية من ميزة "الإكمال التلقائي للأماكن" الاختلافات في عبارات البحث المقترَحة بين أنواع الأماكن المختلفة.

الانتقال إلى العرض التوضيحي

جارٍ الحصول على معلومات عن المكان

عندما يختار المستخدم مكانًا من عبارات البحث المقترَحة المرفقة بحقل نص الإكمال التلقائي، تُطلق الخدمة حدث place_changed. للحصول على تفاصيل المكان:

أنشِئ معالج أحداث للحدث place_changed، واستدعِ addListener() في العنصر Autocomplete لإضافة المعالج.
استخدِم الدالة Autocomplete.getPlace() على العنصر Autocomplete لاسترداد العنصر PlaceResult الذي يمكنك استخدامه بعد ذلك للحصول على مزيد من المعلومات عن المكان المحدّد.

عندما يختار المستخدم مكانًا، تعرض ميزة الإكمال التلقائي تلقائيًا جميع حقول البيانات المتاحة للمكان المحدّد، وسيتم تحصيل الرسوم منك وفقًا لذلك. استخدِم Autocomplete.setFields() لتحديد حقول بيانات الأماكن المطلوب عرضها. يمكنك الاطّلاع على مزيد من المعلومات حول العنصر PlaceResult، بما في ذلك قائمة بحقول بيانات الأماكن التي يمكنك طلبها. لتجنُّب الدفع مقابل بيانات لا تحتاج إليها، احرص على استخدام Autocomplete.setFields() لتحديد بيانات الأماكن التي ستستخدمها فقط.

ملاحظة مهمة: لا ننصح باستخدام ميزة الإكمال التلقائي لإعادة تحميل أرقام تعريف الأماكن، لأنّ كل جلسة ستؤدي إلى فرض رسوم. بدلاً من ذلك، يمكنك استدعاء getDetails() وتحديد الحقل place_id فقط.

تحتوي السمة name على description من عبارات البحث المقترَحة من خلال ميزة "الإكمال التلقائي للأماكن". يمكنك الاطّلاع على مزيد من المعلومات حول description في مستندات "الإكمال التلقائي للأماكن".

بالنسبة إلى نماذج العناوين، من المفيد الحصول على العنوان بتنسيق منظَّم. لعرض العنوان المنظَّم للمكان المحدّد، يمكنك استدعاء Autocomplete.setFields() وتحديد الحقل address_components.

يستخدم المثال التالي ميزة "الإكمال التلقائي" لملء الحقول في نموذج عنوان.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}index.ts

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;
index.js

الاطّلاع على مثال

قد لا يتوفّر مكوّن العنوان street_number في ردود "تفاصيل المكان" لأرقام تعريف الأماكن في بعض عبارات البحث المقترحة. يحدث ذلك عادةً عندما يتعذّر استكمال العنوان لمكان معيّن. في هذه الحالات، ستحتوي مصفوفة types الخاصة بالتوقّع على "route". بالنسبة إلى عبارات البحث المقترحة التي تتضمّن رقمًا في الوصف (تتم مطابقة طلب البحث المُدخَل)، يحتوي ردّ "تفاصيل المكان" لرقم تعريف المكان على رقم الشارع فقط إذا كانت مصفوفة types لعبارة البحث المقترحة تحتوي على واحد على الأقل مما يلي:

street_address
مبنى
مؤسسة

تخصيص النص المؤقت

يحتوي حقل النص الذي تنشئه خدمة الإكمال التلقائي تلقائيًا على نص مؤقت عادي. لتعديل النص، اضبط السمة placeholder على العنصر input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

ملاحظة: تتم ترجمة النص المؤقت التلقائي تلقائيًا. إذا حدّدت قيمة العنصر النائب، عليك معالجة أقلمة هذه القيمة في تطبيقك. للحصول على معلومات حول كيفية اختيار Google Maps JavaScript API للغة التي سيتم استخدامها، يُرجى الاطّلاع على المستندات حول الأقلمة.

اطّلِع على تنسيق تطبيقات "الإكمال التلقائي" و"مربّع البحث" المصغّرة لتخصيص مظهر التطبيق المصغّر.

تتيح SearchBox للمستخدمين إجراء بحث جغرافي مستند إلى النص، مثل "بيتزا في القاهرة" أو "متاجر أحذية بالقرب من شارع التحرير". يمكنك إرفاق SearchBox بحقل نصي، وعند إدخال النص، ستعرض الخدمة توقعات في شكل قائمة اختيار منسدلة.

توفّر SearchBox قائمة موسّعة من عبارات البحث المقترَحة، والتي يمكن أن تتضمّن أماكن (على النحو المحدّد في Places API) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم عبارة "بيتزا في"، قد تتضمّن قائمة الاختيار عبارة "بيتزا في القاهرة" بالإضافة إلى أسماء مطاعم بيتزا مختلفة. عندما يختار المستخدم مكانًا من القائمة، يتم عرض معلومات عن هذا المكان إلى كائن SearchBox، ويمكن استردادها من خلال تطبيقك.

تتطلّب الدالة الإنشائية SearchBox وسيطتَين:

عنصر HTML input من النوع text هذا هو حقل الإدخال الذي ستراقبه خدمة SearchBox وترفق نتائجها به.
وسيطة options يمكن أن تحتوي على السمة bounds: bounds هي كائن google.maps.LatLngBounds يحدّد المنطقة التي يتم البحث فيها عن الأماكن. تكون النتائج منحازة إلى الأماكن المضمّنة ضمن هذه الحدود، ولكنّها لا تقتصر عليها.

يستخدم الرمز التالي مَعلمة الحدود لتوجيه النتائج نحو الأماكن ضمن منطقة جغرافية معيّنة، يتم تحديدها باستخدام إحداثيات خطوط العرض/الطول.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

لتغيير منطقة البحث في SearchBox حالي، استدعِ setBounds() في عنصر SearchBox وأدخِل عنصر LatLngBounds ذي الصلة.

الاطّلاع على مثال

عندما يختار المستخدم عبارة بحث من العبارات المقترَحة المرفقة بمربّع البحث، تُرسِل الخدمة حدث places_changed. يمكنك استدعاء getPlaces() في العنصر SearchBox لاسترداد مصفوفة تحتوي على عدة توقّعات، كل منها عبارة عن عنصر PlaceResult.

لمزيد من المعلومات حول العنصر PlaceResult، يُرجى الرجوع إلى المستندات حول نتائج تفاصيل المكان.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});index.ts

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});index.js

الاطّلاع على مثال

اطّلِع على تنسيق تطبيقات "الإكمال التلقائي" و"مربّع البحث" المصغّرة لتخصيص مظهر التطبيق المصغّر.

استرداد عبارات البحث المقترَحة من "خدمة الإكمال التلقائي للأماكن" آليًا

لاسترداد التوقّعات آليًا، استخدِم الفئة AutocompleteService. AutocompleteService لا يضيف أي عناصر تحكّم في واجهة المستخدم. بدلاً من ذلك، تعرض مصفوفة من عناصر التوقّعات، يحتوي كلّ منها على نص التوقّع ومعلومات مرجعية وتفاصيل عن كيفية مطابقة النتيجة لإدخال المستخدم. ويكون ذلك مفيدًا إذا أردت التحكّم بشكل أكبر في واجهة المستخدم مقارنةً بما يوفّره Autocomplete وSearchBox الموضّحان أعلاه.

توفّر واجهة برمجة التطبيقات AutocompleteService الطرق التالية:

تعرض getPlacePredictions() توقّعات الأماكن. ملاحظة: يمكن أن يكون "المكان" مؤسسة أو موقعًا جغرافيًا أو نقطة اهتمام بارزة، كما هو محدّد في Places API.
تعرض getQueryPredictions() قائمة موسّعة من التوقّعات، والتي يمكن أن تتضمّن أماكن (كما هو محدّد في Places API) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم عبارة "بيتزا في"، قد تتضمّن قائمة الاختيار عبارة "بيتزا في القاهرة" بالإضافة إلى أسماء منافذ بيع البيتزا المختلفة.

تعرض كلتا الطريقتَين أعلاه مصفوفة من عناصر التوقّعات بالشكل التالي:

‫description هي العبارة المقترَحة المطابقة.
‫distance_meters هي المسافة بالأمتار بين المكان والموقع الجغرافي المحدّد في AutocompletionRequest.origin.
يحتوي matched_substrings على مجموعة من السلاسل الفرعية في الوصف التي تتطابق مع العناصر في إدخال المستخدم. ويُعدّ ذلك مفيدًا لتمييز هذه السلاسل الفرعية في تطبيقك. في كثير من الحالات، سيظهر طلب البحث كسلسلة فرعية من حقل الوصف.
- ‫length هو طول السلسلة الفرعية.
- ‫offset هي إزاحة الأحرف، ويتم قياسها من بداية سلسلة الوصف التي تظهر فيها السلسلة الفرعية المطابقة.
‫place_id هو معرّف نصي يحدّد مكانًا بشكل فريد. لاسترداد معلومات عن المكان، أدخِل هذا المعرّف في حقل placeId في طلب تفاصيل المكان. مزيد من المعلومات عن كيفية الإشارة إلى مكان باستخدام رقم تعريف المكان
‫terms هي مصفوفة تحتوي على عناصر طلب البحث. بالنسبة إلى مكان معيّن، سيشكّل كل عنصر عادةً جزءًا من العنوان.
- ‫offset هي إزاحة الأحرف، ويتم قياسها من بداية سلسلة الوصف التي تظهر فيها السلسلة الفرعية المطابقة.
- ‫value هي العبارة المطابقة.

ينفّذ المثال أدناه طلب توقّع طلب البحث للعبارة "بيتزا بالقرب من" ويعرض النتيجة في قائمة.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;index.ts

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;index.js

CSS

style.css

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

الاطّلاع على مثال

الرموز المميزة للجلسات

يمكن لـ AutocompleteService.getPlacePredictions() استخدام الرموز المميّزة للجلسات (في حال تنفيذها) لتجميع طلبات الإكمال التلقائي معًا لأغراض الفوترة. تجمع الرموز المميزة للجلسات مرحلتَي طلب البحث والاختيار في عملية بحث مستخدم باستخدام ميزة "الإكمال التلقائي" في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عندما يختار مكانًا. يمكن أن تتضمّن كل جلسة طلبات بحث متعددة، متبوعة باختيار مكان واحد. بعد انتهاء الجلسة، لن يعود الرمز المميّز صالحًا. يجب أن ينشئ تطبيقك رمزًا مميزًا جديدًا لكل جلسة. ننصح باستخدام الرموز المميّزة للجلسات في جميع جلسات الإكمال التلقائي. في حال حذف المَعلمة sessionToken أو إعادة استخدام رمز مميّز للجلسة، يتم تحصيل رسوم الجلسة كما لو لم يتم تقديم أي رمز مميّز للجلسة (تتم فوترة كل طلب بشكل منفصل).

يجب استخدام الرمز المميّز للجلسة نفسه لإجراء طلب واحد للحصول على تفاصيل المكان في المكان الناتج عن طلب إلى AutocompleteService.getPlacePredictions(). في هذه الحالة، يتم دمج طلب الإكمال التلقائي مع طلب "تفاصيل المكان"، ويتم تحصيل رسوم المكالمة كطلب عادي لـ "تفاصيل المكان". لا يتم فرض أي رسوم على طلب الإكمال التلقائي. سيؤدي عدم استخدام الرمز المميّز للجلسة في الطلب إلى فرض رسوم على كلّ من طلب الإكمال التلقائي وطلب تفاصيل المكان.

تأكَّد من تمرير رمز مميّز فريد لكل جلسة جديدة. سيؤدي استخدام الرمز المميّز نفسه لأكثر من جلسة واحدة من جلسات "الإكمال التلقائي" إلى إبطال جلسات "الإكمال التلقائي" هذه، وسيتم تحصيل رسوم من جميع طلبات "الإكمال التلقائي" في الجلسات غير الصالحة بشكل فردي باستخدام رمز التخزين التعريفي لكل طلب من طلبات "الإكمال التلقائي". مزيد من المعلومات حول الرموز المميّزة للجلسات

يوضّح المثال التالي كيفية إنشاء رمز مميز للجلسة، ثم تمريره في AutocompleteService (تم حذف الدالة displaySuggestions() للإيجاز):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

تأكَّد من تمرير رمز مميّز فريد لكل جلسة جديدة. سيؤدي استخدام الرمز المميّز نفسه لأكثر من جلسة واحدة إلى فوترة كل طلب بشكل فردي.

مزيد من المعلومات حول الرموز المميّزة للجلسات

تنسيق تطبيقَي "الإكمال التلقائي" و"مربّع البحث" المصغّرَين

By default, the UI elements provided by Autocomplete and SearchBox are styled for inclusion on a Google map. وقد تحتاج إلى تعديل النمط ليلائم موقعك الإلكتروني. تتوفّر فئات CSS التالية. تنطبق جميع الفئات المدرَجة أدناه على كلّ من التطبيقَين المصغّرَين Autocomplete وSearchBox.

رسم توضيحي لفئات CSS لعناصر واجهة المستخدم "الإكمال التلقائي" و"مربّع البحث" — فئات CSS لعناصر واجهة المستخدم "الإكمال التلقائي" و"مربّع البحث"

فئة CSS	الوصف
`pac-container`	العنصر المرئي الذي يحتوي على قائمة عبارات البحث المقترَحة التي تعرضها خدمة "الإكمال التلقائي للأماكن". تظهر هذه القائمة كقائمة منسدلة أسفل التطبيق المصغّر `Autocomplete` أو `SearchBox`.
`pac-icon`	الرمز المعروض على يمين كل عنصر في قائمة التوقّعات
`pac-item`	عنصر في قائمة عبارات البحث المقترَحة التي يوفّرها تطبيق `Autocomplete` أو `SearchBox` المصغّر
`pac-item:hover`	العنصر عندما يمرّر المستخدم مؤشر الماوس فوقه
`pac-item-selected`	العنصر عندما يختاره المستخدم باستخدام لوحة المفاتيح ملاحظة: ستكون العناصر المحدّدة عضوًا في هذا الصف وفي الصف "`pac-item`".
`pac-item-query`	يشير هذا الحقل إلى جزء داخل `pac-item` يمثّل الجزء الرئيسي من التوقّع. بالنسبة إلى المواقع الجغرافية، يحتوي هذا الحقل على اسم مكان، مثل "القاهرة"، أو اسم شارع ورقمه، مثل "شارع الملك 10". بالنسبة إلى عمليات البحث المستندة إلى النص، مثل "بيتزا في القاهرة"، يحتوي هذا الحقل على النص الكامل لطلب البحث. يكون لون `pac-item-query` أسود تلقائيًا. إذا كان هناك أي نص إضافي في `pac-item`، يكون خارج `pac-item-query` ويستمد نمطه من `pac-item`. ويكون لونه رماديًا تلقائيًا. وعادةً ما يكون النص الإضافي عبارة عن عنوان.
`pac-matched`	جزء من عبارة البحث المقترَحة التي تطابق ما أدخله المستخدم وبشكل تلقائي، يتم تمييز هذا النص المطابق بتغميق النص. يُرجى العِلم أنّ النص المطابق قد يكون في أي مكان ضمن `pac-item`. ولا يكون بالضرورة جزءًا من `pac-item-query`، ويمكن أن يكون جزءًا من `pac-item-query` وجزءًا من النص المتبقي في `pac-item`.

تحسين الإكمال التلقائي للأماكن (القديم)

يصف هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حدّ من خدمة "الإكمال التلقائي للأماكن" (القديمة).

إليك بعض الإرشادات العامة:

أسرع طريقة لتطوير واجهة مستخدم فعّالة هي استخدام تطبيق "الإكمال التلقائي للأماكن" (الإصدار القديم) المصغّر في Maps JavaScript API، أو تطبيق "الإكمال التلقائي للأماكن" (الإصدار القديم) المصغّر في Places SDK for Android، أو عنصر التحكّم في واجهة المستخدم "الإكمال التلقائي للأماكن" (الإصدار القديم) في Places SDK for iOS.
فهم حقول البيانات الأساسية في ميزة "الإكمال التلقائي للمكان" (الإصدار القديم) من البداية
إنّ حقول تحديد الموقع الجغرافي وحصر الموقع الجغرافي اختيارية، ولكن يمكن أن يكون لها تأثير كبير في أداء ميزة "الإكمال التلقائي".
استخدِم معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سلس إذا عرضت واجهة برمجة التطبيقات خطأً.
تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، ويوفّر للمستخدمين طريقة للمتابعة.

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

لتحسين تكلفة استخدام خدمة "الإكمال التلقائي للأماكن (قديم)"، استخدِم أقنعة الحقول في تطبيقات "تفاصيل المكان (قديم)" و"الإكمال التلقائي للأماكن (قديم)" المصغّرة لعرض حقول بيانات "الإكمال التلقائي للأماكن (قديم)" التي تحتاج إليها فقط.

تحسين التكلفة المتقدّم

ننصحك بتنفيذ ميزة "الإكمال التلقائي للأماكن (الإصدار القديم)" آليًا للوصول إلى رمز التخزين التعريفي: الإكمال التلقائي - التسعير لكل طلب وطلب نتائج Geocoding API حول المكان المحدّد بدلاً من تفاصيل المكان (الإصدار القديم). يكون التسعير لكل طلب مع Geocoding API أكثر فعالية من حيث التكلفة مقارنةً بالتسعير لكل جلسة (المستند إلى الجلسة) في حال استيفاء الشرطَين التاليَين:

إذا كنت بحاجة فقط إلى خط العرض وخط الطول أو عنوان المكان الذي اختاره المستخدم، توفّر Geocoding API هذه المعلومات بتكلفة أقل من طلب Place Details (Legacy).
إذا اختار المستخدمون عبارة بحث مقترحة ضمن متوسط أربعة طلبات أو أقل من طلبات عبارات البحث المقترحة في ميزة "الإكمال التلقائي للأماكن (القديمة)"، يمكن أن يكون التسعير لكل طلب أكثر فعالية من حيث التكلفة مقارنةً بالتسعير لكل جلسة.

للحصول على مساعدة في اختيار طريقة تنفيذ ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم) التي تناسب احتياجاتك، اختَر علامة التبويب التي تتوافق مع إجابتك عن السؤال التالي.

هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخط العرض/خط الطول للتوقّع المحدّد؟

نعم، يجب إضافة المزيد من التفاصيل

استخدِم ميزة "الإكمال التلقائي للأماكن" (القديمة) المستندة إلى الجلسات مع ميزة "تفاصيل المكان" (القديمة).
بما أنّ تطبيقك يتطلّب استخدام تفاصيل المكان (Legacy)، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن يستخدم تنفيذك لخدمة الإكمال التلقائي للأماكن (Legacy) رمزًا مميزًا للجلسة (برمجيًا أو مضمّنًا في تطبيقات JavaScript أو Android أو iOS المصغّرة) لكل جلسة بالإضافة إلى رموز تخزين بيانات الأماكن التعريفية السارية، استنادًا إلى حقول بيانات الأماكن التي تطلبها.¹

تنفيذ التطبيق المصغّر
يتم دمج إدارة الجلسات تلقائيًا في التطبيقات المصغّرة التي تستخدم JavaScript أو Android أو iOS. ويشمل ذلك كلاً من طلبات "الإكمال التلقائي للأماكن (القديم)" وطلب "تفاصيل المكان (القديم)" بشأن عبارة البحث المقترَحة المحدّدة. احرص على تحديد المَعلمة fields لضمان طلب حقول بيانات "الإكمال التلقائي للأماكن (ميزات قديمة)" التي تحتاج إليها فقط.

التنفيذ الآلي
استخدِم رمزًا مميزًا للجلسة مع طلبات "الإكمال التلقائي للأماكن (القديم)". عند طلب تفاصيل المكان (الإصدار القديم) حول عبارة البحث المقترَحة المحدّدة، يجب تضمين المَعلمات التالية:

رقم تعريف المكان من ردّ "الإكمال التلقائي للأماكن (الإصدار القديم)"
الرمز المميّز للجلسة المستخدَم في طلب "الإكمال التلقائي للأماكن" (الإصدار القديم)
المَعلمة fields التي تحدّد حقول بيانات "الإكمال التلقائي للأماكن (الإصدار القديم)" التي تحتاج إليها

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

قد تكون Geocoding API خيارًا أكثر فعالية من حيث التكلفة من تفاصيل المكان (القديمة) لتطبيقك، وذلك استنادًا إلى أداء استخدامك لخدمة الإكمال التلقائي للأماكن (القديمة). تختلف كفاءة ميزة "الإكمال التلقائي لمكان" (الإصدار القديم) في كل تطبيق حسب ما يُدخله المستخدمون ومكان استخدام التطبيق وما إذا تم تنفيذ أفضل الممارسات لتحسين الأداء.

للإجابة عن السؤال التالي، عليك تحليل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل اختيار عبارة مقترَحة من ميزة "الإكمال التلقائي للأماكن (القديمة)" في تطبيقك.

هل يختار المستخدمون توقّعًا من ميزة "الإكمال التلقائي للأماكن (القديمة)" في أربعة طلبات أو أقل في المتوسط؟

نعم

تنفيذ ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم) آليًا بدون الرموز المميّزة للجلسات واستدعاء Geocoding API على توقّع المكان المحدّد
توفّر Geocoding API العناوين وإحداثيات خطوط العرض والطول. إنّ إجراء أربعة طلبات من نوع الإكمال التلقائي - لكل طلب بالإضافة إلى طلب بيانات من Geocoding API بشأن عبارة البحث المقترَحة عن المكان المحدّد هو أقل من تكلفة ميزة "الإكمال التلقائي للأماكن (القديمة)" لكل جلسة.¹

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على عبارة البحث المقترَحة التي يبحثون عنها باستخدام عدد أقل من الأحرف.

لا

استخدِم ميزة "الإكمال التلقائي للأماكن" (القديمة) المستندة إلى الجلسات مع ميزة "تفاصيل المكان" (القديمة).
بما أنّ متوسط عدد الطلبات التي تتوقّع إجراؤها قبل أن يختار المستخدم عبارة مقترَحة من خدمة "الإكمال التلقائي للأماكن (قديم)" يتجاوز تكلفة التسعير لكل جلسة، يجب أن يستخدم تنفيذك لخدمة "الإكمال التلقائي للأماكن (قديم)" رمزًا مميزًا للجلسة لكل من طلبات "الإكمال التلقائي للأماكن (قديم)" وطلب "تفاصيل المكان (قديم)" المرتبط به لكل جلسة. ¹

تنفيذ التطبيق المصغّر
يتم تضمين إدارة الجلسات تلقائيًا في تطبيقات JavaScript أو Android أو iOS المصغّرة. ويشمل ذلك كلاً من طلبات "الإكمال التلقائي للأماكن (القديم)" وطلب "تفاصيل المكان (القديم)" بشأن العبارة المقترَحة المحدّدة. احرص على تحديد المَعلمة fields لضمان طلب الحقول التي تحتاج إليها فقط.

رقم تعريف المكان من ردّ "الإكمال التلقائي للأماكن (الإصدار القديم)"
الرمز المميّز للجلسة المستخدَم في طلب "الإكمال التلقائي للأماكن" (الإصدار القديم)
المَعلمة fields التي تحدّد حقول البيانات الأساسية، مثل العنوان والشكل الهندسي

ننصحك بتأخير طلبات الإكمال التلقائي للأماكن (القديم)
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي للأماكن (القديم) إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى لكي يرسل تطبيقك عددًا أقل من الطلبات. على سبيل المثال، إذا أرسلت طلبات بيانات من واجهة برمجة التطبيقات Place Autocomplete (Legacy) لكل حرف بعد أن يكتب المستخدم الحرف الثالث، يعني ذلك أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة أرسلت لها طلبًا واحدًا من Geocoding API، ستكون التكلفة الإجمالية هي 4 طلبات من Place Autocomplete (Legacy) لكل طلب + Geocoding.¹

إذا كان تأخير الطلبات يمكن أن يخفّض متوسط الطلبات الآلية إلى أقل من أربعة، يمكنك اتّباع الإرشادات الخاصة بتنفيذ ميزة "الإكمال التلقائي للأماكن (القديمة)" العالية الأداء باستخدام Geocoding API. يُرجى العِلم أنّ تأخير الطلبات قد يظهر للمستخدم على أنّه وقت استجابة، وقد يتوقّع المستخدم ظهور عبارات بحث مقترَحة مع كل ضغطة مفتاح جديدة.

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.

لمعرفة التكاليف، يُرجى الاطّلاع على قوائم أسعار "منصة خرائط Google".

أفضل الممارسات المتعلّقة بالأداء

توضّح الإرشادات التالية طرق تحسين أداء ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم):

أضِف القيود المفروضة على البلدان والانحياز للموقع الجغرافي واللغة المفضّلة (لعمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي للأماكن (الإصدار القديم)". لا حاجة إلى تحديد اللغة المفضّلة في التطبيقات المصغّرة لأنّها تختار اللغات المفضّلة من متصفّح المستخدم أو جهازه الجوّال.
إذا كانت ميزة "الإكمال التلقائي للأماكن (القديمة)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار العرض في الخريطة.
في الحالات التي لا يختار فيها المستخدم أحد عبارات البحث المقترَحة من ميزة "الإكمال التلقائي للمكان (القديمة)"، لأنّ أيًا من هذه العبارات لا يمثّل عنوان النتيجة المطلوب، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم في الأصل لمحاولة الحصول على نتائج أكثر صلة:
- إذا كنت تتوقّع أن يُدخل المستخدم معلومات العنوان فقط، أعِد استخدام البيانات التي أدخلها المستخدم الأصلي في طلب إلى Geocoding API.
- إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن حسب الاسم أو العنوان، استخدِم طلب "تفاصيل المكان (الإصدار القديم)". إذا كان من المتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم الانحياز للموقع الجغرافي.
تشمل السيناريوهات الأخرى التي يُفضَّل فيها استخدام Geocoding API ما يلي:
- المستخدمون الذين يُدخلون عناوين فرعية، مثل عناوين وحدات أو شقق معيّنة داخل مبنى على سبيل المثال، العنوان التشيكي "Stroupežnického 3191/17, Praha" يؤدي إلى توقّع جزئي في ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم).
- المستخدمون الذين يُدخلون عناوين تحتوي على بادئات لأجزاء من الطرق، مثل "‎23-30 29th St, Queens" في مدينة نيويورك أو "‎47-380 Kamehameha Hwy, Kaneohe" في جزيرة كاواي في هاواي

تحديد الموقع الجغرافي

يمكنك تحسين النتائج لمنطقة معيّنة من خلال تمرير مَعلمة location ومَعلمة radius. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم) إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. وقد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة includedRegionCodes لفلترة النتائج وعرض الأماكن ضمن بلد محدّد فقط.

تحذير: في حال عدم توفير السمة radius، سيتم تجاهل المَعلمة location.

لا تظهر نتائج المؤسسات عادةً في ترتيب عالٍ بما يكفي لعرضها في النتائج عندما تكون منطقة البحث كبيرة. إذا أردت أن تظهر المؤسسات في نتائج مختلطة بين المؤسسات والرموز الجغرافية، يمكنك تحديد نطاق جغرافي أصغر. يمكنك بدلاً من ذلك استخدام types=establishment لحصر النتائج على المؤسسات فقط.

تقييد الموقع الجغرافي

يمكنك حصر النتائج بمنطقة معيّنة من خلال تمرير مَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة من خلال المَعلمة location ومَعلمة radius، وذلك من خلال إضافة المَعلمة strictbounds. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم) لعرض النتائج ضمن تلك المنطقة فقط.

سقف الاستخدام

الحِصص

للحصول على معلومات حول الحصص والأسعار، يُرجى الاطّلاع على مستندات الاستخدام والفوترة الخاصة بواجهة Places API.

ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم) تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

مقدمة

الخطوات الأولى

تحميل المكتبة

ملخّص الصفوف

إضافة تطبيق مصغّر للإكمال التلقائي

تقييد عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي"

ضبط الخيارات عند الإنشاء

TypeScript

JavaScript

تحديد حقول البيانات

تحديد الانحيازات وحدود منطقة البحث لميزة &quot;الإكمال التلقائي&quot;

تغيير حدود ميزة "الإكمال التلقائي" الحالية

TypeScript

JavaScript

ضبط الحدود على إطار عرض الخريطة

TypeScript

JavaScript

TypeScript

JavaScript

حصر البحث في الحدود الحالية

حصر التوقّعات ببلد معيّن

TypeScript

JavaScript

تقييد أنواع الأماكن

جارٍ الحصول على معلومات عن المكان

TypeScript

JavaScript

تخصيص النص المؤقت

إضافة تطبيق SearchBox المصغّر

تغيير منطقة البحث في SearchBox

جارٍ الحصول على معلومات عن المكان

TypeScript

JavaScript

استرداد عبارات البحث المقترَحة من "خدمة الإكمال التلقائي للأماكن" آليًا

TypeScript

JavaScript

CSS

HTML

الرموز المميزة للجلسات

تنسيق تطبيقَي "الإكمال التلقائي" و"مربّع البحث" المصغّرَين

تحسين الإكمال التلقائي للأماكن (القديم)

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

تحسين التكلفة المتقدّم

نعم، يجب إضافة المزيد من التفاصيل

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

نعم

لا

أفضل الممارسات المتعلّقة بالأداء

تحديد الموقع الجغرافي

تقييد الموقع الجغرافي

سقف الاستخدام

الحِصص

ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم)

تحديد الانحيازات وحدود منطقة البحث لميزة "الإكمال التلقائي"