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

مقدمة

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

البدء

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

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

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

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

خدمة الأماكن هي مكتبة مستقلة، منفصلة عن رمز API الرئيسي لJavaScript للخرائط. لاستخدام الوظائف المضمَّنة في هذه المكتبة، عليك أولاً تحميلها باستخدام المعلَمة libraries في عنوان URL لبدء تشغيل API الخاص بـ 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 لـ "خرائط Google": فئة AutocompleteService).

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

• 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,
};

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!">

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

راجِع تصميم أدوات الإكمال التلقائي وSearchBox لتخصيص مظهر التطبيق المصغّر.

إضافة تطبيق 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

عرض مثال

راجِع تصميم أدوات الإكمال التلقائي وSearchBox لتخصيص مظهر التطبيق المصغّر.

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

لاسترداد عبارات البحث المقترحة آليًا، استخدِم الفئة 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 لخرائط Google، أو حزمة SDK للأماكن لأجهزة Android أداة الإكمال التلقائي أو حزمة SDK للأماكن في نظام التشغيل iOS عناصر التحكم في الإكمال التلقائي لواجهة المستخدم
• فهم حقول البيانات الأساسية الخاصة بميزة "الإكمال التلقائي" للمكان من البداية
• إنّ حقلَي "انحياز الموقع الجغرافي" و"حظر الموقع الجغرافي" هما أمران اختياريان، ولكن قد يكون لهما تأثير كبير في أداء الإكمال التلقائي.
• استخدِم معالجة الأخطاء لضمان تراجع مستوى تطبيقك بشكل مناسب في حال عرض واجهة برمجة التطبيقات خطأ.
• يُرجى التأكّد من معالجة التطبيق في حال عدم تحديد الخيار وتوفير طريقة للمستخدمين للمتابعة.

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

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

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

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

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

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

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

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

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

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

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

الحصص

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

السياسات

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