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

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

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

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

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

مقدمة

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

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

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

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

انتقِل إلى وحدة تحكّم Google Cloud.
انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لمكتبة Maps JavaScript API، ثم انقر على فتح.
من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Places API.
إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد أكملت الإعداد. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة، فعِّلها:
1. في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة اليمنى.
2. ابحث عن Places API، ثم اختَره من قائمة النتائج.
3. انقر على تفعيل. عند اكتمال العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.

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

خدمة "الأماكن" هي مكتبة مكتفية ذاتيًا، منفصلة عن الرمز الرئيسي لـ واجهة برمجة التطبيقات JavaScript لخرائط Google. لاستخدام الميزات المضمّنة في هذه المكتبة، عليك أولاً تحميلها باستخدام المَعلمة 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 لاسترداد نتائج الإكمال التلقائي آليًا (راجِع مرجع واجهة برمجة التطبيقات JavaScript لخرائط Google: فئة AutocompleteService).

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

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

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

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

يمكنك الاطّلاع على التفاصيل أدناه.
يمكنك إنشاء كائن AutocompleteService لاسترداد التوقّعات آليًا. اتصل بالرقم getPlacePredictions() ل retrieving matching places، أو اتصل بالرقم getQueryPredictions() ل retrieving matching places plus suggested search terms. ملاحظة: لا تضيف 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، لن يتم ضبط سوى place id و types وname في PlaceResult المتاح. يمكنك استخدام رقم تعريف الموقع الجغرافي المعروض مع طلبات البيانات من خدمات "الأماكن" أو "ترميز الموقع الجغرافي" أو "الاتجاهات" أو "مصفوفة المسافات".
  ملاحظة: ستحتوي السمة 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". بالنسبة إلى الاقتراحات التي تتمّ من خلال ميزة "الإكمال التلقائي" والتي تحتوي على رقم في الوصف (يتم مطابقة query المُدخلة)، لا يحتوي ردّ "تفاصيل المكان" على معرّف المكان على رقم الشارع إلا إذا كانت مصفوفة types للاقتراح تحتوي على واحد على الأقل مما يلي:

street_address
الافتراض
مؤسسة

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

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

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

ملاحظة: تتم ترجمة نص العنصر النائب التلقائي تلقائيًا. إذا تحديد قيمة العنصر النائب، عليك معالجة ترجمة تلك القيمة في تطبيقك. للحصول على معلومات عن كيفية اختيار واجهة برمجة التطبيقات 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 هو العبارة المطابقة.

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

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 لتضمينها في خريطة 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-query` وجزئيًا في النص المتبقّي في `pac-item`.

تحسين ميزة "الإكمال التلقائي للأماكن"

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

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

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

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

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

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

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

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

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

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

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

نعم، يجب تقديم المزيد من التفاصيل

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

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

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

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

لا، يجب إدخال العنوان والموقع الجغرافي فقط.

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

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

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

نعم

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

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

لا

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

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

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

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

لمعرفة التكاليف، يُرجى الاطّلاع على قوائم أسعار Google Maps Platform.

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

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

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

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

الحصص

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

السياسات

يجب أن يكون استخدام Places Library وواجهة برمجة تطبيقات JavaScript للخرائط متوافقًا مع السياسات الموضّحة في واجهة برمجة تطبيقات Places API.

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

مقدمة

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

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

ملخّص الفصول

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

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

ضبط الخيارات عند إنشاء النموذج

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

TypeScript

JavaScript

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

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

TypeScript

JavaScript

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

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

TypeScript

JavaScript

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

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

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

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

تحسين ميزة "الإكمال التلقائي للأماكن"

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

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

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

نعم، يجب تقديم المزيد من التفاصيل

لا، يجب إدخال العنوان والموقع الجغرافي فقط.

نعم

لا

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

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

الحصص

السياسات