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

المقدمة

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

البدء

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

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

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

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

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

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

راجع نظرة عامة على المكتبات للحصول على مزيد من المعلومات.

ملخّص الصفوف

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

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

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

  

  

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

  

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

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

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

تستخدم دالة إنشاء Autocomplete وسيطتين:

• عنصر HTML input من النوع text. هذا هو حقل الإدخال الذي ستراقبه خدمة الإكمال التلقائي وترفق نتائجه.
• وسيطة اختيارية من النوع AutocompleteOptions، والتي يمكن أن تحتوي على الخصائص التالية:
  • مصفوفة من البيانات fields المطلوب تضمينها في الاستجابة Place Details للمستخدم PlaceResult المحدد. في حال عدم ضبط الخاصية أو في حال تمرير ['ALL']، سيتم إرجاع جميع الحقول المتاحة وتحصيل رسومها (لا يُنصَح بهذا الإجراء لعمليات نشر الإنتاج). للحصول على قائمة بالحقول، يُرجى الاطّلاع على PlaceResult.
  • مصفوفة من types تحدد نوعًا صريحًا أو مجموعة أنواع، كما هو موضح في الأنواع المتوافقة. إذا لم يتم تحديد أي نوع، يتم عرض جميع الأنواع.
  • bounds هو كائن google.maps.LatLngBounds يحدد المنطقة التي سيتم البحث فيها عن الأماكن. تكون النتائج منحازة، على سبيل المثال لا الحصر، الأماكن المضمّنة في هذه الحدود.
  • strictBounds هي boolean تحدّد ما إذا كانت واجهة برمجة التطبيقات يجب أن تعرض فقط تلك الأماكن الواقعة ضمن المنطقة التي تم تحديدها بواسطة السمة bounds المحددة. لا تعرض واجهة برمجة التطبيقات نتائج خارج هذه المنطقة حتى إذا كانت تطابق النتائج التي أدخلها المستخدم.
  • يمكن استخدام componentRestrictions لحصر النتائج بمجموعات محدّدة. يمكنك حاليًا استخدام componentRestrictions للفلترة في ما يصل إلى 5 بلدان. يجب إدخال البلدان في صورة رمز بلد متوافق مع حرفين وفقًا لمعيار ISO 3166-1 Alpha-2. يجب تمرير عدة بلدان كقائمة برموز البلدان.

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

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

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

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

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

تقبل دالة الإنشاء 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,
  types: ["establishment"],
};

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,
  types: ["establishment"],
};
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!">

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

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

إضافة أداة SearchBox

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

يقدّم SearchBox قائمة موسّعة بالتوقّعات، والتي يمكن أن تشمل الأماكن (على النحو المحدّد في واجهة برمجة تطبيقات الأماكن) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم "كباب" في القائمة الجديدة، قد تتضمّن قائمة الاختيار عبارة "كباب في القاهرة" إلى جانب أسماء مطاعم كباب. عندما يختار مستخدم مكانًا من القائمة، يتم إرجاع معلومات حول هذا المكان إلى كائن 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، يُرجى الرجوع إلى المستندات بشأن نتائج تفاصيل المكان.

// 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() تعرض توقعات الأماكن. ملاحظة: يمكن أن يكون "المكان" مؤسسة أو موقعًا جغرافيًا أو نقطة اهتمام بارزة، كما هو محدد في واجهة برمجة تطبيقات الأماكن.
• تعرض getQueryPredictions() قائمة موسعة بالتوقعات، والتي يمكن أن تتضمن أماكن (على النحو الذي تحدده واجهة برمجة تطبيقات الأماكن) بالإضافة إلى عبارات البحث المقترحة. على سبيل المثال، إذا أدخل المستخدم "كباب جديد"، فقد تتضمن قائمة الاختيار عبارة "كباب في القاهرة".

تعرض كلتا الطريقتين أعلاه مجموعة من كائنات التوقع من النموذج التالي:

• 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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.

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

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

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

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

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

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

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

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

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

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

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

أفضل ممارسات الأداء

تصف الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:

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

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

الحصص

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

السياسات

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