ویجت تکمیل خودکار مکان یک فیلد ورودی متن ایجاد میکند، پیشبینیهای مکان را در فهرست انتخاب رابط کاربری ارائه میکند، و جزئیات مکان را در پاسخ به انتخاب کاربر برمیگرداند. از ویجت تکمیل خودکار مکان برای جاسازی یک رابط کاربری کامل خودکار مستقل در صفحه وب خود استفاده کنید.
پیش نیازها
برای استفاده از Place Autocomplete (پیش نمایش)، باید "Places API" را در پروژه Google Cloud خود فعال کنید و کانال بتا ( v: "beta"
) را در بوت استرپ لودر خود مشخص کنید. برای جزئیات بیشتر به شروع به کار مراجعه کنید.
تازه چه خبر
تکمیل خودکار مکان (پیش نمایش) به روش های زیر بهبود یافته است:
- رابط کاربری ویجت تکمیل خودکار از محلیسازی منطقهای (از جمله زبانهای RTL) برای مکانگردان ورودی متن، نشانواره فهرست پیشبینیها و پیشبینیهای مکان پشتیبانی میکند.
- دسترسی پیشرفته، از جمله پشتیبانی از صفحهخوانها و تعامل با صفحهکلید.
- ویجت Autocomplete کلاس Place جدید را برمی گرداند تا مدیریت شیء برگشتی را ساده کند.
- پشتیبانی بهتر از دستگاه های تلفن همراه و صفحه نمایش های کوچک.
- عملکرد بهتر و ظاهر گرافیکی بهبود یافته.
یک ویجت تکمیل خودکار اضافه کنید
می توانید یک ویجت تکمیل خودکار را به یک صفحه وب یا نقشه گوگل اضافه کنید. ویجت تکمیل خودکار یک فیلد ورودی متن ایجاد میکند، پیشبینیهای مکان را در فهرست انتخاب رابط کاربری ارائه میکند، و جزئیات مکان را در پاسخ به کلیک کاربر از طریق شنونده gmp-placeselect
برمیگرداند. این بخش به شما نشان می دهد که چگونه یک ویجت تکمیل خودکار را به یک صفحه وب یا نقشه گوگل اضافه کنید.
یک ویجت تکمیل خودکار را به یک صفحه وب اضافه کنید
برای افزودن ویجت تکمیل خودکار به یک صفحه وب، یک google.maps.places.PlaceAutocompleteElement
جدید ایجاد کنید و همانطور که در مثال زیر نشان داده شده است آن را به صفحه اضافه کنید:
TypeScript
// Request needed libraries. //@ts-ignore 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);
جاوا اسکریپت
// Request needed libraries. //@ts-ignore 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);
ویجت تکمیل خودکار را به نقشه اضافه کنید
برای افزودن یک ویجت تکمیل خودکار به نقشه، یک نمونه جدید google.maps.places.PlaceAutocompleteElement
ایجاد کنید، PlaceAutocompleteElement
به یک div
اضافه کنید و آن را به عنوان یک کنترل سفارشی روی نقشه فشار دهید، همانطور که در مثال زیر نشان داده شده است:
TypeScript
//@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = 'place-autocomplete-input'; const card = document.getElementById('place-autocomplete-card') as HTMLElement; //@ts-ignore card.appendChild(placeAutocomplete); map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
جاوا اسکریپت
//@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = "place-autocomplete-input"; const card = document.getElementById("place-autocomplete-card"); //@ts-ignore card.appendChild(placeAutocomplete); map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
پیش بینی های تکمیل خودکار را محدود کنید
بهطور پیشفرض، «تکمیل خودکار مکان» همه انواع مکانها را ارائه میکند که برای پیشبینیهای نزدیک به مکان کاربر تعصب دارند و همه فیلدهای داده موجود را برای مکان انتخابی کاربر واکشی میکند. گزینههای تکمیل خودکار مکان را برای ارائه پیشبینیهای مرتبطتر، با محدود کردن یا سوگیری نتایج، تنظیم کنید.
محدود کردن نتایج باعث میشود که ویجت تکمیل خودکار نتایجی را که خارج از محدوده محدودیت هستند نادیده بگیرد. یک روش معمول محدود کردن نتایج به محدوده نقشه است. نتایج بایاس باعث می شود که ویجت تکمیل خودکار نتایج را در محدوده مشخص شده نشان دهد، اما برخی از موارد منطبق ممکن است خارج از آن منطقه باشند.
جستجوی مکان را بر اساس کشور محدود کنید
برای محدود کردن جستجوی مکان به یک یا چند کشور خاص، از ویژگی componentRestrictions
برای تعیین کد(های) کشور همانطور که در قطعه زیر نشان داده شده است استفاده کنید:
const pac = new google.maps.places.PlaceAutocompleteElement({ componentRestrictions: {country: ['us', 'au']}, });
جستجوی مکان را به محدوده نقشه محدود کنید
برای محدود کردن جستجوی مکان به محدودههای نقشه، از ویژگی locationRestrictions
برای اضافه کردن محدودهها استفاده کنید، همانطور که در قطعه زیر نشان داده شده است:
const pac = new google.maps.places.PlaceAutocompleteElement({ locationRestriction: map.getBounds(), });
وقتی محدودیتهای نقشه را محدود میکنید، حتماً شنوندهای اضافه کنید تا زمانی که محدودهها تغییر میکنند، آنها را بهروزرسانی کند:
map.addListener('bounds_changed', () => { autocomplete.locationRestriction = map.getBounds(); });
برای حذف locationRestriction
، آن را روی null
قرار دهید.
نتایج جستجوی مکان سوگیری
Bias نتایج جستجو را با استفاده از ویژگی locationBias
و عبور از یک شعاع در یک ناحیه دایره ای قرار می دهد، همانطور که در اینجا نشان داده شده است:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({ locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}}, });
برای حذف locationBias
، آن را روی null
قرار دهید.
نتایج جستجوی مکان را به انواع خاصی محدود کنید
نتایج جستجوی مکان را به انواع خاصی از مکانها با استفاده از types
محدود کنید و یک یا چند نوع را مشخص کنید، همانطور که در اینجا نشان داده شده است:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({ types: ['establishment'], });
برای فهرست کامل انواع پشتیبانی شده، جدول 3: انواع پشتیبانی شده در درخواست های تکمیل خودکار را ببینید.
جزئیات مکان را دریافت کنید
برای دریافت جزئیات مکان برای مکان انتخاب شده، یک شنونده gmp-place-select
به PlaceAutocompleteElement
اضافه کنید، همانطور که در مثال زیر نشان داده شده است:
TypeScript
// Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => { await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); selectedPlaceTitle.textContent = 'Selected Place:'; selectedPlaceInfo.textContent = JSON.stringify( place.toJSON(), /* replacer */ null, /* space */ 2); });
جاوا اسکریپت
// Add the gmp-placeselect listener, and display the results. //@ts-ignore placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => { await place.fetchFields({ fields: ["displayName", "formattedAddress", "location"], }); selectedPlaceTitle.textContent = "Selected Place:"; selectedPlaceInfo.textContent = JSON.stringify( place.toJSON(), /* replacer */ null, /* space */ 2, ); });
در مثال قبل، شنونده رویداد یک شی از کلاس Place را برمی گرداند. با place.fetchFields()
را برای دریافت فیلدهای داده Place Details مورد نیاز برای برنامه خود فراخوانی کنید.
شنونده در مثال بعدی اطلاعات مکان را درخواست می کند و آن را روی نقشه نمایش می دهد.
TypeScript
// Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => { 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; });
جاوا اسکریپت
// Add the gmp-placeselect listener, and display the results on the map. //@ts-ignore placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => { 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; });
نتایج کدگذاری جغرافیایی را برای مکان انتخاب شده دریافت کنید
برای دریافت نتایج کدگذاری جغرافیایی برای مکان انتخاب شده، از google.maps.Geocoder
برای دریافت مکان استفاده کنید، همانطور که در قطعه زیر نشان داده شده است:
const map = new google.maps.Map(document.getElementById('map'), { center: {lat: 50.064192, lng: -130.605469}, zoom: 3, }); const marker = new google.maps.Marker({map}); const autocomplete = new google.maps.places.PlaceAutocompleteElement(); const geocoder = new google.maps.Geocoder(); autocomplete.addListener('gmp-placeselect', async ({prediction: place}) => { const results = await geocoder.geocode({place.id}); marker.setPlace({ placeId: place.id, location: results[0].geometry.location, }); });
نمونه نقشه ها
این بخش شامل کد کامل برای نمونه نقشه های ارائه شده در این صفحه است.
عنصر تکمیل خودکار
این مثال یک ویجت تکمیل خودکار را به یک صفحه وب اضافه می کند و نتایج را برای هر مکان انتخاب شده نمایش می دهد.
TypeScript
async function initMap(): Promise<void> { // Request needed libraries. //@ts-ignore 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-placeselect', async ({ place }) => { await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] }); selectedPlaceTitle.textContent = 'Selected Place:'; selectedPlaceInfo.textContent = JSON.stringify( place.toJSON(), /* replacer */ null, /* space */ 2); }); } initMap();
جاوا اسکریپت
async function initMap() { // Request needed libraries. //@ts-ignore 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-placeselect", async ({ place }) => { 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script> </body> </html>
Sample را امتحان کنید
تکمیل خودکار نقشه
این مثال به شما نشان می دهد که چگونه یک ویجت تکمیل خودکار را به نقشه گوگل اضافه کنید.
TypeScript
let map: google.maps.Map; let marker: google.maps.marker.AdvancedMarkerElement; let infoWindow: google.maps.InfoWindow; 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: { lat: 40.749933, lng: -73.98633 }, zoom: 13, mapId: '4504f8b37365c3d0', mapTypeControl: false, }); //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = 'place-autocomplete-input'; 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-placeselect', async ({ place }) => { 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();
جاوا اسکریپت
let map; let marker; let infoWindow; 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: { lat: 40.749933, lng: -73.98633 }, zoom: 13, mapId: "4504f8b37365c3d0", mapTypeControl: false, }); //@ts-ignore const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(); //@ts-ignore placeAutocomplete.id = "place-autocomplete-input"; 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-placeselect", async ({ place }) => { 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script> </body> </html>
Sample را امتحان کنید
از مولفه Place Picker استفاده کنید
توجه: این نمونه از یک کتابخانه متن باز استفاده می کند. برای پشتیبانی و بازخورد مربوط به کتابخانه به README مراجعه کنید.
جزء انتخابگر مکان یک ورودی متنی است که به کاربران نهایی امکان می دهد آدرس یا مکان خاصی را با استفاده از تکمیل خودکار جستجو کنند. این بخشی از Extended Component Library، مجموعهای از اجزای وب است که به توسعهدهندگان کمک میکند تا نقشهها و ویژگیهای مکان بهتر را سریعتر بسازند.
پیکربندی Place Picker
از پیکربندی برای ایجاد کد قابل جاسازی برای کامپوننت Place Picker سفارشی استفاده کنید، سپس آن را صادر کنید تا با فریم ورک های محبوبی مانند React و Angular یا اصلاً فریمورک استفاده نشود.
شروع کنید
برای شروع، کتابخانه Extended Component را با npm بارگیری کنید.
برای بهترین عملکرد، از یک مدیریت بسته استفاده کنید و فقط اجزای مورد نیاز خود را وارد کنید. این بسته در npm با نام @googlemaps/extended-component-library فهرست شده است. نصبش کن با:
npm i @googlemaps/extended-component-library;
سپس هر مؤلفه ای را که در برنامه خود استفاده می کنید وارد کنید.
import '@googlemaps/extended-component-library/place_picker.js';
پس از بارگیری کتابخانه npm، یک کلید API از کنسول Cloud دریافت کنید .
<gmpx-api-loader key="YOUR_API_KEY" solution-channel="GMP_DOCS_placepicker_v1"></gmpx-api-loader>
از تگ جزء انتخابگر مکان استفاده کنید.
<gmpx-place-picker placeholder="Enter a place" id="place-picker" style="width: 100%"> </gmpx-place-picker>
برای جزئیات بیشتر، GitHub یا npm را بررسی کنید. برای دیدن اجزای مورد استفاده در کد نمونه، صفحه نمونه ها را در GitHub بررسی کنید.