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

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الإكمال التلقائي للأماكن

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

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

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

مقدمة

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

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

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

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

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

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

خدمة "الأماكن" هي مكتبة مستقلة ومنفصلة عن رمز 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 API:‏ فئة AutocompleteService).

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

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

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

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

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

إضافة أداة الإكمال التلقائي

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

تأخذ الدالة الإنشائية Autocomplete وسيطتَين:

عنصر input HTML من النوع 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: List of ISO 3166 country codes أو ISO Online Browsing Platform.
- يمكن استخدام placeIdOnly لتوجيه أداة Autocomplete إلى استرداد معرّفات الأماكن فقط. عند استدعاء getPlace() على العنصر Autocomplete، لن يتضمّن PlaceResult الذي يتم توفيره سوى الخصائص place id وtypes وname. يمكنك استخدام معرّف المكان الذي تم عرضه مع طلبات إلى خدمات Places أو الترميز الجغرافي أو الاتجاهات أو مصفوفة المسافات.
  ملاحظة: ستحتوي السمة name على description من عبارات البحث المقترَحة في Places Autocomplete. يمكنك الاطّلاع على مزيد من المعلومات حول description في مستندات AutocompleteService.
  
  إشعار: تم إيقاف placeIdOnly نهائيًا اعتبارًا من 15 كانون الثاني (يناير) 2019، وسيتم إيقافه بالكامل في 15 كانون الثاني (يناير) 2020. استخدِم مصفوفة fields في واجهة AutocompleteOptions بدلاً من ذلك: fields: ['place_id', 'name', 'types'].

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

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

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

يقبل أداة إنشاء 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

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

حدِّد حقول البيانات لتجنُّب تحصيل رسوم منك مقابل رموز التخزين التعريفية لبيانات "أماكن Google" التي لا تحتاج إليها. أدرِج السمة 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 من عبارات البحث المقترَحة في Places Autocomplete. يمكنك الاطّلاع على مزيد من المعلومات حول description في مستندات Places Autocomplete.

بالنسبة إلى نماذج العناوين، من المفيد الحصول على العنوان بتنسيق منظَّم. لعرض العنوان المنظَّم للمكان المحدّد، استدعِ الدالة 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 وسيطتَين:

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

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

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

تجربة عيّنة

JSFiddle.net Google Cloud Shell

عرض مثال

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

يمكن 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);

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

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

تنسيق أداتَي Autocomplete وSearchBox

يتم تلقائيًا تصميم عناصر واجهة المستخدم التي توفّرها Autocomplete وSearchBox لتضمينها في خريطة Google. يمكنك تعديل التصميم ليتناسب مع موقعك الإلكتروني. تتوفّر فئات CSS التالية. تنطبق جميع الفئات المدرَجة أدناه على كلّ من أداتَي Autocomplete وSearchBox.

رسم توضيحي لفئات CSS الخاصة بأداتَي Autocomplete وSearchBox — فئات CSS لأداتَي Autocomplete وSearchBox

فئة 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`.`pac-item-query`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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

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

توضّح الإرشادات التالية طرقًا لتحسين أداء خدمة Place Autocomplete (الإصدار القديم):

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

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

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

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

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

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

لحصر النتائج في منطقة محدّدة، أضِف المَعلمة locationRestriction.

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

حدود الاستخدام

الحصص

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

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

مقدمة

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

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

ملخّص الصفوف

إضافة أداة الإكمال التلقائي

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

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

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

TypeScript

JavaScript

تقييد البحث على الحدود الحالية

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

TypeScript

JavaScript

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

الحصول على معلومات عن مكان

TypeScript

JavaScript

تخصيص نص العنصر النائب

إضافة أداة SearchBox

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

الحصول على معلومات عن مكان

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

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

تنسيق أداتَي Autocomplete وSearchBox

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

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

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

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

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

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

نعم

لا

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

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

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

حدود الاستخدام

الحصص

الإكمال التلقائي للأماكن

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