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

مقدمة

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

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

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

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

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

جارٍ تحميل المكتبة

خدمة الأماكن هي مكتبة مستقلة ومنفصلة عن رمز واجهة برمجة التطبيقات بلغة JavaScript للخرائط. لاستخدام الوظائف الموجودة من داخل هذه المكتبة، يجب أولاً تحميلها باستخدام libraries في عنوان URL لتمهيد واجهة برمجة التطبيقات للخرائط:

<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 API للخرائط: فئة AutocompleteService).

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

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

  

  

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

  

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

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

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

تستخدم الدالة الإنشائية 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. الرمز. يجب ضبط البلدان المتعددة كقائمة لرموز البلدان.

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

  • يمكن استخدام placeIdOnly لإرشاد تطبيق Autocomplete المصغّر لاسترداد أرقام تعريف الأماكن فقط. عند إجراء مكالمة getPlace() في الكائن Autocomplete، لن تشتمل "PlaceResult" المتاحة إلا على place id، تم ضبط السمتين types وname. يمكنك استخدام ملف رقم تعريف المكان مع إجراء اتصالات بالأماكن أو الترميز الجغرافي أو الاتجاهات أو مصفوفة المسافة

تقييد توقعات الإكمال التلقائي

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

تحديد الخيارات عند البناء

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

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

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

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 حالية
• اضبط الحدود على إطار عرض الخريطة.
• حصر البحث على الحدود.
• حصر البحث على بلد معيّن.

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

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

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

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

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() لانحياز النتائج لإطار عرض الخريطة. حتى أثناء تغير إطار العرض هذا.

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

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

يمكنك استخدام unbind() لإلغاء ربط توقعات الإكمال التلقائي من إطار عرض الخريطة.

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

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

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

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

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

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. لحجز مكان التفاصيل:

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

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

تحتوي السمة name على description من توقعات الإكمال التلقائي للأماكن. يمكنك قراءة المزيد عن description في أماكن مستندات الإكمال التلقائي

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

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

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

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

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

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

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

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

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

راجِع تصميم أداتَي الإكمال التلقائي ومربّع البحث لتخصيص مظهر الأداة.

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

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

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

تستخدم الدالة الإنشائية SearchBox وسيطتين:

• عنصر input HTML من النوع 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، يمكنك الرجوع إلى الوثائق المتعلقة نتائج تفاصيل الأماكن

// 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

// 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 هو العبارة المطابقة.

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

// 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

// 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

style.css

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

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

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

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

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

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

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

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

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

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

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

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

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

نمط أداتَي الإكمال التلقائي وSearchBox

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

استخدام مكوِّن "منتقي الأماكن"

ملاحظة: يستخدم هذا النموذج مكتبة مفتوحة المصدر. يمكنك الاطّلاع على README للحصول على الدعم والملاحظات المتعلقة بالمكتبة.

جرِّب مكوّنات الويب. استخدم يمكنك وضع مكوِّن الويب لأداة اختيار المكان لتفعيل إدخال النص الذي يسمح للمستخدمين بالبحث عن عنوان أو مكان محدد باستخدام الإكمال التلقائي.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

السياسات والحدود القصوى للاستخدام

الحصص

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

السياسات

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