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

مقدمة

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

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

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

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

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

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

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

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

يمكنك الاطّلاع على نظرة عامة على المكتبات لمزيد من المعلومات.

ملخّص الصفوف

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

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

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

  

  

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

  

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

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

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

تأخذ الدالة الإنشائية Autocomplete وسيطتَين:

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

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

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

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

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

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

يقبل منشئ 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 من توقّعات ميزة "الإكمال التلقائي في Places". يمكنك الاطّلاع على مزيد من المعلومات حول description في مستندات الإكمال التلقائي في Places.

بالنسبة إلى نماذج العناوين، من المفيد الحصول على العنوان بتنسيق منظَّم. لعرض العنوان المنظَّم للمكان المحدّد، استدعِ الدالة 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 Maps JavaScript API للغة التي سيتم استخدامها، يُرجى قراءة المستندات حول التوطين.

راجِع تنسيق أدوات الإكمال التلقائي وSearchBox لتخصيص مظهر الأداة.

إضافة أداة SearchBox

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

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

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

• عنصر input HTML من النوع text هذا هو حقل الإدخال الذي ستراقبه خدمة SearchBox وسترفق نتائجها به.
• وسيطة options، والتي يمكن أن تحتوي على السمة bounds: bounds هي كائن google.maps.LatLngBounds يحدّد المنطقة التي سيتم البحث فيها عن الأماكن. وتكون النتائج منحازة إلى الأماكن الواقعة ضمن هذه الحدود، ولكنها لا تقتصر عليها.

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

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

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

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

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

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

تنسيق أداتَي Autocomplete وSearchBox

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

تحسين خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

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

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

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

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

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

لتحسين تكلفة استخدام خدمة Place Autocomplete (الإصدار القديم)، استخدِم أقنعة الحقول في أدوات Place Details (الإصدار القديم) وPlace Autocomplete (الإصدار القديم) لعرض حقول بيانات الأماكن التي تحتاج إليها فقط.

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

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

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

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

أفضل الممارسات لتحسين الأداء

توضّح الإرشادات التالية طرقًا لتحسين أداء خدمة Place Autocomplete (الإصدار القديم):

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

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

الحصص

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