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

المقدمة

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

البدء

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

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

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

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

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

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

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

ملخّص الصفوف

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

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

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

  

  

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

  

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

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

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

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

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

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

  • يمكن استخدام placeIdOnly لتوجيه التطبيق المصغّر Autocomplete لاسترداد أرقام تعريف الأماكن فقط. عند طلب getPlace() على العنصر Autocomplete، لن يتم ضبط سوى السمات 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 لخدمة "خرائط Google" للغة استخدامها، يُرجى الاطّلاع على المستندات حول الترجمة.

راجِع تصميم التطبيقات المصغّرة للإكمال التلقائي وSearch Console لتخصيص مظهرها.

إضافة تطبيق SearchBox مصغّر

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

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

تستخدم أداة إنشاء SearchBox وسيطتَين:

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

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

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

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

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

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

لتغيير منطقة البحث لأحد عناصر SearchBox الحالية، يمكنك طلب setBounds() على العنصر SearchBox وتمرير العنصر LatLngBounds ذي الصلة.

عرض مثال

جارٍ الحصول على معلومات المكان

عندما يختار المستخدم عنصرًا من التوقعات المرفقة بمربّع البحث، تعمل الخدمة على تنشيط حدث places_changed. يمكنك استدعاء getPlaces() في العنصر SearchBox، لاسترداد صفيف يحتوي على عدة عبارات بحث مقترَحة، يكون كل منها عنصر PlaceResult.

لمزيد من المعلومات حول الكائن PlaceResult، يُرجى الاطّلاع على المستندات في نتائج التفاصيل عن الأماكن.

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
index.ts

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});
index.js

عرض مثال

راجِع تصميم التطبيقات المصغّرة للإكمال التلقائي وSearch Console لتخصيص مظهرها.

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

لاسترداد عبارات البحث المقترَحة بطريقة آلية، استخدِم فئة AutocompleteService. ولا يضيف AutocompleteService أي عناصر تحكّم في واجهة المستخدم. وبدلاً من ذلك، تعرض صفيفًا من عناصر التوقّع، يحتوي كل منها على نص التوقّع ومعلومات مرجعية وتفاصيل حول كيفية تطابق النتيجة مع البيانات التي أدخلها المستخدم. ويكون ذلك مفيدًا إذا كنت تريد تحكّمًا أكثر في واجهة المستخدم مقارنةً بما تقدّمه Autocomplete وSearchBox الموضّحة أعلاه.

يعرض AutocompleteService الطرق التالية:

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

تعرض كلتا الطريقتين مجموعة من كائنات التوقّعات على النحو التالي:

• التوقّع المطابق هو description.
• distance_meters هي المسافة المقطوعة بالأمتار من المكان المحدّد في AutocompletionRequest.origin.
• يحتوي matched_substrings على مجموعة من السلاسل الفرعية في الوصف تتطابق مع العناصر في إدخال المستخدم. ويُعدّ ذلك مفيدًا لتسليط الضوء على هذه السلاسل الفرعية في تطبيقك. وفي كثير من الحالات، سيظهر طلب البحث كسلسلة فرعية من حقل الوصف.
  • length هو طول السلسلة الفرعية.
  • تمثّل السمة offset إزاحة الحرف، ويتم قياسها من بداية سلسلة الوصف التي تظهر فيها السلسلة الفرعية المطابقة.
• place_id هو معرّف نصي يحدّد المكان بشكل فريد. لاسترداد معلومات حول المكان، يمكنك تمرير هذا المعرّف في حقل placeId من طلب تفاصيل المكان. اطّلِع على مزيد من المعلومات حول كيفية الإشارة إلى مكان باستخدام رقم تعريف المكان.
• terms هو مصفوفة تحتوي على عناصر من طلب البحث. بالنسبة إلى المكان، سيكون كل عنصر عادةً جزءًا من العنوان.
  • تمثّل السمة offset إزاحة الحرف، ويتم قياسها من بداية سلسلة الوصف التي تظهر فيها السلسلة الفرعية المطابقة.
  • value هي العبارة المطابقة.

ينفّذ المثال التالي طلب توقّع طلب البحث لعبارة "بيتزا بالقرب من" ويعرض النتيجة في قائمة.

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;
index.ts

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

عرض مثال

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

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

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

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

يوضّح المثال التالي إنشاء رمز مميّز للجلسة، ثم تمريره في AutocompleteService (تم حذف الدالة displaySuggestions() لإيجاز):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

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

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

تصميم التطبيقات المصغّرة الخاصة بميزة "الإكمال التلقائي" وSearch Console

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

تحسين عمليات الإكمال التلقائي للأماكن

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الحصص

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

السياسات

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