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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

المقدمة

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

البدء

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

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

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

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

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

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

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

ملخّص الصفوف

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

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

  • Autocomplete: تضيف حقلاً لإدخال النص إلى صفحة الويب وتراقب هذا الحقل لإدخالات الأحرف. عندما يُدخِل المستخدم نصًا، تعرض ميزة "الإكمال التلقائي" عبارات بحث مقترَحة على شكل قائمة اختيار منسدلة. وعندما يختار المستخدم مكانًا من القائمة، يتم إرجاع معلومات المكان إلى عنصر الإكمال التلقائي، ويمكن للتطبيق استردادها. راجع التفاصيل أدناه.
    حقل نص الإكمال التلقائي وقائمة اختيار أماكن التوقّعات المقدَّمة أثناء إدخال المستخدم طلب البحث.
    الشكل 1: الإكمال التلقائي لحقل النص وقائمة الاختيار
    نموذج عنوان مكتمل.
    الشكل 2: نموذج العنوان الكامل
  • SearchBox يضيف حقلاً نصيًا إلى صفحتك على الويب، بالطريقة نفسها التي يستخدمها Autocomplete. وفي ما يلي الاختلافات:
    • ويكمن الاختلاف الرئيسي في النتائج التي تظهر في قائمة الاختيارات. ويقدّم SearchBox قائمة موسّعة بالتوقعات، والتي يمكن أن تشمل أماكن (على النحو المحدّد في واجهة برمجة تطبيقات الأماكن) بالإضافة إلى عبارات البحث المقترحة. على سبيل المثال، إذا أدخل المستخدم 'بيتزا في'، قد تشتمل قائمة الاختيارات على العبارة 'بيتزا في نيويورك، نيويورك&#39، بالإضافة إلى أسماء منافذ البيتزا المختلفة.
    • يقدّم SearchBox خيارات أقل من Autocomplete لحظر البحث. في السابق، يمكنك انحياز البحث نحو LatLngBounds معيّن. وفي الحالة الثانية، يمكنك حصر البحث على بلد معيّن وأنواع أماكن معيّنة، وكذلك تحديد الحدود. ولمزيد من المعلومات، يمكنك الاطّلاع على أدناه.
    نموذج عنوان مكتمل.
    الشكل 3: يقدّم SearchBox عبارات البحث وتوقّعات الأماكن.
    اطّلِع على التفاصيل أدناه.
  • يمكنك إنشاء عنصر 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. يجب إدخال بلدان متعددة كقائمة برموز البلدان.

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

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

حصر توقعات الإكمال التلقائي

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

تحديد الخيارات عند الإنشاء

تقبل دالة الإنشاء Autocomplete معلَمة AutocompleteOptions لضبط القيود عند إنشاء الأداة. يحدّد المثال التالي الخيارات bounds وcomponentRestrictions وtypes لطلب الأماكن من establishment، مع تفضيل الأماكن ضمن المنطقة الجغرافية المحدّدة وقصر التوقعات على الأماكن داخل الولايات المتحدة فقط. يؤدي ضبط الخيار fields إلى تحديد المعلومات التي يجب عرضها حول المكان المحدّد للمستخدم.

يمكنك استدعاء setOptions() لتغيير قيمة خيار لأداة حالية.

TypeScript

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,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

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,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

تحديد حقول البيانات

حدِّد حقول البيانات لتجنُّب دفع رسوم رموز التخزين التعريفي لبيانات الأماكن التي لا تحتاج إليها. أدرِج السمة fields في AutocompleteOptions التي يتم تمريرها إلى أداة إنشاء الأداة، كما هو موضّح في المثال السابق، أو استدعاء setFields() في الكائن Autocomplete الحالي.

autocomplete.setFields(["place_id", "geometry", "name"]);

تحديد الانحيازات وحدود منطقة البحث للإكمال التلقائي

