تنشئ أداة الإكمال التلقائي للأماكن حقل إدخال نصي، وتوفّر توقعات للأماكن في قائمة اختيار ضمن واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لاختيار المستخدم. استخدِم أداة Place Autocomplete Widget لتضمين واجهة مستخدم كاملة ومستقلة خاصة بميزة الإكمال التلقائي في صفحة الويب.
المتطلبات الأساسية
لاستخدام ميزة "الإكمال التلقائي" في Places API، يجب تفعيل "Places API (الجديدة)" في مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الاطّلاع على البدء.
الميزات الجديدة
تم تحسين ميزة "الإكمال التلقائي للأماكن" بالطرق التالية:
- تتيح واجهة مستخدم التطبيق المصغّر "الإكمال التلقائي" إمكانية التكيّف مع اللغة المحلية (بما في ذلك اللغات التي تُكتب من اليمين إلى اليسار)، وذلك بالنسبة إلى العنصر النائب لإدخال النص وشعار قائمة العبارات المقترَحة والعبارات المقترَحة الخاصة بالأماكن.
- تحسين إمكانية الوصول، بما في ذلك إتاحة استخدام قارئات الشاشة والتفاعل باستخدام لوحة المفاتيح
- تعرض أداة "الإكمال التلقائي" فئة المكان الجديدة لتسهيل التعامل مع العنصر الذي تم عرضه.
- تحسين التوافق مع الأجهزة الجوّالة والشاشات الصغيرة
- أداء أفضل ومظهر رسومي محسّن
إضافة أداة الإكمال التلقائي
تنشئ أداة Autocomplete عنصرًا لواجهة المستخدم لإدخال النص، وتوفّر توقعات حول الأماكن في قائمة اختيار ضمن واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لنقرة المستخدم باستخدام أداة الاستماع gmp-select
. يوضّح لك هذا القسم كيفية إضافة أداة الإكمال التلقائي إلى صفحة ويب أو خريطة Google.
إضافة أداة الإكمال التلقائي إلى صفحة ويب
لإضافة أداة الإكمال التلقائي إلى صفحة ويب، أنشئ google.maps.places.PlaceAutocompleteElement
جديدًا، وأضِفه إلى الصفحة كما هو موضّح في المثال التالي:
TypeScript
// Request needed libraries. await google.maps.importLibrary("places") as google.maps.PlacesLibrary; // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore document.body.appendChild(placeAutocomplete);
JavaScript
// Request needed libraries. await google.maps.importLibrary("places"); // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore document.body.appendChild(placeAutocomplete);
الاطّلاع على مثال الرمز الكامل
إضافة أداة Autocomplete إلى خريطة
إذا كان عنوان الفوترة خارج المنطقة الاقتصادية الأوروبية (EEA)، يمكنك أيضًا استخدام أداة "الإكمال التلقائي" مع "خريطة Google".
لإضافة أداة Autocomplete إلى خريطة، أنشئ مثيلاً جديدًا من google.maps.places.PlaceAutocompleteElement
، وألحِق PlaceAutocompleteElement
بـ div
، ثم أضِفه إلى الخريطة كعنصر تحكّم مخصّص، كما هو موضّح في المثال التالي:
TypeScript
//@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = 'place-autocomplete-input'; placeAutocomplete.locationBias = center; const card = document.getElementById('place-autocomplete-card') as HTMLElement; //@ts-ignore card.appendChild(placeAutocomplete); map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
JavaScript
//@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = 'place-autocomplete-input'; placeAutocomplete.locationBias = center; const card = document.getElementById('place-autocomplete-card'); //@ts-ignore card.appendChild(placeAutocomplete); map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
الاطّلاع على مثال الرمز الكامل
تقييد عبارات البحث المقترَحة من ميزة "الإكمال التلقائي"
تعرض خدمة "الإكمال التلقائي للأماكن" تلقائيًا جميع أنواع الأماكن، مع إعطاء الأولوية للتوقّعات القريبة من الموقع الجغرافي للمستخدم، وتستردّ جميع حقول البيانات المتاحة للمكان الذي اختاره المستخدم. اضبط PlaceAutocompleteElementOptions لعرض المزيد من النتائج المطابقة، وذلك عن طريق حصر النتائج أو تحسينها.
يؤدي حصر النتائج إلى تجاهل أداة الإكمال التلقائي لأي نتائج خارج منطقة الحصر. من الممارسات الشائعة حصر النتائج في حدود الخريطة. يؤدي تحيز النتائج إلى عرض أداة الإكمال التلقائي لنتائج ضمن المنطقة المحدّدة، ولكن قد تكون بعض النتائج المطابقة خارج هذه المنطقة.
في حال عدم توفير أي حدود أو إطار عرض للخريطة، ستحاول واجهة برمجة التطبيقات رصد الموقع الجغرافي للمستخدم من عنوان IP الخاص به، وستركّز النتائج على هذا الموقع الجغرافي. اضبط حدودًا كلما أمكن ذلك. بخلاف ذلك، قد يتلقّى مستخدمون مختلفون توقّعات مختلفة. بالإضافة إلى ذلك، لتحسين التوقعات بشكل عام، من المهم توفير إطار عرض معقول، مثل إطار العرض الذي تحدّده من خلال تحريك الخريطة أو تكبيرها أو تصغيرها، أو إطار العرض الذي يحدّده المطوّر استنادًا إلى الموقع الجغرافي للجهاز ونصف القطر. عندما لا يتوفّر نطاق جغرافي، يُعدّ 5 كيلومترات قيمة تلقائية مناسبة لميزة "الإكمال التلقائي للمكان". لا تضبط إطار عرض بنصف قطر يساوي صفرًا (نقطة واحدة)، أو إطار عرض يبلغ عرضه بضعة أمتار فقط (أقل من 100 متر)، أو إطار عرض يمتد على مستوى العالم.
حصر البحث عن الأماكن حسب البلد
لحصر البحث عن الأماكن في بلد واحد أو أكثر، استخدِم السمة includedRegionCodes
لتحديد رموز البلدان كما هو موضّح في المقتطف التالي:
const pac = new google.maps.places.PlaceAutocompleteElement({ includedRegionCodes: ['us', 'au'], });
حصر البحث عن الأماكن ضمن حدود الخريطة
لتقييد البحث عن الأماكن ضمن حدود خريطة معيّنة، استخدِم السمة locationRestrictions
لإضافة الحدود، كما هو موضّح في المقتطف التالي:
const pac = new google.maps.places.PlaceAutocompleteElement({ locationRestriction: map.getBounds(), });
عند حصر النتائج في حدود الخريطة، احرص على إضافة أداة معالجة لتعديل الحدود عند تغييرها:
map.addListener('bounds_changed', () => { autocomplete.locationRestriction = map.getBounds(); });
لإزالة locationRestriction
، اضبطها على null
.
الانحياز في نتائج البحث عن الأماكن
يمكنك إعطاء الأولوية لنتائج البحث عن الأماكن في منطقة دائرية من خلال استخدام السمة locationBias
وتمرير نصف القطر، كما هو موضّح هنا:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({ locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}}, });
لإزالة locationBias
، اضبطها على null
.
حصر نتائج البحث عن الأماكن على أنواع معيّنة
يمكنك حصر نتائج البحث عن الأماكن بأنواع معيّنة من الأماكن باستخدام السمة includedPrimaryTypes
وتحديد نوع واحد أو أكثر، كما هو موضّح هنا:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({ includedPrimaryTypes: ['establishment'], });
للحصول على قائمة كاملة بالأنواع المتوافقة، راجِع جدولَي أنواع الأماكن A وB.
الحصول على تفاصيل المكان
للحصول على تفاصيل المكان المحدّد، أضِف أداة معالجة gmp-select
إلى PlaceAutocompleteElement
، كما هو موضّح في المثال التالي:
TypeScript
// Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); selectedPlaceTitle.textContent = 'Selected Place:'; selectedPlaceInfo.textContent = JSON.stringify( place.toJSON(), /* replacer */ null, /* space */ 2); });
JavaScript
// Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); selectedPlaceTitle.textContent = 'Selected Place:'; selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2); });
الاطّلاع على مثال الرمز الكامل
في المثال السابق، يعرض معالج الأحداث عنصرًا من فئة المكان.
اتّصِل بالرقم place.fetchFields()
للحصول على حقول البيانات الخاصة بطلب "تفاصيل المكان" اللازمة لتطبيقك.
يطلب المستمع في المثال التالي معلومات عن مكان معيّن ويعرضها على خريطة.
TypeScript
// Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); // If the place has a geometry, then present it on a map. if (place.viewport) { map.fitBounds(place.viewport); } else { map.setCenter(place.location); map.setZoom(17); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place.displayName + '</span><br />' + '<span id="place-address">' + place.formattedAddress + '</span>' + '</div>'; updateInfoWindow(content, place.location); marker.position = place.location; });
JavaScript
// Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); // If the place has a geometry, then present it on a map. if (place.viewport) { map.fitBounds(place.viewport); } else { map.setCenter(place.location); map.setZoom(17); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place.displayName + '</span><br />' + '<span id="place-address">' + place.formattedAddress + '</span>' + '</div>'; updateInfoWindow(content, place.location); marker.position = place.location; });
الاطّلاع على مثال الرمز الكامل
أمثلة على الخرائط
يحتوي هذا القسم على الرمز الكامل للخرائط النموذجية المعروضة في هذه الصفحة.
عنصر الإكمال التلقائي
يضيف هذا المثال أداة Autocomplete إلى صفحة ويب، ويعرض النتائج لكل مكان تم اختياره.
TypeScript
async function initMap(): Promise<void> { // Request needed libraries. await google.maps.importLibrary("places") as google.maps.PlacesLibrary; // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore document.body.appendChild(placeAutocomplete); // Inject HTML UI. const selectedPlaceTitle = document.createElement('p'); selectedPlaceTitle.textContent = ''; document.body.appendChild(selectedPlaceTitle); const selectedPlaceInfo = document.createElement('pre'); selectedPlaceInfo.textContent = ''; document.body.appendChild(selectedPlaceInfo); // Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); selectedPlaceTitle.textContent = 'Selected Place:'; selectedPlaceInfo.textContent = JSON.stringify( place.toJSON(), /* replacer */ null, /* space */ 2); }); } initMap();
JavaScript
async function initMap() { // Request needed libraries. await google.maps.importLibrary("places"); // Create the input HTML element, and append it. //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore document.body.appendChild(placeAutocomplete); // Inject HTML UI. const selectedPlaceTitle = document.createElement('p'); selectedPlaceTitle.textContent = ''; document.body.appendChild(selectedPlaceTitle); const selectedPlaceInfo = document.createElement('pre'); selectedPlaceInfo.textContent = ''; document.body.appendChild(selectedPlaceInfo); // Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); selectedPlaceTitle.textContent = 'Selected Place:'; selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2); }); } initMap();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } p { font-family: Roboto, sans-serif; font-weight: bold; }
HTML
<html> <head> <title>Place Autocomplete element</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p style="font-family: roboto, sans-serif">Search for a place here:</p> <!-- prettier-ignore --> <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))}) ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script> </body> </html>
تجربة عيّنة
خريطة الإكمال التلقائي
يوضّح لك هذا المثال كيفية إضافة أداة Autocomplete إلى خريطة Google.
TypeScript
let map: google.maps.Map; let marker: google.maps.marker.AdvancedMarkerElement; let infoWindow: google.maps.InfoWindow; let center = { lat: 40.749933, lng: -73.98633 }; // New York City async function initMap(): Promise<void> { // Request needed libraries. //@ts-ignore const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([ google.maps.importLibrary("marker"), google.maps.importLibrary("places") ]); // Initialize the map. map = new google.maps.Map(document.getElementById('map') as HTMLElement, { center, zoom: 13, mapId: '4504f8b37365c3d0', mapTypeControl: false, }); //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = 'place-autocomplete-input'; placeAutocomplete.locationBias = center; const card = document.getElementById('place-autocomplete-card') as HTMLElement; //@ts-ignore card.appendChild(placeAutocomplete); map.controls[google.maps.ControlPosition.TOP_LEFT].push(card); // Create the marker and infowindow. marker = new google.maps.marker.AdvancedMarkerElement({ map, }); infoWindow = new google.maps.InfoWindow({}); // Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); // If the place has a geometry, then present it on a map. if (place.viewport) { map.fitBounds(place.viewport); } else { map.setCenter(place.location); map.setZoom(17); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place.displayName + '</span><br />' + '<span id="place-address">' + place.formattedAddress + '</span>' + '</div>'; updateInfoWindow(content, place.location); marker.position = place.location; }); } // Helper function to create an info window. function updateInfoWindow(content, center) { infoWindow.setContent(content); infoWindow.setPosition(center); infoWindow.open({ map, anchor: marker, shouldFocus: false, }); } initMap();
JavaScript
let map; let marker; let infoWindow; let center = { lat: 40.749933, lng: -73.98633 }; // New York City async function initMap() { // Request needed libraries. //@ts-ignore const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([ google.maps.importLibrary("marker"), google.maps.importLibrary("places") ]); // Initialize the map. map = new google.maps.Map(document.getElementById('map'), { center, zoom: 13, mapId: '4504f8b37365c3d0', mapTypeControl: false, }); //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = 'place-autocomplete-input'; placeAutocomplete.locationBias = center; const card = document.getElementById('place-autocomplete-card'); //@ts-ignore card.appendChild(placeAutocomplete); map.controls[google.maps.ControlPosition.TOP_LEFT].push(card); // Create the marker and infowindow. marker = new google.maps.marker.AdvancedMarkerElement({ map, }); infoWindow = new google.maps.InfoWindow({}); // Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); // If the place has a geometry, then present it on a map. if (place.viewport) { map.fitBounds(place.viewport); } else { map.setCenter(place.location); map.setZoom(17); } let content = '<div id="infowindow-content">' + '<span id="place-displayname" class="title">' + place.displayName + '</span><br />' + '<span id="place-address">' + place.formattedAddress + '</span>' + '</div>'; updateInfoWindow(content, place.location); marker.position = place.location; }); } // Helper function to create an info window. function updateInfoWindow(content, center) { infoWindow.setContent(content); infoWindow.setPosition(center); infoWindow.open({ map, anchor: marker, shouldFocus: false, }); } initMap();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } #place-autocomplete-card { background-color: #fff; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px; margin: 10px; padding: 5px; font-family: Roboto, sans-serif; font-size: large; font-weight: bold; } gmp-place-autocomplete { width: 300px; } #infowindow-content .title { font-weight: bold; } #map #infowindow-content { display: inline; }
HTML
<html> <head> <title>Place Autocomplete map</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div class="place-autocomplete-card" id="place-autocomplete-card"> <p>Search for a place here:</p> </div> <div id="map"></div> <!-- prettier-ignore --> <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))}) ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script> </body> </html>
تجربة عيّنة
استخدام مكوّن "أداة اختيار الأماكن"
مكوّن "أداة اختيار المكان" هو حقل إدخال نصي يتيح للمستخدمين النهائيين البحث عن عنوان أو مكان محدّد باستخدام ميزة "الإكمال التلقائي". وهي جزء من مكتبة المكوّنات الموسّعة، وهي مجموعة من مكوّنات الويب التي تساعد المطوّرين في إنشاء خرائط وميزات مواقع جغرافية أفضل بشكل أسرع.
استخدِم أداة ضبط Place Picker لإنشاء رمز قابل للتضمين لمكوّن Place Picker مخصّص، ثمّ يمكنك تصديره لاستخدامه مع أُطر العمل الشائعة، مثل React وAngular، أو بدون أي إطار عمل.