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

مقدمة

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

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

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

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

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

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

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

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

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

  

  

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

  

  يمكنك الاطّلاع على التفاصيل أدناه.
• يمكنك إنشاء كائن AutocompleteService لاسترداد التوقّعات آليًا. اتصل بالرقم getPlacePredictions() ل retrieving matching places، أو اتصل بالرقم getQueryPredictions() ل retrieving matching places plus suggested search terms. ملاحظة: لا تضيف 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، لن يتم ضبط سوى place id و types وname في PlaceResult المتاح. يمكنك استخدام رقم تعريف الموقع الجغرافي الذي تم إرجاعه مع طلبات البيانات من خدمات "الأماكن" أو "ترميز الموقع الجغرافي" أو "الاتجاهات" أو "مصفوفة المسافات".

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

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

ضبط الخيارات عند إنشاء النموذج

يقبل 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 API للغة التي سيتم استخدامها، يُرجى الاطّلاع على المستندات حول الأقلمة.

اطّلِع على تصميم التطبيقات المصغّرة "الإكمال التلقائي" و"مربّع البحث" لتخصيص مظهر التطبيق المصغّر.

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

عرض مثال

اطّلِع على تصميم التطبيقات المصغّرة "الإكمال التلقائي" و"مربّع البحث" لتخصيص مظهر التطبيق المصغّر.

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

لاسترداد التوقّعات آليًا، استخدِم فئة 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 هو العبارة المطابِقة.

ينفِّذ المثال أدناه طلب توقّع طلب بحث للعبارة 'pizza near' ويعرض النتيجة في قائمة.

// 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 لتضمينها في خريطة Google. يمكنك تعديل التصميم ليناسب موقعك الإلكتروني. تتوفّر فئات CSS التالية: تنطبق جميع الفئات المدرَجة أدناه على كلّ من التطبيقات المصغّرة Autocomplete وSearchBox.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الحصص

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

السياسات

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