«ابزارک تکمیل خودکار مکان» فیلد ورودی نوشتاری ایجاد میکند، پیشبینیهای مکان را در فهرست انتخاب واسط کاربر ارائه میدهد، و جزئیات مکان را در پاسخ به انتخاب کاربر برمیگرداند. از «ابزارک تکمیل خودکار مکان» برای جاسازی کردن میانای کاربر تکمیل خودکار کامل و خوداتکا در صفحه وب استفاده کنید. برای مرجع کامل
میانای برنامهسازی کاربردی،
PlaceAutocompleteElement را ببینید.
پیشنیازها
برای استفاده از «تکمیل خودکار جا»، باید Places API (جدید) را در پروژه Google Cloud خود فعال کنید. برای جزئیات، به شروع به کار بروید.
ویژگیهای جدید
«تکمیل خودکار جا» به روشهای زیر بهبود یافته است:
- میانای کاربری ابزارک «تکمیل خودکار» از بومیسازی منطقهای (ازجمله زبانهای راستبهچپ) برای جایبان ورودی نوشتاری، نشانواره فهرست پیشبینیها، و پیشبینیهای مکان پشتیبانی میکند.
- دسترسپذیری بهبودیافته، ازجمله پشتیبانی از صفحهخوانها و تعامل با صفحهکلید.
- ابزاره «تکمیل خودکار»
کلاس مکان
(
Placeمرجع) جدید را برمیگرداند تا مدیریت شیء برگشتی را ساده کند. - پشتیبانی بهتر از دستگاههای همراه و صفحهنمایشهای کوچک.
- عملکرد بهتر و ظاهر گرافیکی بهبودیافته.
افزودن ابزاره «تکمیل خودکار»
ابزاره «تکمیل خودکار» فیلد ورودی نوشتاری ایجاد میکند، پیشبینیهای مکان را در فهرست انتخاب واسط کاربر ارائه میدهد، و جزئیات مکان را در پاسخ به کلیک کاربر بااستفاده از شنونده gmp-select برمیگرداند. این بخش نحوه افزودن ابزاره تکمیل خودکار به صفحه وب یا نقشه Google را نشان میدهد.
افزودن ابزاره «تکمیل خودکار» به صفحه وب
برای افزودن ابزارک «تکمیل خودکار» به صفحه وب،
google.maps.places.PlaceAutocompleteElement جدیدی ایجاد کنید
و آن را همانطور که در مثال زیر نشان داده شده است به صفحه اضافه کنید:
TypeScript
// Request needed libraries. const { PlaceAutocompleteElement } = await google.maps.importLibrary('places'); // Create the input HTML element, and append it. const placeAutocomplete = new PlaceAutocompleteElement(); document.body.appendChild(placeAutocomplete);
JavaScript
// Request needed libraries. const { PlaceAutocompleteElement } = await google.maps.importLibrary('places'); // Create the input HTML element, and append it. const placeAutocomplete = new PlaceAutocompleteElement(); document.body.appendChild(placeAutocomplete);
افزودن ابزاره «تکمیل خودکار» به نقشه
اگر نشانی صورتحساب شما خارج از منطقه اقتصادی اروپا (EEA) باشد، میتوانید از ابزارک «تکمیل خودکار» با «نقشه Google» نیز استفاده کنید.
برای افزودن ابزارک «تکمیل خودکار» به نقشه، ابتدا کتابخانههای موردنیاز را درخواست کنید، همانطور که در اینجا نشان داده شده است:
// In your TS or JS, request the needed libraries. const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");
سپس در HTML، عنصر gmp-place-autocomplete جدیدی را در
div قرار دهید و آن div را در gmp-map قرار دهید، همانطور که در
مثال زیر نشان داده شده است:
<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
<div
class="place-autocomplete-card"
slot="control-inline-start-block-start">
<gmp-place-autocomplete
placeholder="Search for a place..."></gmp-place-autocomplete>
</div>
</gmp-map>برای افزودن ابزاره «تکمیل خودکار» به نقشه بهصورت برنامهنویسیشده، یک نمونه جدید
google.maps.places.PlaceAutocompleteElement
ایجاد کنید،
PlaceAutocompleteElement
را به div اضافه کنید، و مشخصه slot را به
div اعمال کنید، همانطور که در مثال زیر نشان داده شده است:
// In your TS or JS, request the needed libraries. const { PlaceAutocompleteElement } = await google.maps.importLibrary("places"); // Get the map element. const mapElement = document.querySelector('gmp-map') as google.maps.MapElement; // Create the PlaceAutocompleteElement instance. const placeAutocomplete = new PlaceAutocompleteElement({}); // Create a div and append the PlaceAutocompleteElement to it. const card = document.createElement("div"); card.appendChild(placeAutocomplete); // Apply the slot attribute to the div. // This positions the control in the top-left corner of the map. card.setAttribute("slot", "control-inline-start-block-start"); // Append the div to the map element (check for null). if (mapElement) { mapElement.appendChild(card); }
افزودن نوشتار جایبان
از خصوصیت
placeholder
برای افزودن نوشتار جایبان استفاده کنید. مثال زیر تنظیم نوشتار جایبان را در HTML نشان میدهد:
<gmp-place-autocomplete placeholder="Search for a place..." ></gmp-place-autocomplete>
همچنین میتوانید نوشتار جایبان را بهصورت برنامهریزیشده تنظیم کنید:
placeAutocomplete.placeholder = 'Search for a place...';
محدود کردن پیشبینیهای «تکمیل خودکار»
بهطور پیشفرض، «تکمیل خودکار مکان» همه انواع مکان را ارائه میدهد و پیشبینیهای نزدیک به مکان کاربر را اولویت میدهد و همه فیلدهای داده دردسترس را برای مکان انتخابشده کاربر واکشی میکند. با محدود کردن یا سوگیری نتایج،
PlaceAutocompleteElementOptions
را برای ارائه پیشبینیهای مرتبطتر تنظیم کنید.
محدود کردن نتایج باعث میشود ابزاره «تکمیل خودکار» هر نتیجهای را که خارج از منطقه محدودشده باشد نادیده بگیرد. یک رویه معمول این است که نتایج را به محدوده نقشه محدود کنیم. سوگیری نتایج باعث میشود ابزاره «تکمیل خودکار» نتایج را در منطقه مشخصشده نشان دهد، اما برخیاز موارد منطبق ممکن است خارج از آن منطقه باشد.
اگر هیچ محدوده یا نمای نقشه ارائه نکنید، API تلاش میکند مکان کاربر را از نشانی IP او تشخیص دهد و نتایج را به آن مکان متمایل میکند. هرزمان ممکن بود، محدوده تنظیم کنید. درغیراینصورت، ممکن است کاربران مختلف پیشبینیهای متفاوتی دریافت کنند. همچنین، برای بهبود کلی پیشبینیها، مهم است که نمای معقولی ارائه دهید، مانند نمایی که با حرکت دادن یا بزرگنمایی روی نقشه تنظیم میکنید، یا نمای تنظیمشده توسط توسعهدهنده براساس مکان و شعاع دستگاه. وقتی شعاع دردسترس نباشد، ۵ کیلومتر بهعنوان پیشفرض منطقی برای «تکمیل خودکار مکان» درنظر گرفته میشود. نمای هدف را با شعاع صفر (یک نقطه)، نمای هدفی که فقط چند متر عرض دارد (کمتر از ۱۰۰ متر)، یا نمای هدفی که کل جهان را دربرمیگیرد تنظیم نکنید.
محدود کردن جستجوی مکان براساس کشور
برای محدود کردن جستجوی مکان به یک یا چند کشور خاص، از
دارایی includedRegionCodes
برای مشخص کردن کد(های) کشور همانطور که در گزیده زیر نشان داده شده است استفاده کنید
(این گزیده فرض میکند که قبلاً نمونهای بهنام
placeAutocomplete ایجاد کردهاید):
placeAutocomplete.includedRegionCodes = ['us', 'au'];;
محدود کردن جستجوی مکان به مرزهای نقشه
برای محدود کردن جستجوی مکان به محدوده نقشه، از
locationRestriction
دارایی استفاده کنید. قطعه کد زیر نحوه افزودن شنونده برای بهروزرسانی مرزها را هنگام تغییر آنها نشان میدهد:
// Use the bounds_changed event to restrict results to the current map bounds. google.maps.event.addListener(innerMap, 'bounds_changed', async () => { placeAutocomplete.locationRestriction = innerMap.getBounds(); });
برای برداشتن
locationRestriction،
آن را روی null تنظیم کنید.
نتایج جستجوی مکان سوگیری
بااستفاده از ویژگی
locationBias
، نتایج جستجوی مکان را به یک منطقه دایرهای محدود کنید، همانطور که در اینجا نشان داده شده است:
placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};
برای برداشتن
locationBias،
آن را روی null تنظیم کنید.
محدود کردن نتایج جستجوی مکان به انواع خاص
نتایج جستجوی مکان را بااستفاده از ویژگی
includedPrimaryTypes
و مشخص کردن یک یا چند نوع، همانطور که در اینجا نشان داده شده است، به انواع خاصی از مکانها محدود کنید:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({ includedPrimaryTypes: ['establishment'], });
برای فهرست کامل انواع پشتیبانیشده، جدولهای نوع مکان الف و ب را ببینید.
دریافت جزئیات مکان
برای دریافت جزئیات مکان برای مکان انتخابشده،
gmp-select
شنونده را به
PlaceAutocompleteElement
اضافه کنید، همانطور که در مثال زیر نشان داده شده است:
TypeScript
// Add the gmp-select listener, and display the results. placeAutocomplete.addEventListener( 'gmp-select', async ({ placePrediction, }: google.maps.places.PlacePredictionSelectEvent) => { 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-select listener, and display the results. 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 ); } );
در مثال قبلی، شنونده رویداد
PlacePredictionSelectEvent
را دریافت میکند و
placePrediction.toPlace()
را فرا میخواند تا نمونهای از
کلاس مکان
(مرجع Place
) را دریافت کند. برای دریافت
فیلدهای داده
«جزئیات مکان» موردنیاز برای برنامهتان،
place.fetchFields()
را فراخوانی کنید.
شنونده در مثال بعدی اطلاعات مکان را درخواست میکند و آن را در نقشه نمایش میدهد.
TypeScript
// Add the gmp-select listener, and display the results on the map. placeAutocomplete.addEventListener( 'gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: [ 'displayName', 'formattedAddress', 'location', 'viewport', ], }); // If the place has a geometry, then present it on a map. if (place.viewport) { innerMap.fitBounds(place.viewport); } else { innerMap.setCenter(place.location!); innerMap.setZoom(17); } const content = document.createElement('div'); const nameText = document.createElement('span'); nameText.textContent = place.displayName ?? 'No name'; content.appendChild(nameText); content.appendChild(document.createElement('br')); const addressText = document.createElement('span'); addressText.textContent = place.formattedAddress ?? 'No address'; content.appendChild(addressText); updateInfoWindow(content, place.location); marker.position = place.location; } );
JavaScript
// Add the gmp-select listener, and display the results on the map. placeAutocomplete.addEventListener( 'gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: [ 'displayName', 'formattedAddress', 'location', 'viewport', ], }); // If the place has a geometry, then present it on a map. if (place.viewport) { innerMap.fitBounds(place.viewport); } else { innerMap.setCenter(place.location); innerMap.setZoom(17); } const content = document.createElement('div'); const nameText = document.createElement('span'); nameText.textContent = place.displayName ?? 'No name'; content.appendChild(nameText); content.appendChild(document.createElement('br')); const addressText = document.createElement('span'); addressText.textContent = place.formattedAddress ?? 'No address'; content.appendChild(addressText); updateInfoWindow(content, place.location); marker.position = place.location; } );
نقشههای نمونه
این بخش حاوی کد کامل برای نقشههای نمونهای است که در این صفحه نشان داده شده است.
عنصر تکمیل خودکار
این مثال یک ابزاره «تکمیل خودکار» را به صفحه وب اضافه میکند و نتایج را برای هر مکان انتخابشده نمایش میدهد.
TypeScript
async function init(): Promise<void> { // Request needed libraries. const { PlaceAutocompleteElement } = await google.maps.importLibrary('places'); // Create the input HTML element, and append it. const placeAutocomplete = new PlaceAutocompleteElement(); 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-select listener, and display the results. placeAutocomplete.addEventListener( 'gmp-select', async ({ placePrediction, }: google.maps.places.PlacePredictionSelectEvent) => { 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 ); } ); } void init();
JavaScript
async function init() { // Request needed libraries. const { PlaceAutocompleteElement } = await google.maps.importLibrary('places'); // Create the input HTML element, and append it. const placeAutocomplete = new PlaceAutocompleteElement(); 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-select listener, and display the results. 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 ); } ); } void init();
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>
<script>
// prettier-ignore
(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: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<p style="font-family: roboto, sans-serif">Search for a place here:</p>
</body>
</html>نقشه تکمیل خودکار
این مثال به شما نشان میدهد که چگونه یک ابزاره «تکمیل خودکار» را به نقشه Google اضافه کنید.
TypeScript
const mapElement = document.querySelector('gmp-map')!; const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!; let innerMap: google.maps.Map; let marker: google.maps.marker.AdvancedMarkerElement; let infoWindow: google.maps.InfoWindow; async function init(): Promise<void> { // Request needed libraries. const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([ google.maps.importLibrary('marker'), google.maps.importLibrary('maps'), google.maps.importLibrary('places'), ]); // Get the inner map. innerMap = mapElement.innerMap; innerMap.setOptions({ mapTypeControl: false, }); // Use the bounds_changed event to restrict results to the current map bounds. innerMap.addListener('bounds_changed', () => { placeAutocomplete.locationRestriction = innerMap.getBounds()!; }); // Create the marker and infoWindow. marker = new AdvancedMarkerElement({ map: innerMap, }); infoWindow = new InfoWindow(); // Add the gmp-select listener, and display the results on the map. placeAutocomplete.addEventListener( 'gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: [ 'displayName', 'formattedAddress', 'location', 'viewport', ], }); // If the place has a geometry, then present it on a map. if (place.viewport) { innerMap.fitBounds(place.viewport); } else { innerMap.setCenter(place.location!); innerMap.setZoom(17); } const content = document.createElement('div'); const nameText = document.createElement('span'); nameText.textContent = place.displayName ?? 'No name'; content.appendChild(nameText); content.appendChild(document.createElement('br')); const addressText = document.createElement('span'); addressText.textContent = place.formattedAddress ?? 'No address'; content.appendChild(addressText); updateInfoWindow(content, place.location); marker.position = place.location; } ); } // Helper function to create an info window. function updateInfoWindow( content: string | Element | Text | null | undefined, center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined ) { infoWindow.setContent(content); infoWindow.setPosition(center); infoWindow.open({ map: innerMap, anchor: marker, shouldFocus: false, }); } void init();
JavaScript
const mapElement = document.querySelector('gmp-map'); const placeAutocomplete = document.querySelector('gmp-place-autocomplete'); let innerMap; let marker; let infoWindow; async function init() { // Request needed libraries. const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([ google.maps.importLibrary('marker'), google.maps.importLibrary('maps'), google.maps.importLibrary('places'), ]); // Get the inner map. innerMap = mapElement.innerMap; innerMap.setOptions({ mapTypeControl: false, }); // Use the bounds_changed event to restrict results to the current map bounds. innerMap.addListener('bounds_changed', () => { placeAutocomplete.locationRestriction = innerMap.getBounds(); }); // Create the marker and infoWindow. marker = new AdvancedMarkerElement({ map: innerMap, }); infoWindow = new InfoWindow(); // Add the gmp-select listener, and display the results on the map. placeAutocomplete.addEventListener( 'gmp-select', async ({ placePrediction }) => { const place = placePrediction.toPlace(); await place.fetchFields({ fields: [ 'displayName', 'formattedAddress', 'location', 'viewport', ], }); // If the place has a geometry, then present it on a map. if (place.viewport) { innerMap.fitBounds(place.viewport); } else { innerMap.setCenter(place.location); innerMap.setZoom(17); } const content = document.createElement('div'); const nameText = document.createElement('span'); nameText.textContent = place.displayName ?? 'No name'; content.appendChild(nameText); content.appendChild(document.createElement('br')); const addressText = document.createElement('span'); addressText.textContent = place.formattedAddress ?? 'No address'; content.appendChild(addressText); 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: innerMap, anchor: marker, shouldFocus: false, }); } void init();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ gmp-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: small; } 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>
<script>
// prettier-ignore
(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: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
<div
class="place-autocomplete-card"
slot="control-inline-start-block-start">
<gmp-place-autocomplete
placeholder="Search for a place..."></gmp-place-autocomplete>
</div>
</gmp-map>
</body>
</html>بهینهسازی تکمیل خودکار (جدید)
این بخش روالهای مطلوب را شرح میدهد تا به شما کمک کند بیشترین بهره را از سرویس «تکمیل خودکار» (جدید) ببرید.
در اینجا چند دستورالعمل کلی آمده است:
- سریعترین راه برای توسعه یک میانای کاربری کاربردی استفاده از ویجت تکمیل خودکار (جدید) در Maps JavaScript API، ویجت تکمیل خودکار (جدید) در Places SDK for Android، یا ویجت تکمیل خودکار (جدید) در Places SDK for iOS است.
- از همان ابتدا با فیلدهای داده ضروری «تکمیل خودکار» (جدید) آشنا شوید.
- فیلدهای «سوگیری مکان» و «محدودیت مکان» اختیاری هستند اما میتوانند تأثیر قابلتوجهی بر عملکرد تکمیل خودکار داشته باشند.
- از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامهسازی کاربردی خطایی برگرداند، برنامه شما بهخوبی تنزل پیدا میکند.
- مطمئن شوید که برنامهتان شرایطی را که هیچ انتخابی وجود ندارد مدیریت میکند و راهی برای ادامه دادن به کاربران ارائه میدهد.
روالهای مطلوب بهینهسازی هزینه
بهینهسازی هزینه پایه
برای بهینهسازی هزینه استفاده از سرویس «تکمیل خودکار (جدید)»، از ماسکهای فیلد در ابزارههای «جزئیات مکان (جدید)» و «تکمیل خودکار (جدید)» استفاده کنید تا فقط فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان برگردانده شود.
بهینهسازی پیشرفته هزینه
برای دسترسی به واحد نگهداری موجودی: قیمتگذاری درخواست تکمیل خودکار و درخواست نتایج Geocoding API درباره مکان انتخابشده بهجای «جزئیات مکان» (جدید)، پیادهسازی برنامهریزیشده «تکمیل خودکار» (جدید) را درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمتگذاری بهازای درخواست همراه با Geocoding API مقرونبهصرفهتر از قیمتگذاری بهازای جلسه (جلسهمحور) است:
- اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، «میانای برنامهسازی کاربردی زمینکدی» این اطلاعات را با هزینه کمتر از تماس «جزئیات مکان (جدید)» ارائه میدهد.
- اگر کاربران پیشبینی تکمیل خودکار را در میانگین چهار درخواست پیشبینی تکمیل خودکار (جدید) یا کمتر انتخاب کنند، قیمتگذاری بهازای هر درخواست میتواند مقرونبهصرفهتر از قیمتگذاری بهازای هر جلسه باشد.
آیا برنامه شما به اطلاعات دیگری غیراز نشانی و طول/عرض جغرافیایی پیشبینی انتخابی نیاز دارد؟
بله، به جزئیات بیشتری نیاز است
از «تکمیل خودکار» (جدید) مبتنی بر جلسه با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجاییکه برنامه شما به «جزئیات مکان (جدید)» مانند نام مکان، وضعیت کسبوکار،
یا ساعت کاری نیاز دارد، پیادهسازی شما از «تکمیل خودکار (جدید)» باید از کد جلسه استفاده کند
(بهصورت برنامهنویسیشده یا تعبیهشده در ابزارههای
JavaScript،
Android،
یا iOS)
بهازای هر جلسه بهعلاوه شناسههای یکتای کالای «مکانها»ی مربوطه،
بسته به اینکه کدام فیلدهای داده مکان را درخواست میکنید.۱
پیادهسازی ابزاره
مدیریت جلسه بهطور خودکار در ابزارههای
JavaScript،
Android،
یا iOS
ساخته میشود. این شامل درخواستهای «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید)
در پیشبینی انتخابشده میشود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط
فیلدهای داده «تکمیل خودکار (جدید)»
موردنیازتان را درخواست میکنید.
پیادهسازی برنامهریزیشده
از
کد جلسه
با درخواستهای «تکمیل خودکار» (جدید) استفاده کنید. هنگام درخواست «جزئیات مکان (جدید)» درباره پیشبینی انتخابشده، پارامترهای زیر را اضافه کنید:
- شناسه مکان از پاسخ «تکمیل خودکار (جدید)»
- کد جلسه استفادهشده در درخواست «تکمیل خودکار (جدید)»
- پارامتر
fieldsکه فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان را مشخص میکند
نه، فقط به نشانی و مکان نیاز دارد
Geocoding API میتواند گزینه مقرونبهصرفهتری نسبتبه Place Details (New) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Autocomplete (New). کارایی «تکمیل خودکار (جدید)» هر برنامه بسته به آنچه کاربران وارد میکنند، جایی که برنامه استفاده میشود، و اینکه آیا روالهای مطلوب بهینهسازی عملکرد اجرا شده است یا نه متفاوت است.
برای پاسخ دادن به سؤال زیر، تحلیل کنید که کاربر بهطور میانگین چند نویسه تایپ میکند تا پیشبینی «تکمیل خودکار» (جدید) را در برنامهتان انتخاب کند.
آیا کاربران شما بهطور میانگین با چهار درخواست یا کمتر، پیشبینی «تکمیل خودکار (جدید)» را انتخاب میکنند؟
بله
«تکمیل خودکار» (جدید) را بهصورت برنامهنویسیشده بدون کد جلسه پیادهسازی کنید و Geocoding API را در پیشبینی مکان انتخابشده فراخوانی کنید.
Geocoding API نشانیها و مختصات طول/عرض جغرافیایی را ارائه میدهد.
انجام چهار درخواست
تکمیل خودکار
بهعلاوه یک فراخوانی Geocoding API
درباره پیشبینی مکان انتخابشده کمتر از هزینه هر جلسه
«تکمیل خودکار (جدید)» است.۱
برای کمک به کاربران در دریافت پیشبینی موردنظرشان با تعداد نویسههای کمتر، از بهترین روشهای عملکرد استفاده کنید.
نه
از «تکمیل خودکار مبتنی بر جلسه» (جدید) با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجاییکه تعداد میانگین درخواستهایی که انتظار دارید قبلاز اینکه کاربر پیشبینی
«تکمیل خودکار (جدید)» را انتخاب کند ایجاد کنید از هزینه قیمتگذاری بهازای هر جلسه فراتر میرود، پیادهسازی
«تکمیل خودکار (جدید)» شما باید برای درخواستهای «تکمیل خودکار (جدید)» و درخواست
«جزئیات مکان (جدید)» مرتبط از
کد جلسه استفاده کند.
۱
پیادهسازی ابزاره
مدیریت جلسه بهطور خودکار در ابزارههای
JavaScript،
Android،
یا iOS
ساخته میشود. این شامل درخواستهای «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیشبینی انتخابشده میشود. حتماً پارامتر fields را مشخص کنید
تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست میکنید.
پیادهسازی برنامهریزیشده
از
نشانه جلسه
با درخواستهای «تکمیل خودکار (جدید)» استفاده کنید.
هنگام درخواست «جزئیات مکان (جدید)» درباره پیشبینی انتخابشده،
پارامترهای زیر را اضافه کنید:
- شناسه مکان از پاسخ «تکمیل خودکار (جدید)»
- کد جلسه استفادهشده در درخواست «تکمیل خودکار (جدید)»
- پارامتر
fieldsکه فیلدهایی مثل نشانی و هندسه را مشخص میکند
بهتأخیر انداختن درخواستهای «تکمیل خودکار» (جدید) را مدنظر قرار دهید
میتوانید از استراتژیهایی مانند بهتأخیر انداختن درخواست «تکمیل خودکار» (جدید) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامهتان درخواستهای کمتری ارسال کند. برای مثال، ارسال درخواستهای «تکمیل خودکار (جدید)» برای هر نویسه پساز اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیشبینیای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال میکنید، هزینه کل برای ۴ درخواست «تکمیل خودکار (جدید)» بهازای هر درخواست + Geocoding خواهد بود.۱
اگر با بهتأخیر انداختن درخواستها میتوانید میانگین درخواستهای برنامهریزیشده را به زیر چهار برسانید، میتوانید راهنمای پیادهسازی «تکمیل خودکار (جدید)» با Geocoding API را دنبال کنید. توجه داشته باشید که تأخیر در درخواستها میتواند ازسوی کاربر بهعنوان تأخیر درک شود، زیرا ممکن است کاربر انتظار داشته باشد با هر ضربه کلید جدید، پیشبینیها را ببیند.
برای کمک به کاربران در دریافت پیشبینی موردنظرشان با نویسههای کمتر، روشهای مطلوب عملکرد را بهکار بگیرید.
-
برای اطلاع از هزینهها، فهرستهای قیمتگذاری «پلاتفرم Google Maps» را ببینید.
روالهای مطلوب عملکرد
دستورالعملهای زیر روشهای بهینهسازی عملکرد «تکمیل خودکار (جدید)» را شرح میدهد:
- محدودیتهای کشور، انحراف مکان، و (برای پیادهسازیهای برنامهریزیشده) اولویت زبان را به پیادهسازی «تکمیل خودکار» (جدید) اضافه کنید. برای ابزارهها به اولویت زبان نیازی نیست چون آنها اولویتهای زبان را از مرورگر یا دستگاه همراه کاربر انتخاب میکنند.
- اگر «تکمیل خودکار (جدید)» با نقشه همراه باشد، میتوانید مکان را براساس نمای درگاه نقشه گرایش دهید.
- در شرایطی که کاربر یکی از پیشبینیهای Autocomplete (New) را انتخاب نمیکند، معمولاً
به این دلیل که هیچکدام از آن پیشبینیها نشانی نتیجه موردنظر نیست، میتوانید از ورودی اصلی
کاربر مجدداً استفاده کنید تا نتایج مرتبطتری دریافت کنید:
- اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، ورودی کاربر اصلی را در تماس با Geocoding API دوباره استفاده کنید.
- اگر انتظار دارید کاربر پُرسمانهای مربوط به مکان خاصی را براساس نام یا نشانی وارد کند، از درخواست «جزئیات مکان (جدید)» استفاده کنید. اگر نتایج فقط در منطقه خاصی موردانتظار است، از سوگیری مکان استفاده کنید.
- کاربرانی که نشانیهای فرعی وارد میکنند، مثل نشانیهای واحدهای خاص یا آپارتمانها در یک ساختمان. برای مثال، نشانی چک «Stroupežnického 3191/17, Praha» پیشبینی جزئی در «تکمیل خودکار» (جدید) ارائه میدهد.
- کاربرانی که نشانیها را با پیشوند بخش جاده وارد میکنند، مانند «23-30 29th St, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره کائوآئی در هاوایی.
انحراف مکانی
با ارسال پارامتر location و پارامتر radius، نتایج را به منطقه مشخصی متمایل کنید. این دستور به «تکمیل خودکار (جدید)» میگوید که نمایش نتایج در محدوده تعریفشده را ترجیح دهد. نتایج خارج از منطقه تعریفشده ممکن است همچنان
نمایش داده شود. میتوانید از پارامتر includedRegionCodes برای فیلتر کردن نتایج استفاده کنید
تا فقط مکانهای درون کشور مشخصشده را نشان دهد.
مکان محدودکننده
با ارسال پارامتر locationRestriction، نتایج را به منطقه مشخصی محدود کنید.
همچنین میتوانید با افزودن پارامتر
locationRestriction
نتایج را به منطقهای که با location
و پارامتر radius تعریف شده است محدود کنید. این دستور به «تکمیل خودکار (جدید)» میدهد که فقط
نتایج را در آن منطقه برگرداند.