این صفحه کتابخانه سمت سرویس گیرنده موجود با Maps JavaScript API را شرح می دهد. اگر می‌خواهید با سرویس وب Places API روی سرور خود کار کنید، به Node.js Client for Google Maps Services نگاهی بیندازید. صفحه موجود در آن پیوند همچنین Java Client، Python Client و Go Client را برای خدمات Google Maps معرفی می کند.
مقدمه
تکمیل خودکار یکی از ویژگی های کتابخانه Places در Maps JavaScript API است. می‌توانید از تکمیل خودکار استفاده کنید تا به برنامه‌های خود رفتار جستجوی پیش‌نویس فیلد جستجوی Google Maps را بدهید. سرویس تکمیل خودکار می‌تواند با کلمات و زیررشته‌های کامل مطابقت داشته باشد، نام مکانها، آدرس‌ها و کدهای بعلاوه را حل کند. بنابراین، برنامه‌ها می‌توانند پرس‌و‌جوهایی را به‌عنوان نوع کاربر ارسال کنند تا پیش‌بینی‌های مکان را در لحظه ارائه دهند. همانطور که توسط Places API تعریف شده است، یک "مکان" می تواند یک موسسه، یک مکان جغرافیایی یا یک نقطه جالب توجه باشد.
شروع کردن
قبل از استفاده از کتابخانه Places در Maps JavaScript API، ابتدا بررسی کنید که Places API در کنسول Google Cloud در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید فعال باشد.
روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
از لیست APIها در داشبورد ، Places API را جستجو کنید.
اگر API را در لیست مشاهده کردید، همه چیز آماده است. با این حال، این پروژه در وضعیت Legacy است. برای اطلاعات بیشتر درباره مرحله Legacy و نحوه انتقال از Legacy به سرویس‌های جدیدتر، به محصولات و ویژگی‌های Legacy مراجعه کنید. یک استثنا برای ویجت های تکمیل خودکار و SearchBox در دسترس است که هنوز به عنوان یک محصول GA در Places API (جدید) در دسترس نیستند.
کتابخانه را بارگیری کنید
سرویس Places یک کتابخانه مستقل و جدا از کد اصلی Maps JavaScript API است. برای استفاده از ویژگی های موجود در این کتابخانه، ابتدا باید آن را با استفاده از پارامتر libraries در URL بوت استرپ Maps API بارگیری کنید:
API دو نوع ویجت تکمیل خودکار را ارائه می دهد که می توانید به ترتیب با استفاده از کلاس های Autocomplete و SearchBox را اضافه کنید. علاوه بر این، می‌توانید از کلاس AutocompleteService برای بازیابی نتایج تکمیل خودکار به صورت برنامه‌نویسی استفاده کنید (به مرجع Maps JavaScript API مراجعه کنید: کلاس AutocompleteService ).
در زیر خلاصه ای از کلاس های موجود است:
Autocomplete یک فیلد ورودی متن را به صفحه وب شما اضافه می کند و آن فیلد را برای ورود کاراکترها کنترل می کند. همانطور که کاربر متن را وارد می کند، تکمیل خودکار پیش بینی های مکان را در قالب یک لیست کشویی برمی گرداند. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به مکان به شی تکمیل خودکار بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود. جزئیات را در زیر مشاهده کنید. شکل 1: تکمیل خودکار فیلد متن و لیست انتخاب شکل 2: فرم آدرس تکمیل شده
SearchBox یک فیلد ورودی متن را به صفحه وب شما اضافه می کند، تقریباً مانند Autocomplete . تفاوت ها به شرح زیر است:
تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می شوند. SearchBox فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌کند که می‌تواند شامل مکانها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاه‌های مختلف پیتزا باشد.
SearchBox گزینه های کمتری نسبت به Autocomplete برای محدود کردن جستجو ارائه می دهد. در حالت اول، می توانید جستجو را به سمت LatLngBounds معین سوگیری کنید. در حالت دوم، می‌توانید جستجو را به یک کشور خاص و انواع مکانهای خاص محدود کنید، و همچنین محدودیت‌ها را تعیین کنید. برای اطلاعات بیشتر، زیر را ببینید.
شکل 3: یک SearchBox عبارات جستجو و پیش بینی مکان را ارائه می دهد. جزئیات را در زیر مشاهده کنید.
می توانید یک شی AutocompleteService برای بازیابی پیش بینی ها به صورت برنامه ای ایجاد کنید. برای بازیابی مکانهای منطبق با getPlacePredictions() یا برای بازیابی مکانهای منطبق و عبارات جستجوی پیشنهادی getQueryPredictions() را تماس بگیرید. توجه: AutocompleteService هیچ کنترل رابط کاربری اضافه نمی کند. در عوض، روشهای فوق آرایه‌ای از اشیاء پیش‌بینی را برمی‌گردانند. هر شیء پیش‌بینی حاوی متن پیش‌بینی، و همچنین اطلاعات مرجع و جزئیات نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر مشاهده کنید.
یک ویجت تکمیل خودکار اضافه کنید
ویجت Autocomplete یک فیلد ورودی متن را در صفحه وب شما ایجاد می کند، پیش بینی مکان ها را در لیست انتخاب رابط کاربری ارائه می دهد و جزئیات مکان را در پاسخ به درخواست getPlace() برمی گرداند. هر ورودی در لیست انتخاب مربوط به یک مکان واحد است (همانطور که توسط Places API تعریف شده است).
سازنده Autocomplete دو آرگومان می گیرد:
یک عنصر input HTML از نوع text . این فیلد ورودی است که سرویس تکمیل خودکار نتایج آن را نظارت کرده و به آن پیوست می کند.
آرایه ای از fields داده که باید در پاسخ Place Details برای PlaceResult انتخابی کاربر گنجانده شود. اگر ویژگی تنظیم نشده باشد یا اگر ['ALL'] وارد شود، همه فیلدهای موجود برگردانده شده و برای آنها صورتحساب دریافت می‌شود (این برای استقرار تولید توصیه نمی‌شود). برای فهرستی از فیلدها، PlaceResult ببینید.
آرایه ای از types که نوع صریح یا مجموعه نوع را مشخص می کند، همانطور که در انواع پشتیبانی شده فهرست شده است. اگر نوع مشخص نشده باشد، همه انواع برگردانده می شوند.
bounds یک شی google.maps.LatLngBounds است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج به سمت مکانهایی که در این محدوده‌ها قرار دارند، تعصب دارند، اما محدود به آنها نیستند.
strictBounds یک boolean است که مشخص می‌کند آیا API باید فقط مکانهایی را برگرداند که دقیقاً در منطقه تعریف‌شده با bounds داده شده هستند یا خیر. API نتایج خارج از این منطقه را حتی اگر با ورودی کاربر مطابقت داشته باشد برنمی‌گرداند.
componentRestrictions می تواند برای محدود کردن نتایج به گروه های خاص استفاده شود. می توانید از componentRestrictions برای فیلتر کردن بر اساس حداکثر 5 کشور استفاده کنید. کشورها باید به عنوان کد کشوری دو کاراکتری و سازگار با ISO 3166-1 Alpha-2 ارسال شوند. چندین کشور باید به عنوان فهرستی از کدهای کشور ارسال شوند.
placeIdOnly می‌تواند برای دستور دادن به ویجت Autocomplete برای بازیابی فقط شناسه‌های مکان استفاده شود. هنگام فراخوانی getPlace() در شیء Autocomplete ، PlaceResult موجود تنها دارای شناسه place id ، types و خصوصیات name است. می‌توانید از شناسه مکان برگشتی با تماس‌هایی که با سرویس‌های مکانها، کدگذاری جغرافیایی، مسیرها یا ماتریس فاصله دارد استفاده کنید.
پیش بینی های تکمیل خودکار را محدود کنید
به‌طور پیش‌فرض، «تکمیل خودکار مکان» همه انواع مکانها را ارائه می‌کند که برای پیش‌بینی‌های نزدیک به مکان کاربر تعصب دارند و همه فیلدهای داده موجود را برای مکان انتخابی کاربر واکشی می‌کند. گزینه‌های تکمیل خودکار مکان را تنظیم کنید تا پیش‌بینی‌های مرتبط‌تری بر اساس مورد استفاده شما ارائه شود.
گزینه ها را در ساخت و ساز تنظیم کنید
سازنده Autocomplete یک پارامتر AutocompleteOptions را برای تعیین محدودیت در ایجاد ویجت می پذیرد. مثال زیر گزینه‌های bounds ، componentRestrictions و types را برای درخواست مکانهای نوع establishment ، ترجیح می‌دهد که در منطقه جغرافیایی مشخص شده و پیش‌بینی‌ها را فقط به مکانهای داخل ایالات متحده محدود می‌کند. تنظیم گزینه fields مشخص می کند که چه اطلاعاتی در مورد مکان انتخابی کاربر بازگردانده شود.
برای تغییر مقدار یک گزینه برای ویجت موجود، setOptions() را فراخوانی کنید.
TypeScript
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
فیلدهای داده را مشخص کنید تا از دریافت صورتحساب برای مکانهای SKU داده مکانهایی که به آنها نیاز ندارید اجتناب کنید. همانطور که در مثال قبلی نشان داده شد، ویژگی fields را در AutocompleteOptions که به سازنده ویجت ارسال می شود، اضافه کنید، یا setFields() را روی یک شیء Autocomplete موجود فراخوانی کنید.
گزینه strictBounds را تنظیم کنید تا نتایج را به کران های فعلی محدود کنید، چه بر اساس نمای نقشه و چه بر اساس مرزهای مستطیلی.
autocomplete.setOptions({strictBounds:true});
پیش بینی ها را به یک کشور خاص محدود کنید
از گزینه componentRestrictions استفاده کنید یا setComponentRestrictions() را فراخوانی کنید تا جستجوی تکمیل خودکار را به مجموعه خاصی از حداکثر پنج کشور محدود کنید.
از گزینه types یا فراخوانی setTypes() برای محدود کردن پیش‌بینی‌ها به انواع مکانهای خاص استفاده کنید. این محدودیت یک نوع یا یک مجموعه نوع را مشخص می کند، همانطور که در Place Types فهرست شده است. اگر هیچ محدودیتی مشخص نشده باشد، همه انواع برگردانده می شوند.
برای مقدار گزینه 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
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=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")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).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();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=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!">
توجه: متن مکان‌نمای پیش‌فرض به‌طور خودکار بومی‌سازی می‌شود. اگر مقدار متغیر مکان خود را مشخص کنید، باید محلی سازی آن مقدار را در برنامه خود انجام دهید. برای کسب اطلاعات در مورد نحوه انتخاب زبان مورد استفاده توسط Google Maps JavaScript API، مستندات مربوط به محلی سازی را بخوانید.
SearchBox به کاربران اجازه می دهد تا جستجوی جغرافیایی مبتنی بر متن را انجام دهند، مانند «پیتزا در نیویورک» یا «فروشگاه های کفش در نزدیکی خیابان رابسون». می‌توانید SearchBox به یک فیلد متنی وصل کنید و با وارد کردن متن، سرویس پیش‌بینی‌ها را در قالب فهرست انتخابی کشویی برمی‌گرداند.
SearchBox فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌کند که می‌تواند شامل مکانها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاه‌های مختلف پیتزا باشد. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به آن مکان به شی SearchBox بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود.
سازنده SearchBox دو آرگومان می گیرد:
یک عنصر input HTML از نوع text . این فیلد ورودی است که سرویس SearchBox آن را نظارت کرده و نتایج خود را به آن پیوست می کند.
یک آرگومان options ، که می‌تواند حاوی ویژگی bounds باشد: bounds یک شی google.maps.LatLngBounds است که منطقه‌ای را که در آن مکانها جستجو می‌شود را مشخص می‌کند. نتایج به سمت مکانهایی که در این محدوده‌ها قرار دارند، تعصب دارند، اما محدود به آنها نیستند.
کد زیر از پارامتر کرانه‌ها برای سوگیری نتایج به سمت مکانهایی در یک منطقه جغرافیایی خاص استفاده می‌کند که با استفاده از مختصات طول و عرض جغرافیایی مشخص شده‌اند.
هنگامی که کاربر موردی را از پیش‌بینی‌های پیوست شده به کادر جستجو انتخاب می‌کند، سرویس یک رویداد places_changed فعال می‌کند. می‌توانید getPlaces() در شی SearchBox فراخوانی کنید تا آرایه‌ای حاوی چندین پیش‌بینی را بازیابی کنید که هر کدام یک شی PlaceResult هستند.
برای اطلاعات بیشتر درباره شی PlaceResult ، به مستندات مربوط به نتایج جزئیات مکان مراجعه کنید.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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() پیش بینی های مکان را برمی گرداند. توجه: «مکان» می‌تواند یک مؤسسه، موقعیت جغرافیایی یا نقطه‌ی مهم مورد علاقه باشد که توسط Places API تعریف شده است.
getQueryPredictions() لیست گسترده ای از پیش بینی ها را برمی گرداند که می تواند شامل مکان ها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاه‌های مختلف پیتزا باشد.
distance_meters فاصله بر حسب متر از مکان از AutocompletionRequest.origin مشخص شده است.
matched_substrings شامل مجموعه ای از زیر رشته ها در توضیحات است که عناصر ورودی کاربر را مطابقت می دهد. این برای برجسته کردن رشته های فرعی در برنامه شما مفید است. در بسیاری از موارد، پرس و جو به عنوان زیر رشته فیلد توضیحات ظاهر می شود.
length طول رشته فرعی است.
offset عبارت است از آفست کاراکتر که از ابتدای رشته توضیحات اندازه گیری می شود و در آن رشته فرعی مطابقت داده شده ظاهر می شود.
place_id یک شناسه متنی است که به طور منحصر به فرد یک مکان را شناسایی می کند. برای بازیابی اطلاعات مربوط به مکان، این شناسه را در قسمت placeIdدرخواست جزئیات مکان ارسال کنید. درباره نحوه ارجاع مکان با شناسه مکان بیشتر بیاموزید.
terms آرایه ای است که شامل عناصر پرس و جو است. برای یک مکان، هر عنصر معمولاً بخشی از آدرس را تشکیل می دهد.
offset عبارت است از آفست کاراکتر که از ابتدای رشته توضیحات اندازه گیری می شود و در آن رشته فرعی مطابقت داده شده ظاهر می شود.
value عبارت تطبیقی است.
مثال زیر یک درخواست پیش‌بینی پرس و جو را برای عبارت «pizza near» اجرا می‌کند و نتیجه را در یک لیست نمایش می‌دهد.
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">functioninitService():void{constdisplaySuggestions=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)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{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">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<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 script 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() ناشی می‌شود، استفاده کنید. در این حالت، درخواست تکمیل خودکار با درخواست جزئیات مکان ترکیب می شود و هزینه تماس به عنوان یک درخواست معمولی جزئیات مکان محاسبه می شود. برای درخواست تکمیل خودکار هزینه ای دریافت نمی شود.
مطمئن شوید که برای هر جلسه جدید یک نشانه جلسه منحصر به فرد ارسال می کنید. استفاده از یک نشانه برای بیش از یک جلسه تکمیل خودکار، آن جلسات تکمیل خودکار را باطل می‌کند و تمام درخواست‌های تکمیل خودکار در جلسات نامعتبر به صورت جداگانه با استفاده از تکمیل خودکار در هر درخواست SKU کسر می‌شود. درباره نشانه های جلسه بیشتر بخوانید .
مثال زیر ایجاد یک نشانه جلسه، سپس ارسال آن در AutocompleteService را نشان می دهد (عملکرد displaySuggestions() برای اختصار حذف شده است):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
مطمئن شوید که برای هر جلسه جدید یک نشانه جلسه منحصر به فرد ارسال می کنید. استفاده از یک نشانه برای بیش از یک جلسه باعث می شود که هر درخواست به صورت جداگانه صورتحساب شود.
به‌طور پیش‌فرض، عناصر رابط کاربری ارائه‌شده توسط 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 کینگ» است. برای جستجوهای مبتنی بر متن مانند "پیتزا در نیویورک"، حاوی متن کامل پرس و جو است. به طور پیش فرض، pac-item-query سیاه رنگ است. اگر متن اضافی در pac-item وجود داشته باشد، خارج از pac-item-query است و استایل خود را از pac-item به ارث می برد. به طور پیش فرض خاکستری رنگ است. متن اضافی معمولاً یک آدرس است.
pac-matched
بخشی از پیش بینی برگشتی که با ورودی کاربر مطابقت دارد. به طور پیش فرض، این متن مطابق با متن پررنگ برجسته می شود. توجه داشته باشید که متن تطبیق داده شده ممکن است در هر جایی از pac-item باشد. لزوماً بخشی از pac-item-query نیست و می تواند تا حدی در pac-item-query و همچنین بخشی از متن باقی مانده در pac-item باشد.
بهینه سازی تکمیل خودکار مکان (میراث).
این بخش بهترین روشها را توضیح می‌دهد که به شما کمک می‌کند از خدمات تکمیل خودکار مکان (قدیمی) حداکثر استفاده را ببرید.
از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان (میراث) ایجاد کنید.
فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.
بهترین شیوه های بهینه سازی هزینه
بهینه سازی هزینه پایه
برای بهینه‌سازی هزینه استفاده از سرویس تکمیل خودکار مکان (میراث)، از ماسک‌های فیلد در ویجت‌های Place Details (Legacy) و Place Autocomplete (Legacy) استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.
بهینه سازی هزینه پیشرفته
به منظور دسترسی به قیمت هر درخواست و درخواست نتایج Geocoding API در مورد مکان انتخابی به جای جزئیات مکان (میراث) اجرای برنامه‌ای Place Autocomplete (Legacy) را در نظر بگیرید. قیمت گذاری هر درخواست جفت شده با Geocoding API مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) است اگر هر دو شرایط زیر رعایت شود:
اگر فقط به طول/طول جغرافیایی یا آدرس مکان انتخابی کاربر نیاز دارید، API Geocoding این اطلاعات را کمتر از یک تماس با جزئیات مکان (میراث) ارائه می دهد.
اگر کاربران یک پیش‌بینی تکمیل خودکار را به‌طور متوسط در چهار درخواست پیش‌بینی تکمیل خودکار مکان (قدیمی) یا کمتر انتخاب کنند، قیمت‌گذاری در هر درخواست ممکن است مقرون‌به‌صرفه‌تر از قیمت‌گذاری در هر جلسه باشد.
برای کمک به انتخاب پیاده‌سازی تکمیل خودکار مکان (میراث) که متناسب با نیاز شما باشد، برگه‌ای را انتخاب کنید که با پاسخ شما به سؤال زیر مطابقت دارد.
آیا برنامه شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیش بینی انتخاب شده نیاز دارد؟
دستورالعمل‌های زیر روش‌هایی را برای بهینه‌سازی عملکرد تکمیل خودکار مکان (میراث) شرح می‌دهند:
محدودیت‌های کشور، سوگیری موقعیت و اولویت زبان (برای اجرای برنامه‌ای) را به پیاده‌سازی تکمیل خودکار مکان (میراث) خود اضافه کنید. اولویت زبان با ویجت ها مورد نیاز نیست زیرا آنها ترجیحات زبان را از مرورگر کاربر یا دستگاه تلفن همراه انتخاب می کنند.
اگر تکمیل خودکار مکان (میراث) با نقشه همراه باشد، می‌توانید مکان را با درگاه نمای نقشه سوگیری کنید.
در شرایطی که کاربر یکی از پیش‌بینی‌های تکمیل خودکار مکان (میراث) را انتخاب نمی‌کند، معمولاً به دلیل اینکه هیچ یک از آن پیش‌بینی‌ها آدرس نتیجه مورد نظر نیستند، می‌توانید از ورودی اصلی کاربر برای تلاش برای دریافت نتایج مرتبط‌تر دوباره استفاده کنید:
اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند ، از ورودی اصلی کاربر در تماس با API GeoCoding استفاده مجدد کنید.
اگر انتظار دارید کاربر برای یک مکان خاص با نام یا آدرس ، نمایش داده شود ، از یک درخواست Find Place (Legacy) استفاده کنید. اگر نتایج فقط در یک منطقه خاص انتظار می رود ، از تعصب مکان استفاده کنید.
سناریوهای دیگر هنگامی که بهتر است به API Geocoding برگردید عبارتند از:
کاربرانی که آدرس های فرعی را وارد می کنند ، مانند آدرس برای واحدهای خاص یا آپارتمان ها در یک ساختمان. به عنوان مثال ، آدرس چک "stroupežnického 3191/17 ، praha" پیش بینی جزئی در جای خود را به صورت خودکار (میراث) ارائه می دهد.
کاربرانی که آدرس هایی را با پیشوندهای قطعه جاده مانند "23-30 29 خیابان ، کوئینز" در شهر نیویورک یا "47-380 Kamehameha Hwy ، Kaneohe" در جزیره Kauai در هاوایی وارد می کنند.
این صفحه کتابخانه سمت مشتری موجود با نقشه های JavaScript API را توصیف می کند. اگر می خواهید با سرویس های وب API در سرور خود کار کنید ، به سرویس Node.js برای خدمات Google Maps نگاهی بیندازید. صفحه در آن لینک همچنین مشتری Java ، Python Client و Go Client را برای خدمات Google Maps معرفی می کند.
مقدمه
Autoclotte یکی از ویژگی های کتابخانه مکان ها در نقشه های API JavaScript است. شما می توانید از AutoClotte استفاده کنید تا به برنامه های خود رفتار نوع جستجوی قسمت جستجوی Google Maps را ارائه دهید. سرویس خودکار می تواند بر روی کلمات و بستر های کامل مطابقت داشته باشد ، نام مکان ها ، آدرس ها و کدهای به علاوه را حل کند. بنابراین برنامه ها می توانند نمایش داده ها را به عنوان انواع کاربر ارسال کنند تا پیش بینی های مکان پرواز را ارائه دهند. همانطور که توسط مکانها API تعریف شده است ، یک "مکان" می تواند یک تأسیس ، یک مکان جغرافیایی یا یک نکته جالب توجه باشد.
شروع کردن
قبل از استفاده از کتابخانه مکان ها در نقشه های JavaScript API ، ابتدا تأیید کنید که API مکان ها در کنسول Google Cloud فعال شده است ، در همان پروژه ای که برای نقشه های JavaScript API تنظیم کرده اید.
بر روی دکمه Select A Project کلیک کنید ، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کرده و روی Open کلیک کنید.
از لیست API ها در داشبورد ، به دنبال API مکان ها باشید.
اگر API را در لیست مشاهده می کنید ، همه شما تنظیم شده اید. با این حال ، این پروژه در وضعیت میراث است. برای کسب اطلاعات بیشتر در مورد مرحله میراث و نحوه مهاجرت از میراث به خدمات جدیدتر ، به محصولات و ویژگی های میراث مراجعه کنید. یک استثناء برای ابزارک های اتوماتیک و جعبه جستجو ، که هنوز به عنوان یک محصول GA در API (جدید) در دسترس نیستند ، در دسترس نیست.
بارگیری کتابخانه
سرویس مکان ها یک کتابخانه خودمختار است ، جدا از نقشه اصلی کد API JavaScript. برای استفاده از ویژگی های موجود در این کتابخانه ، ابتدا باید آن را با استفاده از پارامتر libraries در URL Bootstrap API MAPS بارگیری کنید:
API دو نوع ابزارک ناقص را ارائه می دهد که می توانید به ترتیب با استفاده از کلاس های Autocomplete و SearchBox اضافه کنید. علاوه بر این ، شما می توانید از کلاس AutocompleteService برای بازیابی نتایج خودکار به صورت برنامه ای استفاده کنید (به نقشه های JavaScript API مرجع: کلاس AutoCompleTeservice مراجعه کنید).
در زیر خلاصه ای از کلاس های موجود است:
Autocomplete یک قسمت ورودی متن را به صفحه وب خود اضافه می کند و مانیتور آن را برای ورود شخصیت ها نظارت می کند. با ورود کاربر متن ، پیش بینی های خودکار پیش بینی های خود را در قالب لیست کشویی قرار می دهد. هنگامی که کاربر مکانی را از لیست انتخاب می کند ، اطلاعات مربوط به مکان به شیء خودکار بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود. جزئیات را در زیر مشاهده کنید. شکل 1: قسمت متن و لیست انتخاب خودکار شکل 2: فرم آدرس تکمیل شده
SearchBox یک قسمت ورودی متن را به صفحه وب خود اضافه می کند ، به همان روشی که به Autocomplete وجود دارد. تفاوت ها به شرح زیر است:
تفاوت اصلی در نتایج موجود در لیست انتخاب نهفته است. SearchBox لیست گسترده ای از پیش بینی ها را ارائه می دهد ، که می تواند شامل مکانهایی (مطابق با مکان های API) به علاوه اصطلاحات جستجوی پیشنهادی باشد. به عنوان مثال ، اگر کاربر وارد پیتزا جدید شود ، لیست انتخاب ممکن است عبارت "پیتزا در نیویورک ، نیویورک" و همچنین نام رسانه های مختلف پیتزا را شامل شود.
SearchBox گزینه های کمتری نسبت به Autocomplete برای محدود کردن جستجو ارائه می دهد. در گذشته ، می توانید جستجو را به سمت یک LatLngBounds داده شده تعصب کنید. در حالت دوم ، می توانید جستجو را به یک کشور خاص و انواع مکان خاص و همچنین تعیین مرزها محدود کنید. برای اطلاعات بیشتر ، به زیر مراجعه کنید.
شکل 3: یک جعبه جستجو اصطلاحات جستجو و پیش بینی مکان را ارائه می دهد. جزئیات را در زیر مشاهده کنید.
برای بازیابی پیش بینی ها به صورت برنامه ای می توانید یک شیء AutocompleteService ایجاد کنید. برای بازیابی مکان های تطبیق یا تماس با getPlacePredictions()getQueryPredictions() تماس بگیرید تا مکانهای تطبیق به علاوه شرایط جستجوی پیشنهادی را بازیابی کنید. توجه: AutocompleteService هیچ کنترل UI را اضافه نمی کند. در عوض ، روشهای فوق مجموعه ای از اشیاء پیش بینی را برمی گردانند. هر شیء پیش بینی شامل متن پیش بینی ، و همچنین اطلاعات مرجع و جزئیات مربوط به نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر مشاهده کنید.
ویجت خودکار را اضافه کنید
ویجت Autocomplete یک قسمت ورودی متن را در صفحه وب شما ایجاد می کند ، پیش بینی مکان ها را در یک لیست انتخاب UI تهیه می کند و جزئیات مکان را در پاسخ به درخواست getPlace() باز می گرداند. هر ورودی در لیست انتخاب با یک مکان واحد مطابقت دارد (همانطور که توسط API مکان ها تعریف شده است).
سازنده Autocomplete دو استدلال می کند:
یک عنصر input HTML از text . این قسمت ورودی است که سرویس خودکار ناقص آن را کنترل می کند و نتایج خود را به آن وصل می کند.
مجموعه ای از fields داده که باید در پاسخ Place Details برای PlaceResult انتخاب شده کاربر گنجانده شود. اگر این ملک تنظیم نشده باشد یا اگر ['ALL'] منتقل شود ، تمام زمینه های موجود بازگردانده و صورتحساب می شوند (این برای استقرار تولید توصیه نمی شود). برای لیستی از قسمت ها ، به PlaceResult مراجعه کنید.
مجموعه ای از types که یک نوع صریح یا یک مجموعه نوع را مشخص می کند ، همانطور که در انواع پشتیبانی شده ذکر شده است. اگر هیچ نوع مشخص نشده باشد ، همه نوع بازگردانده می شوند.
bounds یک شیء google.maps.LatLngBounds است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج نسبت به مکانهای موجود در این مرزها مغرضانه ، اما محدود نمی شوند.
strictBounds یک boolean است که مشخص می کند آیا API باید فقط مکانهایی را که کاملاً در منطقه تعریف شده توسط bounds داده شده است ، برگرداند. API حتی اگر با ورودی کاربر مطابقت داشته باشد ، نتایج خارج از این منطقه را بر نمی گرداند.
componentRestrictions می توان برای محدود کردن نتایج به گروه های خاص استفاده کرد. شما می توانید از componentRestrictions استفاده کنید تا حداکثر 5 کشور جهان فیلتر شود. کشورها باید به عنوان یک کد سازگار با دو شخصیت ، ISO 3166-1 Alpha-2 تصویب شوند. چندین کشور باید به عنوان لیستی از کدهای کشور منتقل شوند.
توجه: اگر نتایج غیر منتظره ای را با یک کد کشور دریافت می کنید ، تأیید کنید که از کدی استفاده می کنید که شامل کشورها ، سرزمین های وابسته و مناطق خاص از علاقه جغرافیایی مورد نظر شما می شود. می توانید اطلاعات کد را در ویکی پدیا پیدا کنید: لیست کدهای کشور ISO 3166 یا پلت فرم مرور آنلاین ISO .
placeIdOnly می تواند برای آموزش ویجت Autocomplete برای بازیابی فقط شناسه های مکان استفاده شود. در تماس با getPlace() در شیء Autocomplete ، PlaceResult که در دسترس است فقط دارای place id ، types و ویژگی های name است. می توانید از شناسه مکان برگشتی با تماس به مکان ها ، GeoCoding ، دستورالعمل ها یا خدمات ماتریس از راه دور استفاده کنید.
پیش بینی های خودکار را محدود کنید
به طور پیش فرض ، Place Autoclotte کلیه انواع مکان را ارائه می دهد ، برای پیش بینی های نزدیک محل کاربر مغرضانه است و تمام قسمتهای داده موجود را برای مکان انتخاب شده کاربر دریافت می کند. گزینه های خودکار را برای ارائه پیش بینی های مرتبط تر بر اساس مورد استفاده خود قرار دهید.
گزینه ها را در ساخت و ساز تنظیم کنید
سازنده Autocomplete یک پارامتر AutocompleteOptions را برای تنظیم محدودیت ها در ایجاد ویجت می پذیرد. مثال زیر bounds ، componentRestrictions و گزینه های types را برای درخواست مکان های نوع establishment ، به نفع کسانی که در منطقه جغرافیایی مشخص شده و محدود کردن پیش بینی ها فقط در مکان های موجود در ایالات متحده قرار دارند ، تعیین می کند. تنظیم گزینه fields مشخص می کند که چه اطلاعاتی را برای بازگشت در مورد مکان انتخاب شده کاربر نشان می دهد.
برای تغییر مقدار گزینه برای ویجت موجود ، setOptions() تماس بگیرید.
TypeScript
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
زمینه های داده را مشخص کنید تا از صورتحساب برای مکان های SKU های مورد نیاز خودداری کنید. ویژگی های fields را در AutocompleteOptions که به سازنده ویجت منتقل می شوند ، همانطور که در مثال قبلی نشان داده شده است ، یا Call setFields() روی یک شیء Autocomplete موجود موجود درج کنید.
برای محدود کردن پیش بینی ها به انواع مکان خاص از گزینه types یا setTypes() استفاده کنید. این محدودیت یک نوع یا مجموعه نوع را مشخص می کند ، همانطور که در انواع مکان ذکر شده است. اگر هیچ محدودیتی مشخص نشده باشد ، همه نوع بازگردانده می شوند.
برای مقدار گزینه types یا مقدار منتقل شده به setTypes() ، می توانید یا مشخص کنید:
هنگامی که یک کاربر مکانی را از پیش بینی های متصل به قسمت متن خودکار انتخاب می کند ، این سرویس یک رویداد place_changed شلیک می کند. برای به دست آوردن جزئیات مکان:
برای یک رویداد place_changed () با addListener() در شیء Autocomplete تماس بگیرید تا یک کنترل کننده را اضافه کنید.
برای بازیابی یک شیء Autocomplete ، که می توانید PlaceResult آن استفاده کنید تا اطلاعات بیشتری در مورد مکان انتخاب شده داشته باشید ، با Autocomplete.getPlace() تماس بگیرید.
به طور پیش فرض ، هنگامی که یک کاربر یک مکان را انتخاب می کند ، Autoclotte تمام قسمت های داده موجود را برای مکان انتخاب شده باز می گرداند و بر این اساس صورتحساب می شود. برای مشخص کردن کدام قسمت از قسمت های داده برای بازگشت ، از Autocomplete.setFields() استفاده کنید. اطلاعات بیشتر در مورد شیء PlaceResult ، از جمله لیستی از زمینه های داده مکان که می توانید درخواست کنید بخوانید. برای جلوگیری از پرداخت داده هایی که به آن احتیاج ندارید ، حتماً از Autocomplete.setFields() استفاده کنید تا فقط داده های مکانی را که استفاده می کنید مشخص کنید.
ویژگی name شامل description از مکان های پیش بینی های خودکار است. می توانید اطلاعات بیشتر در مورد description در مکانها مستندات خودکار را بخوانید.
برای فرم های آدرس ، دریافت آدرس در قالب ساختاری مفید است. برای بازگشت آدرس ساختار یافته برای مکان انتخاب شده ، با Autocomplete.setFields() تماس بگیرید و قسمت address_components مشخص کنید.
مثال زیر از AutoClotte برای پر کردن قسمت ها به صورت آدرس استفاده می کند.
TypeScript
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=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")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).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();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=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;
به طور پیش فرض ، قسمت متن ایجاد شده توسط سرویس AutoClotte حاوی متن استاندارد نگهدارنده است. برای اصلاح متن ، ویژگی placeholder را بر روی عنصر input تنظیم کنید:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
توجه: متن پیش فرض مکان یابی به طور خودکار بومی سازی می شود. اگر مقدار مکان نگهدارنده خود را مشخص کرده اید ، باید محلی سازی آن مقدار را در برنامه خود انجام دهید. برای کسب اطلاعات در مورد چگونگی انتخاب Google Maps JavaScript API زبان استفاده ، مستندات مربوط به محلی سازی را بخوانید.
SearchBox به کاربران امکان می دهد یک جستجوی جغرافیایی مبتنی بر متن ، مانند "پیتزا در نیویورک" یا "فروشگاه های کفش در نزدیکی خیابان رابسون" انجام دهند. می توانید SearchBox به یک قسمت متن وصل کنید و با وارد کردن متن ، این سرویس پیش بینی ها را به صورت یک لیست انتخاب کشویی باز می گرداند.
SearchBox لیست گسترده ای از پیش بینی ها را ارائه می دهد ، که می تواند شامل مکانهایی (مطابق با مکان های API) به علاوه اصطلاحات جستجوی پیشنهادی باشد. به عنوان مثال ، اگر کاربر وارد پیتزا جدید شود ، لیست انتخاب ممکن است عبارت "پیتزا در نیویورک ، نیویورک" و همچنین نام رسانه های مختلف پیتزا را شامل شود. هنگامی که یک کاربر مکانی را از لیست انتخاب می کند ، اطلاعات مربوط به آن مکان به شیء جعبه جستجو بازگردانده می شود و توسط برنامه شما قابل بازیابی است.
سازنده SearchBox دو استدلال می کند:
یک عنصر input HTML از text . این قسمت ورودی است که سرویس SearchBox نتایج آن را کنترل کرده و به آن وصل می کند.
یک آرگومان options ، که می تواند حاوی خاصیت bounds باشد: bounds یک شیء google.maps.LatLngBounds است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج نسبت به مکانهای موجود در این مرزها مغرضانه ، اما محدود نمی شوند.
کد زیر از پارامتر مرزها برای سوگیری نتایج به سمت مکانها در یک منطقه جغرافیایی خاص ، که با استفاده از مختصات Laitude/طول جغرافیایی مشخص شده است ، استفاده می کند.
هنگامی که کاربر یک مورد را از پیش بینی های متصل به کادر جستجو انتخاب می کند ، این سرویس یک رویداد places_changed آتش می زند. برای بازیابی آرایه ای که حاوی چندین پیش PlaceResult است ، می توانید با SearchBoxgetPlaces() تماس بگیرید.
برای کسب اطلاعات بیشتر در مورد شیء PlaceResult ، به اسناد مربوط به نتایج جزئیات مکان مراجعه کنید.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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 هیچ کنترل UI را اضافه نمی کند. در عوض ، مجموعه ای از اشیاء پیش بینی را برمی گرداند ، هر یک حاوی متن پیش بینی ، اطلاعات مرجع و جزئیات مربوط به چگونگی نتیجه با ورودی کاربر است. این امر مفید است اگر می خواهید کنترل بیشتری بر رابط کاربری داشته باشید از آنچه توسط جعبه Autocomplete و SearchBox توضیح داده شده است.
AutocompleteService روشهای زیر را در معرض دید قرار می دهد:
getPlacePredictions() پیش بینی های مکان را برمی گرداند. توجه: "مکان" می تواند یک مکان ، موقعیت جغرافیایی یا نکته برجسته مورد علاقه باشد ، همانطور که توسط مکان های API تعریف شده است.
getQueryPredictions() لیست گسترده ای از پیش بینی ها را برمی گرداند ، که می تواند شامل مکانهایی (مطابق با مکان های API) به علاوه اصطلاحات جستجوی پیشنهادی باشد. به عنوان مثال ، اگر کاربر وارد پیتزا جدید شود ، لیست انتخاب ممکن است عبارت "پیتزا در نیویورک ، نیویورک" و همچنین نام رسانه های مختلف پیتزا را شامل شود.
هر دو روش فوق مجموعه ای از اشیاء پیش بینی شکل زیر را برمی گردانند:
description پیش بینی همسان است.
distance_meters فاصله در متر مکان از AutocompletionRequest.origin مشخص شده است.
matched_substrings شامل مجموعه ای از بستر ها در توضیحات است که عناصر در ورودی کاربر را مطابقت می دهد. این برای برجسته کردن آن بستر های موجود در برنامه شما مفید است. در بسیاری از موارد ، پرس و جو به عنوان بستری از قسمت توضیحات ظاهر می شود.
length طول بستر است.
offset جبران شخصیت است که از ابتدای رشته توضیحات اندازه گیری می شود ، که در آن زیر لایه همسان ظاهر می شود.
place_id یک شناسه متنی است که به طور منحصر به فرد یک مکان را مشخص می کند. برای بازیابی اطلاعات در مورد مکان ، این شناسه را در قسمت placeId یک درخواست جزئیات مکان منتقل کنید. در مورد نحوه مراجعه به مکانی با شناسه مکان بیشتر بدانید.
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">functioninitService():void{constdisplaySuggestions=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)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{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">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<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 script 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() می تواند از نشانه های جلسه (در صورت اجرای) استفاده کند تا درخواست های خودکار را برای اهداف صورتحساب گروه بندی کند. Tokens Session Tokens گروه پرس و جو و انتخاب یک جستجوی خودکار کاربر در یک جلسه گسسته برای اهداف صورتحساب. جلسه از زمانی شروع می شود که کاربر شروع به تایپ کردن یک پرس و جو کند و هنگام انتخاب مکانی نتیجه می گیرد. هر جلسه می تواند چندین نمایش داده شود و به دنبال آن انتخاب یک مکان انجام شود. پس از پایان جلسه ، این نشانه دیگر معتبر نیست. برنامه شما باید برای هر جلسه یک نشانه تازه ایجاد کند. توصیه می کنیم برای همه جلسات خودکار از نشانه های جلسه استفاده کنید. اگر پارامتر sessionToken حذف شود ، یا اگر از یک جلسه جلسه استفاده مجدد می کنید ، جلسه به نظر می رسد که هیچ نشانه ای از جلسه ارائه نشده است (هر درخواست به طور جداگانه صورتحساب می شود).
شما می توانید از همان Token Session استفاده کنید تا یک درخواست جزئیات یک مکان را در مکانی که از تماس با AutocompleteService.getPlacePredictions() حاصل می شود ، استفاده کنید. در این حالت ، درخواست خودکار با درخواست جزئیات مکان ترکیب می شود و تماس به عنوان یک درخواست جزئیات مکان معمولی شارژ می شود. هیچ هزینه ای برای درخواست خودکار وجود ندارد.
حتماً برای هر جلسه جدید یک نشانه جلسه منحصر به فرد را پشت سر بگذارید. استفاده از همان نشانه برای بیش از یک جلسه خودکار ، آن جلسات ناقص را باطل می کند و کلیه درخواست های خودکار در جلسات نامعتبر به صورت جداگانه با استفاده از خودکار در هر درخواست SKU شارژ می شود. اطلاعات بیشتر در مورد نشانه های جلسه را بخوانید .
مثال زیر نشان می دهد که یک نشانه جلسه ایجاد می کند ، سپس عبور از آن در یک AutocompleteService (عملکرد displaySuggestions() برای کوتاه بودن حذف شده است):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
حتماً برای هر جلسه جدید یک نشانه جلسه منحصر به فرد را پشت سر بگذارید. استفاده از همان نشانه برای بیش از یک جلسه باعث می شود که هر درخواست به صورت جداگانه صورتحساب شود.
به طور پیش فرض ، عناصر UI ارائه شده توسط Autocomplete و SearchBox برای گنجاندن در نقشه Google طراحی شده اند. ممکن است بخواهید یک ظاهر طراحی شده را متناسب با سایت خود تنظیم کنید. کلاس های CSS زیر در دسترس است. کلیه کلاسهای ذکر شده در زیر برای هر دو ابزارک Autocomplete و SearchBox اعمال می شود.
کلاسهای CSS برای ابزارک های خودکار و جعبه جستجو
کلاس CSS
توضیحات
pac-container
عنصر بصری حاوی لیست پیش بینی های برگرفته شده توسط سرویس AutoClottle Place. این لیست به عنوان یک لیست کشویی در زیر ویجت Autocomplete یا SearchBox ظاهر می شود.
pac-icon
نماد نمایش داده شده در سمت چپ هر مورد در لیست پیش بینی ها.
pac-item
موردی در لیست پیش بینی های تهیه شده توسط ویجت Autocomplete یا SearchBox .
pac-item:hover
موردی که کاربر نشانگر ماوس خود را بر روی آن معلق می کند.
pac-item-selected
مورد هنگامی که کاربر با استفاده از صفحه کلید آن را انتخاب می کند. توجه: موارد منتخب عضو این کلاس و کلاس pac-item خواهند بود.
pac-item-query
دهانه داخل یک pac-item که قسمت اصلی پیش بینی است. برای مکانهای جغرافیایی ، این شامل یک نام مکانی مانند "سیدنی" یا نام خیابان و شماره مانند "خیابان 10 پادشاه" است. برای جستجوهای مبتنی بر متن مانند "پیتزا در نیویورک" ، حاوی متن کامل پرس و جو است. به طور پیش فرض ، pac-item-query به رنگ سیاه است. اگر متن دیگری در pac-item وجود داشته باشد ، خارج از pac-item-query است و یک ظاهر طراحی شده خود را از pac-item به ارث می برد. به طور پیش فرض به رنگ خاکستری است. متن اضافی به طور معمول یک آدرس است.
pac-matched
بخشی از پیش بینی برگشتی که با ورودی کاربر مطابقت دارد. به طور پیش فرض ، این متن همسان با متن جسورانه برجسته می شود. توجه داشته باشید که متن همسان ممکن است در هر نقطه از pac-item باشد. این لزوماً بخشی از pac-item-query نیست و می تواند تا حدودی در pac-item-query و همچنین تا حدودی در متن باقی مانده در pac-item باشد.
بهینه سازی خودکار (میراث) را بهینه کنید
در این بخش بهترین شیوه ها برای کمک به شما در استفاده بیشتر از محل خدمات خودکار (میراث) به شما کمک می کند.
از ابتدا درک از قسمت های داده های خودکار (میراث) مکان ضروری را ایجاد کنید.
زمینه های تعصب مکان و محدودیت موقعیت مکانی اختیاری هستند اما می توانند تأثیر قابل توجهی در عملکرد خودکار داشته باشند.
اگر API خطایی را برگرداند ، از کنترل خطا استفاده کنید تا اطمینان حاصل شود که برنامه شما به طرز فجیعی تخریب می شود.
اطمینان حاصل کنید که برنامه شما در صورت عدم انتخاب ، کنترل می کند و راهی برای ادامه کار به کاربران ارائه می دهد.
بهینه سازی هزینه بهترین روشها
بهینه سازی هزینه اساسی
برای بهینه سازی هزینه استفاده از سرویس Autoclotte (Legacy) Place ، از ماسک های میدانی در جزئیات (میراث) استفاده کنید و ابزارک های خودکار (میراث) را قرار دهید تا فقط قسمت های داده مورد نیاز خود را برگردانید.
بهینه سازی هزینه پیشرفته
به منظور دسترسی به قیمت گذاری درخواست و درخواست نتایج API GeoCoding در مورد مکان انتخاب شده به جای جزئیات مکان (میراث) ، اجرای برنامه نویسی مکان (میراث) مکان (میراث) را در نظر بگیرید. قیمت هر درخواست جفت شده با API GeoCoding مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) در صورت برآورده شدن هر دو شرایط زیر است:
اگر فقط به عرض جغرافیایی/طول جغرافیایی یا آدرس محل انتخاب شده کاربر نیاز دارید ، API GeoCoding این اطلاعات را برای کمتر از یک مکان (میراث) در تماس ارائه می دهد.
اگر کاربران پیش بینی خودکار را به طور متوسط در چهار مکان درخواست های پیش بینی خودکار (میراث) یا کمتر از آنها انتخاب کنند ، در هر درخواست قیمت گذاری ممکن است مقرون به صرفه تر از قیمت گذاری هر جلسه باشد.
برای کمک به انتخاب پیاده سازی AutoClottle (Legacy) که متناسب با نیازهای شما باشد ، برگه ای را که مطابق با پاسخ شما به سوال زیر است ، انتخاب کنید.
آیا برنامه شما به اطلاعاتی غیر از آدرس و عرض جغرافیایی/طول جغرافیایی پیش بینی انتخاب شده نیاز دارد؟
The following guidelines describe ways to optimize Place Autocomplete (Legacy) performance:
Add country restrictions, location biasing , and (for programmatic implementations) language preference to your Place Autocomplete (Legacy) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
If Place Autocomplete (Legacy) is accompanied by a map, you can bias location by map viewport.
In situations when a user does not choose one of the Place Autocomplete (Legacy) predictions, generally because none of those predictions are the result-address wanted, you can reuse the original user input to attempt to get more relevant results:
If you expect the user to enter only address information, reuse the original user input in a call to the Geocoding API .
If you expect the user to enter queries for a specific place by name or address, use a Find Place (Legacy) request . If results are only expected in a specific region, use location biasing .
Other scenarios when it's best to fall back to the Geocoding API include:
Users inputting subpremise addresses, such as addresses for specific units or apartments within a building. For example, the Czech address "Stroupežnického 3191/17, Praha" yields a partial prediction in Place Autocomplete (Legacy).
Users inputting addresses with road-segment prefixes like "23-30 29th St, Queens" in New York City or "47-380 Kamehameha Hwy, Kaneohe" on the island of Kauai in Hawai'i.
