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

مقدمة

الإكمال التلقائي هو إحدى ميزات مكتبة الأماكن في 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. يجب إدخال البلدان المتعددة كقائمة برموز البلدان.

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

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

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

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

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

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

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

عرض مثال

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

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

يمكنك استخدام الرمز المميز للجلسة نفسه لتقديم طلب واحد بشأن تفاصيل المكان للمكان الناتج من طلب تم إجراؤه إلى 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تفضيل المواقع الجغرافية

يمكنك توجيه النتائج إلى منطقة محدّدة من خلال تمرير المَعلمة location والمَعلمة radius. يوجّه هذا الخيار خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم) إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. قد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة includedRegionCodes لفلترة النتائج وعرض الأماكن الواقعة ضمن بلد محدّد فقط.

حصر الموقع الجغرافي

يمكنك حصر النتائج على منطقة محدّدة من خلال تمرير المَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج على المنطقة المحدّدة بواسطة location والمَعلمة radius، وذلك عن طريق إضافة المَعلمة strictbounds التي توجّه خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم) إلى عرض النتائج فقط ضمن تلك المنطقة.

سقف الاستخدام

الحصص

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