يمكنك انحياز نتائج الإكمال التلقائي لصالح موقع جغرافي أو منطقة تقريبًا، بالطرق التالية:

  • حدِّد الحدود عند إنشاء العنصر Autocomplete.
  • يمكنك تغيير الحدود في Autocomplete الحالية.
  • اضبط الحدود على إطار عرض الخريطة.
  • تقييد البحث على الحدود.
  • تقييد البحث على بلد محدد.

يوضح المثال السابق إعداد الحدود عند الإنشاء. توضح الأمثلة التالية أساليب الانحياز الأخرى.

تغيير حدود الإكمال التلقائي الحالي

يمكنك الاتصال بـ setBounds() لتغيير منطقة البحث على Autocomplete الحالية إلى حدود مستطيلة.

TypeScript

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);

JavaScript

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);
ضبط الحدود على إطار عرض الخريطة

يمكنك استخدام bindTo() لانحياز النتائج إلى إطار عرض الخريطة، حتى أثناء تغيير إطار العرض هذا.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

يمكنك استخدام unbind() لإلغاء ربط توقعات الإكمال التلقائي من إطار عرض الخريطة.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

عرض مثال

تقييد البحث على الحدود الحالية

يمكنك ضبط الخيار strictBounds لتقييد النتائج بالحدود الحالية، سواء كانت تستند إلى إطار عرض الخريطة أو حدود مستطيلة.

autocomplete.setOptions({ strictBounds: true });
حصر التوقعات على بلد معيّن

يمكنك استخدام الخيار componentRestrictions أو الاتصال بالرقم setComponentRestrictions() لحصر البحث التلقائي في مجموعة محدّدة من خمسة بلدان كحدّ أقصى.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

عرض مثال

تقييد أنواع الأماكن

يمكنك استخدام الخيار 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.

يستخدم المثال التالي الإكمال التلقائي لملء الحقول في نموذج عنوان.

TypeScript

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();
}

JavaScript

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;

عرض مثال

تخصيص نص العنصر النائب

يحتوي حقل النص الذي تم إنشاؤه بواسطة خدمة الإكمال التلقائي تلقائيًا على نص العنصر النائب العادي. لتعديل النص، اضبط السمة placeholder على العنصر input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

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

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

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

وتوفّر السمة SearchBox قائمة موسّعة بالتوقّعات، والتي يمكن أن تشمل أماكن (على النحو المحدّد في واجهة برمجة تطبيقات الأماكن) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم 'pizza in new'، قد تتضمّن قائمة الاختيار العبارة 'بيتزا في نيويورك، نيويورك&#39، بالإضافة إلى أسماء منافذ البيتزا المختلفة. وعندما يختار مستخدم مكانًا من القائمة، يتم عرض معلومات حول ذلك المكان إلى كائن 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، يُرجى الرجوع إلى المستندات حول نتائج تفاصيل المكان.

TypeScript

// 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);
});

JavaScript

// 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);
});

عرض مثال

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

استرداد توقعات خدمة الإكمال التلقائي للأماكن آليًا

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

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

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

تعرض كلتا الطريقتين أعلاه مجموعة من عناصر التوقّع من النموذج التالي:

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

ينفذ المثال التالي طلب توقع طلب البحث للعبارة 'بيتزا بالقرب من&#39؛ ويعرض النتيجة في قائمة.

TypeScript

// 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;

JavaScript

// 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;

CSS

HTML

<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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

جرّب عيّنة

عرض مثال

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

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

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

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

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

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

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

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

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

تصميم أدوات الإكمال التلقائي وSearchBox

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

