مقدمة
الإكمال التلقائي هو ميزة في مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript لـ "خرائط Google". يمكنك استخدام ميزة الإكمال التلقائي لمنح تطبيقاتك سلوك البحث المسبق في حقل البحث في "خرائط Google". ويمكن أن تتطابق خدمة الإكمال التلقائي مع الكلمات والسلاسل الفرعية الكاملة، ما يؤدي إلى معالجة أسماء الأماكن والعناوين ورموز الجمع. وبالتالي، يمكن للتطبيقات إرسال طلبات البحث حسب أنواع المستخدمين، وذلك لتوفير توقعات فورية عن الأماكن. كما هو موضّح في Places API، قد يكون "المكان" مؤسسة أو موقعًا جغرافيًا أو نقطة اهتمام بارزة.
الخطوات الأولى
قبل استخدام مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript للخرائط، تأكّد أولاً من تفعيل واجهة Places API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة Maps JavaScript API.
لعرض قائمة واجهات برمجة التطبيقات المفعَّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزرّ اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الأماكن.
- إذا رأيت واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك جاهز. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، يمكنك تفعيلها:
- في أعلى الصفحة، انقر على ENABLE API لعرض علامة تبويب المكتبة. يمكنك أيضًا اختيار المكتبة من القائمة الجانبية اليمنى.
- ابحث عن Places API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
جارٍ تحميل المكتبة
خدمة "الأماكن" هي مكتبة مستقلة عن رمز واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" الرئيسي. لاستخدام الوظائف المضمَّنة
في هذه المكتبة، يجب أولاً تحميلها باستخدام المَعلمة libraries
في عنوان URL الخاص ببدء تشغيل واجهة برمجة تطبيقات "خرائط Google":
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
لمزيد من المعلومات، يمكنك الاطّلاع على نظرة عامة على المكتبات.
ملخّص الصفوف
توفّر واجهة برمجة التطبيقات نوعَين من التطبيقات المصغّرة للإكمال التلقائي، يمكنك إضافتهما من خلال الصفَّين Autocomplete
وSearchBox
على التوالي.
بالإضافة إلى ذلك، يمكنك استخدام الفئة AutocompleteService
لاسترداد نتائج الإكمال التلقائي بشكل آلي (يمكنك الاطّلاع على مرجع واجهة برمجة تطبيقات JavaScript لـ "خرائط Google":
فئة AutocompleteService).
في ما يلي ملخّص عن الصفوف المتاحة:
-
Autocomplete
يضيف حقل إدخال نص إلى صفحة الويب ويراقب هذا الحقل بحثًا عن إدخالات الأحرف. بينما يُدخِل المستخدم النص، تعرض ميزة الإكمال التلقائي توقّعات الأماكن على شكل قائمة اختيار منسدلة. عندما يختار المستخدم مكانًا من القائمة، يتم عرض معلومات عن المكان في عنصر الإكمال التلقائي، ويمكن للتطبيق استرداده. يمكنك الاطّلاع على التفاصيل أدناه. - يضيف
SearchBox
حقل إدخال نص إلى صفحة الويب بالطريقة نفسها التي يضيفهاAutocomplete
. وفي ما يلي الاختلافات:- يكمن الاختلاف الرئيسي في النتائج التي تظهر ضمن قائمة الاختيار. وتوفّر دالة
SearchBox
قائمة موسّعة من عبارات البحث المقترحة التي يمكن أن تشمل أماكن (على النحو المحدّد في Places API) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم عبارة "بيتزا في مطعم جديد"، قد تحتوي قائمة الاختيارات على العبارة "بيتزا في دبي" بالإضافة إلى أسماء منافذ بيع البيتزا المختلفة. - ويقدّم
SearchBox
خيارات أقل منAutocomplete
لحصر عملية البحث. في الطريقة الأولى، يمكنك انحياز البحث نحو عنصرLatLngBounds
محدّد. وفي الحالة الثانية، يمكنك حصر البحث ببلد معيّن وأنواع أماكن معيّنة، بالإضافة إلى ضبط الحدود. لمزيد من المعلومات، يمكنك الاطّلاع على أدناه.
- يكمن الاختلاف الرئيسي في النتائج التي تظهر ضمن قائمة الاختيار. وتوفّر دالة
- يمكنك إنشاء كائن
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. يجب إدراج عدة بلدان كقائمة رموز البلدان.ملاحظة: إذا تلقّيت نتائج غير متوقعة تتضمّن رمز بلد، تأكَّد من استخدام رمز يتضمّن البلدان والأقاليم التابعة ومناطق اهتمام جغرافية خاصة التي تريدها. يمكنك العثور على معلومات حول الرموز البرمجية على ويكيبيديا: قائمة رموز البلدان وفقًا لمعيار ISO 3166 أو منصة ISO للتصفّح على الإنترنت.
- يمكن استخدام
placeIdOnly
لتوجيه تطبيقAutocomplete
المصغّر لاسترداد أرقام تعريف الأماكن فقط. عند استدعاءgetPlace()
على الكائنAutocomplete
، سيتم ضبط الخصائصPlaceResult
المتاحة فقط علىplace id
وtypes
وname
. يمكنك استخدام معرّف المكان الذي تم إرجاعه مع مكالمات إلى خدمات "الأماكن" أو "الترميز الجغرافي" أو الاتجاهات أو مصفوفة المسافة.
- مصفوفة من البيانات
تقييد توقعات الإكمال التلقائي
تعرض ميزة "الإكمال التلقائي" الخاصة بالأماكن بشكل تلقائي جميع أنواع الأماكن، بشكل متحيز لتوقّعات البحث بالقرب من الموقع الجغرافي للمستخدم، ويجلب جميع حقول البيانات المتاحة للمكان الذي اختاره المستخدم. يمكنك ضبط خيارات الإكمال التلقائي لـ "الأماكن" لعرض توقعات أكثر صلة استنادًا إلى حالة استخدامك.
ضبط الخيارات أثناء البناء
تقبل الدالة الإنشائية 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);
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);
تحديد حقول البيانات
حدِّد حقول البيانات لتجنُّب تحصيل الفواتير منك مقابل رموز التخزين التعريفية لبيانات الأماكن التي لا تحتاج إليها. ضمِّن السمة fields
في AutocompleteOptions
التي يتم تمريرها إلى الدالة الإنشائية للأداة، كما هو موضّح في المثال السابق، أو استدعِ setFields()
في عنصر Autocomplete
حالي.
autocomplete.setFields(["place_id", "geometry", "name"]);
تحديد التحيزات وحدود منطقة البحث للإكمال التلقائي
يمكنك التحيّز نتائج الإكمال التلقائي لتفضيل موقع جغرافي أو منطقة تقريبية، وذلك بالطرق التالية:
- يمكنك ضبط الحدود عند إنشاء العنصر
Autocomplete
. - تغيير الحدود على
Autocomplete
حالي - تعيين الحدود على إطار عرض الخريطة.
- احصر البحث بالحدود.
- حصر البحث ببلد معيّن
يوضح المثال السابق حدود الإعداد عند الإنشاء. توضح الأمثلة التالية تقنيات التحيز الأخرى.
تغيير حدود إكمال تلقائي حالي
عليك استدعاء 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);
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);
ضبط الحدود على إطار عرض الخريطة
استخدِم bindTo()
لانحياز النتائج في إطار عرض الخريطة،
حتى مع تغيّر إطار العرض هذا.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
يمكنك استخدام unbind()
لإلغاء ربط توقّعات "الإكمال التلقائي" من إطار عرض الخريطة.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
حصر البحث بالحدود الحالية
يمكنك ضبط الخيار strictBounds
لحصر النتائج بالحدود الحالية، سواء كانت مستندة إلى إطار عرض الخريطة أو الحدود المستطيلة.
autocomplete.setOptions({ strictBounds: true });
حصر التوقعات في بلد معيّن
يمكنك استخدام الخيار componentRestrictions
أو الاتصال بالرقم setComponentRestrictions()
لحصر
ميزة البحث ضمن ميزة "الإكمال التلقائي" على عدد محدّد يصل إلى خمسة بلدان.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
تقييد أنواع الأماكن
استخدِم الخيار 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()
لتحديد بيانات المكان التي ستستخدمها فقط.
تحتوي السمة 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(); }
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;
تخصيص نص العنصر النائب
بشكل تلقائي، يحتوي حقل النص الذي تم إنشاؤه من خلال خدمة الإكمال التلقائي على نص عنصر نائب عادي. لتعديل النص، اضبط السمة placeholder
على العنصر input
:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
ملاحظة: تتم ترجمة نص العنصر النائب التلقائي تلقائيًا. وإذا حددت قيمة العنصر النائب الخاصة بك، يجب التعامل مع أقلمة هذه القيمة في تطبيقك. للاطّلاع على معلومات عن آلية تحديد واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" اللغة المطلوب استخدامها، يُرجى قراءة المواد المتعلّقة بالأقلمة.
راجِع تصميم كلٍّ من الإكمال التلقائي وأداة SearchBox لتخصيص مظهر التطبيق المصغّر.
إضافة تطبيق SearchBox المصغّر
تتيح
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
لتغيير منطقة البحث عن عنصر 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); });
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); });
راجِع تصميم كلٍّ من الإكمال التلقائي وأداة SearchBox لتخصيص مظهر التطبيق المصغّر.
استرداد توقعات خدمة الإكمال التلقائي للأماكن بشكل آلي
لاسترداد عبارات البحث المقترَحة بطريقة آلية، استخدِم الفئة
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;
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;
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>
تجربة النموذج
الرموز المميّزة للجلسة
يمكن لخدمة 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);
تأكد من تمرير رمز مميز فريد للجلسة لكل جلسة جديدة. سيؤدي استخدام الرمز المميّز نفسه لأكثر من جلسة إلى تحصيل رسوم كل طلب على حدة.
المزيد من المعلومات حول الرموز المميّزة للجلسة
تصميم تطبيقَي الإكمال التلقائي وSearchBox
يتم تلقائيًا تصميم عناصر واجهة المستخدم المقدَّمة من Autocomplete
وSearchBox
بحيث يتم تضمينها على خريطة Google. ويمكنك
تعديل التصميم ليلائم موقعك الإلكتروني. تتوفّر فئات 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 |
استخدام مكوِّن "أداة اختيار الأماكن"
ملاحظة: يستخدم هذا النموذج مكتبة مفتوحة المصدر. يمكنك الاطّلاع على ملف README للحصول على الدعم والملاحظات المتعلقة بالمكتبة.
جرِّب مكوّنات الويب. استخدِم مكوّن الويب "أداة اختيار المكان" لتفعيل إدخال النص الذي يسمح للمستخدمين بالبحث عن عنوان أو مكان محدّد باستخدام الإكمال التلقائي.
تحسين الإكمال التلقائي للأماكن
يوضِّح هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حدّ من خدمة الإكمال التلقائي للأماكن.
في ما يلي بعض الإرشادات العامة:
- تتمثل أسرع طريقة لتطوير واجهة مستخدم عاملة في استخدام واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" أداة الإكمال التلقائي أو حزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل Android أو أداة الإكمال التلقائي أو حزمة تطوير البرامج للأماكن المخصّصة لنظام التشغيل iOS التحكم في الإكمال التلقائي لواجهة المستخدم
- فهم حقول البيانات الأساسية الخاصة بالإكمال التلقائي للأماكن من البداية
- يُعدّ حقلا "انحياز الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريًا، ولكن قد يكون لهما تأثير كبير في أداء الإكمال التلقائي.
- استخدِم معالجة الأخطاء لضمان تراجع أداء تطبيقك بشكل آمن إذا ظهرت واجهة برمجة التطبيقات خطأ.
- تأكَّد من أنّ تطبيقك يعالجه في حال عدم تحديد أي خيار، وأنّه يوفِّر للمستخدمين طريقة للمتابعة.
أفضل الممارسات لتحسين التكلفة
تحسين التكلفة الأساسية
ولتحسين تكلفة استخدام خدمة الإكمال التلقائي للأماكن، استخدِم أقنعة الحقول في أداتَي "تفاصيل المكان" و"الإكمال التلقائي للأماكن" لعرض حقول بيانات المكان التي تحتاج إليها فقط.
التحسين المتقدم للتكلفة
يمكنك الاستخدام الآلي للإكمال التلقائي لـ "الإكمال التلقائي" للوصول إلى السعر لكل طلب وطلب نتائج واجهة برمجة التطبيقات للترميز الجغرافي حول المكان المحدّد بدلاً من تفاصيل المكان. إنّ التسعير لكلّ طلب عند إقرانه بواجهة برمجة تطبيقات الترميز الجغرافي يكون أكثر فعالية من حيث التكلفة من التسعير لكل جلسة (استنادًا إلى الجلسة) في حال استيفاء الشرطَين التاليَين:
- إذا كنت تحتاج فقط إلى خط العرض/خط الطول أو عنوان المكان الذي اختاره المستخدم، ستعرض واجهة برمجة تطبيقات الترميز الجغرافي هذه المعلومات بتكلفة أقل من طلب بيانات عن تفاصيل المكان.
- إذا اختار المستخدمون عبارات بحث مقترحة للإكمال التلقائي ضمن متوسط أربعة طلبات لتوقعات الإكمال التلقائي أو أقل، قد يكون التسعير لكل طلب أكثر فعالية من حيث التكلفة من التسعير لكل جلسة.
هل يتطلّب طلبك أي معلومات أخرى غير العنوان وخط العرض أو خط الطول لعبارة البحث المقترحة التي اخترتها؟
نعم، يجب تقديم تفاصيل إضافية.
استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسة لـ "تفاصيل المكان"
بما أنّ طلبك يتطلّب "تفاصيل المكان"، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن تستخدِم ميزة "الإكمال التلقائي" الخاصة بالمكان رمزًا مميّزًا للجلسة (آليًا أو مُدمجًا في أدوات JavaScript أو Android أو iOS) بتكلفة إجمالية تبلغ 0.017 دولار أمريكي لكل جلسة بالإضافة إلى رموز التخزين التعريفية لبيانات الأماكن السارية بناءً على حقول بيانات الأماكن التي تطلبها.
تنفيذ الأداة
يتم دمج إدارة الجلسات تلقائيًا في أدوات JavaScript أو Android أو iOS. ويشمل ذلك طلبات الإكمال التلقائي الخاصة بالأماكن وطلب تفاصيل المكان على عبارة البحث المقترحة المحدّدة. تأكّد من تحديد المَعلمة fields
لضمان أنّك لا تطلب سوى
حقول بيانات المكان التي تحتاجها.
التنفيذ الآلي
استخدِم الرمز المميّز للجلسة مع طلبات الإكمال التلقائي للأماكن. عند طلب تفاصيل المكان عن عبارة البحث المقترحة المحدّدة، يجب تضمين المَعلمات التالية:
- رقم تعريف المكان من رد الإكمال التلقائي للمكان
- الرمز المميز للجلسة المستخدَم في طلب الإكمال التلقائي لـ "المكان"
- معلمة
fields
التي تحدد حقول بيانات المكان التي تحتاجها
لا، يحتاج إلى العنوان والموقع فقط
قد تكون واجهة برمجة تطبيقات الترميز الجغرافي خيارًا أكثر فعالية من حيث التكلفة من ميزة "تفاصيل المكان" لتطبيقك، وذلك استنادًا إلى أداء استخدام ميزة "الإكمال التلقائي" الخاصة بالأماكن. تختلف كفاءة الإكمال التلقائي لكل تطبيق وفقًا لما يدخله المستخدمون، ومكان استخدام التطبيق، وما إذا كان قد تم تنفيذ أفضل ممارسات تحسين الأداء أم لا.
للإجابة عن السؤال التالي، عليك تحليل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل تحديد أحد توقّعات الإكمال التلقائي للأماكن في تطبيقك.
هل يختار المستخدمون في مؤسستك عبارة بحث مقترحة خاصة بميزة "الإكمال التلقائي" عن الأماكن من خلال أربعة طلبات أو أقل في المتوسط؟
نعم
تنفيذ ميزة الإكمال التلقائي للأماكن بشكل آلي بدون الرموز المميّزة للجلسة وطلب واجهة برمجة التطبيقات Geocoding API عند اقتراح المكان المحدّد
توفّر واجهة برمجة التطبيقات للترميز الجغرافي العناوين وإحداثيات خطوط الطول/العرض مقابل 0.005 دولار أمريكي (أو ما يعادله بالعملة المحلية) لكل طلب. يكلّف إجراء أربعة طلبات من طلبات الإكمال التلقائي - حسب الطلب 0.01132 دولار أمريكي، وبالتالي سيكون إجمالي التكلفة لأربعة طلبات بالإضافة إلى طلب بيانات واجهة برمجة التطبيقات للترميز الجغرافي حول توقّع المكان المحدّد هو 0.01632 دولار أمريكي، وهو أقل من سعر الإكمال التلقائي لكل جلسة الذي يبلغ 0.017 دولار أمريكي لكل جلسة.1
ننصحك باستخدام أفضل الممارسات المتعلقة بالأداء لمساعدة المستخدمين في الحصول على توقعات البحث التي يبحثون عنها باستخدام عدد أقل من الأحرف.
لا
استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسة لـ "تفاصيل المكان"
بما أنّ متوسط عدد الطلبات التي تتوقّع تقديمها قبل أن يختار المستخدم عبارة بحث مقترَحة خاصة بميزة "الإكمال التلقائي" عن "المكان" تتجاوز تكلفة السعر لكل جلسة، يجب أن تستخدم عملية تنفيذ ميزة "الإكمال التلقائي" الخاصة بـ "المكان" رمزًا مميزًا للجلسة لكل من طلبات الإكمال التلقائي الخاصة بالأماكن وطلب "تفاصيل المكان" ذي الصلة بتكلفة إجمالية تبلغ 0.017 دولار أمريكي (أو ما يعادله بالعملة المحلية) لكل جلسة.1
تنفيذ الأداة
يتم دمج إدارة الجلسات تلقائيًا في أدوات JavaScript أو Android أو iOS. ويشمل ذلك طلبات الإكمال التلقائي الخاصة بالأماكن وطلب تفاصيل المكان على عبارة البحث المقترحة المحدّدة. تأكّد من تحديد المَعلمة fields
لضمان أنّك تطلب فقط حقول البيانات الأساسية.
التنفيذ الآلي
استخدِم الرمز المميّز للجلسة مع طلبات الإكمال التلقائي للأماكن. عند طلب تفاصيل المكان عن عبارة البحث المقترحة المحدّدة، يجب تضمين المَعلمات التالية:
- رقم تعريف المكان من رد الإكمال التلقائي للمكان
- الرمز المميز للجلسة المستخدَم في طلب الإكمال التلقائي لـ "المكان"
- المعلمة
fields
التي تحدد حقول البيانات الأساسية مثل العنوان والشكل الهندسي
تأخير طلبات الإكمال التلقائي لـ "الأماكن"
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي الخاص بالأماكن إلى أن يكتب المستخدم أول ثلاثة أو أربعة أحرف حتى يتمكّن تطبيقك من تقديم عدد أقل من الطلبات. على سبيل المثال، يعني تقديم طلبات الإكمال التلقائي لـ "أماكن" لكل حرف بعد كتابة المستخدم الحرف الثالث يعني أنه إذا كتب المستخدم سبعة أحرف ثم اختار توقعًا يمكنك تقديم طلب واحد له من واجهة برمجة التطبيقات للترميز الجغرافي، ستكون التكلفة الإجمالية 0.01632 دولار أمريكي (4 * 0.00283 إكمال تلقائي لكل طلب + 0.005 ترميز جغرافي).1
إذا أدى تأخير الطلبات إلى خفض متوسط الطلب الآلي عن أربعة طلبات، يمكنك اتّباع الإرشادات الخاصة بتنفيذ الإكمال التلقائي لأماكن معيّنة باستخدام واجهة برمجة التطبيقات Geocoding API. تجدر الإشارة إلى أنّ الطلبات المتأخرة قد تنظر إلى كونها وقت استجابة من قِبل المستخدم الذي قد يتوقّع رؤية توقعات مع كل ضغطة مفتاح جديدة.
ننصحك باستخدام أفضل ممارسات الأداء لمساعدة المستخدمين في الحصول على التوقعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.
-
التكاليف المُدرَجة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للحصول على معلومات كاملة عن الأسعار.
أفضل ممارسات الأداء
توضّح الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:
- أضِف القيود المفروضة على البلدان وانحياز الموقع الجغرافي وإعدادات اللغة المفضّلة (في عمليات التنفيذ الآلية) إلى تنفيذ ميزة الإكمال التلقائي للأماكن. ولا حاجة إلى استخدام الإعدادات المفضّلة للغة في التطبيقات المصغّرة لأنّها تختار الإعدادات المفضّلة للّغة من متصفّح المستخدم أو جهازه الجوّال.
- إذا كان الإكمال التلقائي للأماكن مصحوبًا بخريطة، يمكنك تحيز الموقع بواسطة إطار عرض الخريطة.
- في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترحة من ميزة "الإكمال التلقائي"، وبما أنّ أيًا من عبارات البحث المقترحة هذا ليس عنوان النتيجة المطلوبة، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم بهدف الحصول على نتائج أكثر صلة باهتماماتك، وذلك باتّباع الخطوات التالية:
- إذا كنت تتوقّع من المستخدم إدخال معلومات العنوان فقط، أعِد استخدام البيانات الأصلية التي أدخلها المستخدم في طلب واجهة برمجة تطبيقات الترميز الجغرافي.
- إذا كنت تتوقّع من المستخدم إدخال طلبات بحث عن مكان محدّد حسب الاسم أو العنوان، استخدِم طلب "العثور على مكان". إذا كانت النتائج غير متوقّعة في منطقة معيّنة فقط، استخدِم انحياز الموقع الجغرافي.
- المستخدمون الذين يُدخِلون عناوين المباني الفرعية في البلدان التي لا تتوفّر فيها ميزة الإكمال التلقائي لعناوين المباني الفرعية، مثل التشيك وإستونيا وليتوانيا. على سبيل المثال، يؤدي العنوان التشيكي "Stroupezznického 3191/17,prha" إلى ظهور توقّع جزئي في ميزة "الإكمال التلقائي" للمكان.
- المستخدمون الذين يُدخلون عناوين باستخدام بادئات أجزاء الطريق، مثل " 23-30 29th St, Queens" في مدينة نيويورك أو "47-380 شارع الهرم، الإسكندرية" في جزيرة كاواي في مدينة هاواي.
الحدود القصوى للاستخدام والسياسات
الحصص
للحصول على معلومات الحصص والأسعار، راجع مستندات الاستخدام والفوترة الخاصة بـ Places API.
السياسات
ويجب أن يتوافق استخدام "مكتبة الأماكن" مع "واجهة برمجة تطبيقات JavaScript للخرائط" مع السياسات الموضّحة في "واجهة برمجة تطبيقات الأماكن".