توضّح هذه الصفحة "المكتبة من جهة العميل" المتاحة في
Maps JavaScript API. إذا كنت تريد العمل مع خدمة
Web API على الويب في خادمك، يمكنك إلقاء نظرة على
عميل Node.js في "خرائط Google". تقدّم الصفحة
التي تحتوي على هذا الرابط أيضًا برنامج Java Client
وPython وبرنامج Go لخدمات "خرائط Google ".
المقدمة
الإكمال التلقائي هو ميزة من مكتبة "الأماكن" في
Maps JavaScript API. يمكنك استخدام ميزة "الإكمال التلقائي" لمنح
تطبيقاتك سلوكًا مُسبقًا لنوع البحث في حقل "خرائط Google".
ويمكن أن تتطابق خدمة الإكمال التلقائي مع الكلمات والسلاسل الفرعية الكاملة، ما يؤدي إلى
حلّ أسماء الأماكن والعناوين ورموز Plus. لذلك، يمكن للتطبيقات إرسال طلبات البحث بصفتها أنواع مستخدمين لتقديم توقعات فورية أثناء التنقّل.
البدء
قبل استخدام مكتبة "الأماكن" في واجهة برمجة تطبيقات JavaScript لخدمة "خرائط Google"، تأكّد أولاً من تفعيل واجهة برمجة تطبيقات الأماكن في Google Cloud Console، وذلك في المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript لتطبيق "خرائط Google" وانقر على فتح.
من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الأماكن.
إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، هذا يعني أنك جاهز للبدء. إذا لم يتم إدراج واجهة برمجة التطبيقات، عليك تفعيلها:
في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، اختَر المكتبة في القائمة اليمنى.
ابحث عن PLACES API، ثم اختَرها من
قائمة النتائج.
انقر على تفعيل. عند انتهاء العملية،
تظهر واجهة برمجة تطبيقات الأماكن في قائمة واجهات برمجة التطبيقات في
لوحة البيانات.
جارٍ تحميل المكتبة
خدمة الأماكن هي مكتبة مستقلة، منفصلة عن رمز واجهة برمجة تطبيقات JavaScript للخرائط. لاستخدام الوظائف المضمّنة
في هذه المكتبة، عليك أولاً تحميلها باستخدام المعلَمة libraries
في عنوان URL للتشغيل مع "خرائط Google":
توفّر واجهة برمجة التطبيقات نوعَين من أدوات الإكمال التلقائي، ويمكنك إضافتهما من خلال
صفّي Autocomplete وSearchBox على التوالي.
بالإضافة إلى ذلك، يمكنك استخدام فئة AutocompleteService لاسترداد
نتائج الإكمال التلقائي آليًا (راجِع مرجع واجهة برمجة تطبيقات JavaScript في "خرائط Google":
completeService class).
في ما يلي ملخّص للصفوف المتاحة:
Autocomplete تضيف حقل إدخال نصي إلى صفحة الويب، وتراقب هذا الحقل بحثًا عن إدخالات الأحرف. مع إدخال المستخدم للنصوص، تعرض ميزة "الإكمال التلقائي" عبارات بحث مقترحة على شكل قائمة اختيار منسدلة. عندما يختار المستخدم مكانًا من القائمة، تتم إعادة المعلومات المتعلقة بالمكان إلى كائن الإكمال التلقائي، ويمكن لتطبيقك استردادها. اطّلِع على التفاصيل أدناه.
الشكل 1: إكمال الحقل النصي للنص وقائمة المنتجاتالشكل 2: إكمال نموذج العنوان
SearchBox يضيف حقل إدخال نصيًا إلى صفحة الويب، مثلما هو الحال إلى Autocomplete. وفي ما يلي الاختلافات:
ويكمن الاختلاف الرئيسي في النتائج التي تظهر في قائمة الاختيار. توفّر السمة SearchBox قائمة موسّعة بعبارات البحث المقترَحة، والتي يمكن أن تشمل أماكن (على النحو المحدّد في
APIs API) بالإضافة إلى عبارات بحث مقترَحة. على سبيل المثال، إذا أدخل المستخدم "بيتزا في جديد"، قد تتضمّن قائمة الاختيار عبارة "بيتزا في نيويورك، نيويورك"، بالإضافة إلى أسماء منافذ بيتزا مختلفة.
SearchBox يقدم خيارات أقل من
Autocomplete لحظر البحث. في السابق، يمكنك
الانحياز للبحث عن LatLngBounds معيّن. وفي المرحلة الثانية، يمكنك حصر البحث على بلد معيّن وأنواع معيّنة من الأماكن، فضلاً عن ضبط الحدود. ولمزيد من المعلومات، يمكنك الاطّلاع على أدناه.
الشكل 3: يقدّم Search Console عبارات البحث وتوقعات الأماكن.
يمكنك الاطّلاع على التفاصيل أدناه.
يمكنك إنشاء عنصر
AutocompleteService لاسترداد
عبارات البحث المقترَحة آليًا. يمكنك الاتصال بالرقم getPlacePredictions() لاسترداد الأماكن المطابقة أو الاتصال بالرقم getQueryPredictions() لاسترداد الأماكن المطابقة بالإضافة إلى عبارات البحث المقترَحة.
ملاحظة: لا يضيف AutocompleteService أي عناصر تحكم في واجهة المستخدم.
وبدلاً من ذلك، تعرض الطرق أعلاه مجموعة من عناصر التوقّع. يحتوي كل عنصر من عناصر التوقّع على نص عبارة البحث المقترَحة، بالإضافة إلى معلومات مرجعية وتفاصيل عن كيفية تطابق النتيجة مع البيانات التي أدخلها المستخدم. يمكنك الاطّلاع على
التفاصيل أدناه.
إضافة أداة إكمال تلقائي
ينشئ التطبيق المصغّر Autocomplete حقل إدخال نصيًا على صفحة الويب، ويقدّم توقعات للأماكن في قائمة اختيار واجهة المستخدم، ويعرض تفاصيل المكان استجابةً لطلب getPlace(). يتطابق كل إدخال في قائمة الاختيار مع مكان واحد (وفقًا لتعريف واجهة برمجة تطبيقات الأماكن).
تستخدم أداة إنشاء Autocomplete وسيطتَين:
عنصر HTML input من النوع text. هذا هو حقل الإدخال الذي ستراقبه خدمة الإكمال التلقائي وترفق نتائجه به.
مصفوفة من البيانات fields التي سيتم تضمينها في الاستجابة Place Details لـ PlaceResult المحددة للمستخدم. في حال عدم ضبط
السمة أو في حال ضبط ['ALL']، يتم عرض جميع الحقول المتاحة
وإرسال فواتير لها (لا يُنصح بهذا الإجراء
لعمليات نشر الإنتاج). للحصول على قائمة بالحقول، يُرجى الاطّلاع على PlaceResult.
مصفوفة من types
تحدّد نوعًا صريحًا أو مجموعة أنواع، كما هو موضّح في الأنواع المتوافقة. إذا لم يتم تحديد أي نوع، يتم عرض جميع الأنواع.
تمثّل السمة bounds كائن google.maps.LatLngBounds يحدّد المنطقة التي تبحث فيها عن الأماكن. ولا يمكن انحياز النتائج - على سبيل المثال لا الحصر - للأماكن الموجودة داخل هذه الحدود.
strictBounds هي boolean
تحدّد ما إذا كانت واجهة برمجة التطبيقات يجب أن تعرض فقط الأماكن التي تقع بدقة في المنطقة
المحدّدة في bounds. ولا تعرض واجهة برمجة التطبيقات النتائج خارج هذه المنطقة حتى إذا كانت تطابق القيمة التي أدخلها المستخدم.
يمكن استخدام componentRestrictions لحصر النتائج بمجموعات معيّنة. يمكنك حاليًا استخدام componentRestrictions للفلترة حسب ما يصل إلى 5 بلدان. ويجب إدخال البلدان كرمز بلد متوافق وفقًا لمعيار ISO 3166-1 Alpha-2. يجب إدخال بلدان متعددة كقائمة برموز البلدان.
يمكن استخدام placeIdOnly لتوجيه
التطبيق المصغّر Autocomplete لاسترداد أرقام تعريف الأماكن فقط. عند طلب
getPlace() على العنصر Autocomplete،
لن يتم ضبط سوى السمات place id وtypes وname في السمة PlaceResult المتاحة. يمكنك استخدام رقم تعريف المكان المعروض مع المكالمات إلى خدمات الأماكن أو الترميز الجغرافي أو الاتجاهات أو مصفوفة المسافة.
حصر عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي"
تقدّم ميزة "الإكمال التلقائي" للأماكن تلقائيًا جميع أنواع الأماكن، وتتحيز عند تلقّي عبارات البحث المقترحة بالقرب من الموقع الجغرافي للمستخدم، كما تجلب جميع حقول البيانات المتاحة للمكان المحدّد للمستخدم. اضبط خيارات الإكمال التلقائي من المكان لتقديم توقعات أكثر صلة استنادًا إلى حالة استخدامك.
تحديد الخيارات عند البناء
تقبل أداة الإنشاء 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,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
حدِّد حقول البيانات لتجنُّب تحصيل الرسوم منك مقابل رموز التخزين التعريفية لبيانات الأماكن التي لا تحتاج إليها. يمكنك تضمين السمة fields في
AutocompleteOptions التي يتم تمريرها إلى أداة إنشاء الأداة، كما هو موضّح في المثال السابق، أو استدعاء setFields() في عنصر Autocomplete حالي.
يمكنك استخدام الخيار types أو استدعاء setTypes() لتقييد التوقّعات لأنواع معيّنة من الأماكن. تحدد هذه القيود نوعًا أو مجموعة أنواع،
كما هو مُدرج في أنواع الأماكن.
إذا لم يتم تحديد أي قيود، يتم عرض جميع الأنواع.
بالنسبة إلى قيمة الخيار types أو القيمة التي يتم تمريرها إلى setTypes()، يمكنك تحديد أيٍّ مما يلي:
عندما ينقر المستخدم على مكان من عبارات البحث المقترَحة في حقل نص الإكمال التلقائي، يتم تنشيط حدث place_changed في الخدمة. للاطّلاع على تفاصيل المكان:
عليك إنشاء معالج الأحداث للحدث place_changed، واستدعاء addListener()
في الكائن Autocomplete لإضافة المعالج.
يمكنك استدعاء 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();
}
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 بحقل نصي، وعند إدخال النص، ستعرض الخدمة عبارات البحث المقترَحة في شكل قائمة اختيار منسدلة.
توفّر السمة 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.
// 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);
});
// 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);
});
استرداد عبارات البحث المقترحة من خدمة "الإكمال التلقائي" للأماكن
لاسترداد عبارات البحث المقترَحة بطريقة آلية، استخدِم فئة
AutocompleteService. ولا يضيف AutocompleteService
أي عناصر تحكّم في واجهة المستخدم. وبدلاً من ذلك، تعرض صفيفًا من عناصر التوقّع، يحتوي كل منها على نص التوقّع ومعلومات مرجعية وتفاصيل حول كيفية تطابق النتيجة مع البيانات التي أدخلها المستخدم.
ويكون ذلك مفيدًا إذا كنت تريد تحكّمًا أكثر في واجهة المستخدم مقارنةً
بما تقدّمه Autocomplete وSearchBox
الموضّحة أعلاه.
يعرض AutocompleteService الطرق التالية:
تعرض getPlacePredictions() توقعات الأماكن.
ملاحظة: يمكن أن يكون "المكان" مؤسسة أو موقعًا جغرافيًا أو نقطة اهتمام بارزة، وفقًا لتعريف واجهة برمجة تطبيقات الأماكن.
تعرض getQueryPredictions() قائمة موسّعة
بعبارات البحث المقترَحة، والتي يمكن أن تتضمّن أماكن (على النحو المحدّد في واجهة برمجة تطبيقات الأماكن)
بالإضافة إلى عبارات بحث مقترَحة. على سبيل المثال، إذا أدخل المستخدم
"بيتزا في جديد"، قد تتضمّن قائمة الاختيار عبارة
"بيتزا في نيويورك، نيويورك" بالإضافة إلى أسماء منافذ بيتزا مختلفة.
تعرض كلتا الطريقتين مجموعة من كائنات التوقّعات على النحو التالي:
التوقّع المطابق هو description.
distance_meters هي المسافة المقطوعة بالأمتار من المكان المحدّد في AutocompletionRequest.origin.
يحتوي matched_substrings على مجموعة من السلاسل الفرعية في الوصف تتطابق مع العناصر في إدخال المستخدم. ويُعدّ ذلك مفيدًا
لتسليط الضوء على هذه السلاسل الفرعية في تطبيقك. وفي كثير من الحالات، سيظهر طلب البحث كسلسلة فرعية من حقل الوصف.
length هو طول السلسلة الفرعية.
تمثّل السمة offset إزاحة الحرف، ويتم قياسها من بداية سلسلة الوصف التي تظهر فيها السلسلة الفرعية المطابقة.
terms هو مصفوفة تحتوي على عناصر من طلب البحث. بالنسبة إلى
المكان، سيكون كل عنصر عادةً جزءًا من العنوان.
تمثّل السمة offset إزاحة الحرف، ويتم قياسها من بداية سلسلة الوصف التي تظهر فيها السلسلة الفرعية المطابقة.
value هي العبارة المطابقة.
ينفّذ المثال التالي طلب توقّع طلب البحث لعبارة "بيتزا بالقرب من" ويعرض النتيجة في قائمة.
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;
// 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;
<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>
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.
فئات 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 يمثّل الجزء الرئيسي من عبارة البحث المقترَحة. بالنسبة إلى المواقع الجغرافية، يحتوي هذا الاسم على اسم المكان، مثل "سيدني" أو اسم شارع ورقم، مثل "10 King Street". بالنسبة إلى عمليات البحث النصية مثل "بيتزا في نيويورك"، تحتوي على النص الكامل لطلب البحث. وتكون ألوان pac-item-query باللون الأسود تلقائيًا. إذا كان هناك أي نص إضافي في pac-item، يكون خارج النطاق pac-item-query ويكتسب نمطه من pac-item. وهو ملوّن بشكل تلقائي. ويكون النص الإضافي عادةً عنوانًا.
pac-matched
جزء التوقّع المعروض الذي يتطابق مع مدخلات المستخدم. وبشكل تلقائي، يتم تمييز هذا النص المطابق بخط غامق. وتجدر الإشارة إلى أنّ النص المطابق قد يكون في أي مكان داخل pac-item. وليس بالضرورة أن يكون جزءًا من pac-item-query، ويمكن أن يكون جزئيًا داخل pac-item-query وجزءًا من النص المتبقي في pac-item.
تحسين عمليات الإكمال التلقائي للأماكن
يصف هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حد من
خدمة "الإكمال التلقائي" للأماكن.
اكتسِب فهمًا أساسيًا لحقول البيانات الخاصة بميزة "الإكمال التلقائي" من الأماكن من البداية.
إنّ حقول انحياز الموقع الجغرافي وقيود الموقع الجغرافي اختيارية، ولكن يمكن أن يكون لها تأثير كبير في أداء الإكمال التلقائي.
استخدِم التعامل مع الأخطاء للتأكّد من انخفاض مستوى أداء تطبيقك بشكلٍ سليم
إذا كانت واجهة برمجة التطبيقات تعرض خطأً.
احرص على أن يتعامل تطبيقك مع عدم توفّر أي خيار وأن يوفّر للمستخدمين طريقة للمتابعة.
أفضل ممارسات تحسين التكلفة
تحسين التكلفة الأساسية
لتحسين تكلفة استخدام خدمة "الإكمال التلقائي" للأماكن، استخدِم أقنعة الحقل في "تفاصيل المكان" والتطبيقات المصغّرة الخاصة بميزة "الإكمال التلقائي" لعرض حقول بيانات الأماكن التي تحتاج إليها فقط.
تحسين التكلفة المتقدّم
يمكنك التنفيذ الآلي للإكمال التلقائي للأماكن من أجل الوصول إلى التسعير حسب الطلب وطلب نتائج واجهة برمجة التطبيقات للترميز الجغرافي بشأن المكان المحدّد بدلاً من تفاصيل المكان. إنّ سعر كل طلب، مع واجهة برمجة التطبيقات الجغرافية، هو أكثر فعالية من حيث التكلفة من السعر لكل جلسة (مستند إلى الجلسة) إذا تم استيفاء الشرطين التاليين:
إذا كنت بحاجة فقط إلى خط العرض/خط الطول أو عنوان المكان المحدّد للمستخدم، تقدّم واجهة برمجة التطبيقات للترميز الجغرافي هذه المعلومات بأقل من طلب بشأن تفاصيل المكان.
إذا اختار المستخدمون عبارة بحث مقترَحة تلقائيًا ضمن متوسط أربعة عبارات بحث مقترَحة أو أقل، قد يكون سعر كل طلب أكثر فعالية من حيث التكلفة لكل جلسة.
للحصول على مساعدة في اختيار طريقة تنفيذ ميزة "الإكمال التلقائي" من المكان بحيث تناسب احتياجاتك، اختَر علامة التبويب التي تتوافق مع إجابتك على السؤال التالي.
هل يتطلب تطبيقك أي معلومات غير العنوان وخط العرض/خط الطول للتوقّع المحدّد؟
التكاليف المُدرَجة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للحصول على معلومات كاملة عن الأسعار.
أفضل الممارسات المتعلقة بالأداء
توضّح الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:
يمكنك إضافة قيود على البلدان
وانحياز الموقع الجغرافي
واللغة المفضّلة (في عمليات التنفيذ الآلية) إلى تنفيذ ميزة "الإكمال التلقائي" من المكان. ليس من الضروري اختيار اللغة المفضّلة
مع التطبيقات المصغّرة، لأنّها تختار إعدادات اللغة المفضّلة من متصفّح المستخدم أو جهازه الجوّال.
إذا كانت ميزة "الإكمال التلقائي" للأماكن مصحوبة بخريطة، يمكنك انحياز الموقع الجغرافي حسب إطار عرض الخريطة.
في الحالات التي لا يختار فيها المستخدم أحد عبارات البحث المقترَحة ضمن ميزة "الإكمال التلقائي"، بشكلٍ عام، لأنّ أيًّا من عبارات البحث المقترَحة لا يمثّل عنوان النتيجة المطلوب، يمكنك إعادة استخدام الإدخال الأصلي للمستخدم لمحاولة الحصول على نتائج أكثر صلة:
إذا كنت تتوقع أن يُدخِل المستخدم معلومات العنوان فقط، أعِد استخدام إدخال المستخدم الأصلي في استدعاء واجهة برمجة التطبيقات Geocode API.
إذا كنت تعتقد أنّ المستخدم يُدخِل طلبات بحث عن مكان معيّن بالاسم أو العنوان، استخدِم طلب بحث عن مكان.
وإذا كان من المتوقّع أن تكون النتائج في منطقة معيّنة فقط، استخدِم
انحياز الموقع الجغرافي.
في ما يلي سيناريوهات أخرى يكون من الأفضل فيها الرجوع إلى واجهة برمجة تطبيقات ترميز المواقع الجغرافية:
المستخدمون الذين يُدخِلون عناوين مبانٍ فرعية في البلدان التي لا تتوفّر فيها خدمة الإكمال التلقائي للأماكن من العناوين الفرعية، مثل التشيك وإستونيا وليتوانيا على سبيل المثال،
يشير العنوان التشيكي "Stroupeznického 3191/17, Praha" إلى توقّع جزئي في الإكمال التلقائي للأماكن.
المستخدمون الذين يُدخلون عناوين تتضمّن بادئات أجزاء الطريق، مثل "23-30 29 St. Queens" في
مدينة نيويورك أو "47 -380 Kamehameha Hwy, Kaneohe" على جزيرة "كواي" في "هاواي".
الحدود القصوى للاستخدام وسياسات الاستخدام
الحصص
للحصول على معلومات حول الحصص والأسعار، اطّلِع على
مستندات الاستخدام والفوترة لواجهة برمجة التطبيقات الأماكن.