رسم توضيحي رسومي لصفوف CSS للأدوات الإضافية الخاصة بميزة &quot;الإكمال التلقائي&quot; وSearchBox
فئات CSS للأدوات الإضافية الخاصة بميزة "الإكمال التلقائي" وSearchBox
فئة CSS الوصف
pac-container العنصر المرئي الذي يتضمّن قائمة بالتوقعات التي تعرضها خدمة الإكمال التلقائي للأماكن. تظهر هذه القائمة كقائمة منسدلة أسفل أداة Autocomplete أو SearchBox.
pac-icon الرمز المعروض على يمين كل عنصر في قائمة التوقعات.
pac-item تمثّل هذه السمة عنصرًا في قائمة التوقعات التي تقدّمها الأداة Autocomplete أو SearchBox.
pac-item:hover العنصر عند تمرير المستخدم مؤشر الماوس فوقه.
pac-item-selected العنصر الذي يختاره المستخدم عبر لوحة المفاتيح. ملاحظة: ستكون العناصر المحدّدة عضوًا في هذا الصف وفي pac-item صف.
pac-item-query امتداد داخل pac-item هو الجزء الرئيسي من عبارة البحث المقترَحة. بالنسبة إلى المواقع الجغرافية، يحتوي هذا على اسم المكان، مثل 'Sydney'، أو اسم ورقم للشارع، مثل '10 شارع الملك&#39؛ لإجراء عمليات بحث نصية، مثل 'pizza in New York'، تحتوي على النص الكامل لطلب البحث. ويتم تلقائيًا تحديد اللون pac-item-query باللون الأسود. وإذا كان هناك أي نص إضافي في pac-item، يكون خارج نص pac-item-query ويكتسب نمطه من pac-item. ويكون باللون الرمادي بشكل تلقائي. ويكون النص الإضافي عادةً عنوانًا.
pac-matched جزء عبارة البحث المقترَحة التي تتطابق مع ملاحظات المستخدم. ويتم تلقائيًا تمييز هذا النص المُطابِق بنص غامق. يُرجى العلم بأنّ النص المطابق قد يكون في أي مكان داخل pac-item. إنها ليست بالضرورة جزءًا من pac-item-query، ويمكن أن تكون جزءًا من pac-item-query وكذلك في النص المتبقي في pac-item.

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

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

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

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

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

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

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

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

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

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

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

نعم، بحاجة إلى مزيد من التفاصيل

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

تنفيذ الأدوات
يتم دمج إدارة الجلسات تلقائيًا في أدوات JavaScript أو Android أو iOS. يتضمّن هذا كلاً من طلبات "الإكمال التلقائي" للمكان و"تفاصيل المكان" في عبارة البحث المقترَحة. تأكد من تحديد المعلمة fields للتأكد من أنك تطلب فقط حقول بيانات المكان التي تحتاجها فقط.

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

  1. رقم تعريف المكان من ردّ "الإكمال التلقائي" للمكان
  2. الرمز المميز للجلسة المُستخدَم في طلب الإكمال التلقائي للأماكن
  3. المعلَمة fields التي تحدّد حقول بيانات الأماكن التي تحتاجها

لا، يحتاج فقط إلى العنوان والموقع

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

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

هل يختار المستخدمون توقّع "الإكمال التلقائي" للأماكن من خلال أربعة طلبات أو أقل في المتوسط؟

نعم

نفِّذ ميزة "الإكمال التلقائي" للأماكن آليًا بدون الرموز المميزة للجلسة واستدعاء واجهة برمجة التطبيقات للترميز الجغرافي في عبارة البحث المقترحة عن المكان.
توفّر واجهة برمجة التطبيقات للترميز الجغرافي عناوين وإحداثيات خطوط الطول/العرض مقابل 0.005 دولار أمريكي لكل طلب. عند تنفيذ أربعة طلبات تلقائيًا، تقديم طلب مقابل مكان معيّن، تبلغ التكلفة 0.01132 دولار أمريكي، وبالتالي فإن التكلفة الإجمالية لأربعة طلبات بالإضافة إلى طلب ترميز الموقع الجغرافي سيكون حول توقّع المكان المحدّد بقيمة 0.01632 دولار أمريكي، أي أقل من سعر الإكمال التلقائي لكل جلسة يبلغ 0.017 دولار أمريكي لكل جلسة.1

ننصحك باعتماد أفضل الممارسات المتعلقة بالأداء لمساعدة المستخدمين في توقّع ما يبحثون عنه باستخدام عدد أقل من الأحرف.

لا

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

تنفيذ الأدوات
يتم دمج إدارة الجلسات تلقائيًا في أدوات JavaScript أو Android أو iOS. يتضمّن هذا كلاً من طلبات "الإكمال التلقائي" للمكان و"تفاصيل المكان" في عبارة البحث المقترَحة. تأكد من تحديد المعلمة fields لضمان طلبك فقط لحقول البيانات الأساسية.

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

  1. رقم تعريف المكان من ردّ "الإكمال التلقائي" للمكان
  2. الرمز المميز للجلسة المُستخدَم في طلب الإكمال التلقائي للأماكن
  3. المعلمة fields التي تحدد حقول البيانات الأساسية، مثل العنوان والهندسة

فكِّر في تأخير طلبات الإكمال التلقائي للأماكن
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي للأماكن حتى يكتب المستخدم أول ثلاثة أو أربعة أحرف حتى يُجري التطبيق طلبات أقل. على سبيل المثال، يعني تقديم طلبات الإكمال التلقائي للمكان لكل حرف بعد أن يكتب المستخدم الحرف الثالث أنه إذا كتب المستخدم سبعة أحرف، ثم اختار توقعًا تُجري فيه طلبًا واحدًا لواجهة برمجة تطبيقات ترميز جغرافي، ستكون التكلفة الإجمالية 0.01632 دولار أمريكي (4 * 0.00283 إكمال تلقائي لكل طلب + 0.005 دولار أمريكي كترميز جغرافي).1

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

ننصحك باعتماد أفضل الممارسات المتعلقة بالأداء لمساعدة المستخدمين على توقّع ما يبحثون عنه بعدد أقل من الأحرف.


  1. التكاليف الواردة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للحصول على معلومات كاملة عن الأسعار.

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

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

  • يمكنك إضافة قيود على البلد وانحياز الموقع الجغرافي ولغة (لعمليات التنفيذ الآلية) في تنفيذ الإكمال التلقائي للأماكن. لست بحاجة إلى اختيار اللغة المفضّلة باستخدام الأدوات، لأنّها تختار الإعدادات المفضّلة للغة من متصفّح المستخدم أو جهازه الجوّال.
  • إذا كانت ميزة "الإكمال التلقائي" للأماكن مصحوبة بخريطة، يمكنك الانحياز للموقع الجغرافي حسب إطار عرض الخريطة.
  • وفي الحالات التي لا يختار فيها المستخدم أحد عبارات البحث المقترَحة من خلال ميزة"الإكمال التلقائي"، بشكل عام لأنّ أيًا من عبارات البحث المقترَحة لا تمثّل عنوان النتيجة المطلوب، يمكنك إعادة استخدام الإدخال الأصلي للمستخدم لمحاولة الحصول على نتائج أكثر صلة: من السيناريوهات الأخرى التي يفضّل فيها الرجوع إلى واجهة برمجة تطبيقات الترميز الجغرافي:
    • المستخدمون الذين يُدخِلون عناوين فرعية في بلدان أخرى غير أستراليا أو نيوزيلندا أو كندا. على سبيل المثال، لا يمكن استخدام ميزة "الإكمال التلقائي" في عنوان الولايات المتحدة "123 Bowdoin St #456, Texas MA, USA&quot. (لا تسمح ميزة الإكمال التلقائي باستخدام العناوين الفرعية إلا في أستراليا ونيوزيلندا وكندا. تشتمل تنسيقات العناوين المعتمَدة في هذه البلدان الثلاثة على "9/321 Pitt Street, London, New Southville, Australia" أو "14/19 جادة لوس أنجلوس أو براونز باي أو أوكلاند أو نيوزيلندا&quot أو &&;;145-112 Renfrew Dr, Markham, Ontario, Canada".)
    • المستخدمون الذين يُدخِلون عناوين تحتوي على بادئات مقطع الطريق، مثل "23-30 29 St. Queens" في مدينة نيويورك أو: &77-380 Kamehameha Hwy, Kaneohe"على جزيرة كاواي في هاواي'i

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

الحصص

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

السياسات

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