این صفحه کتابخانه سمت سرویس گیرنده موجود با 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 Console، در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید، فعال است.
برای مشاهده لیست API های فعال:
- به Google Cloud Console بروید.
- روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
- از لیست APIها در داشبورد ، Places API را جستجو کنید.
- اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
- در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
- Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
- ENABLE را انتخاب کنید. پس از پایان فرآیند، Places API در فهرست APIها در داشبورد ظاهر میشود.
در حال بارگیری کتابخانه
سرویس Places یک کتابخانه مستقل و جدا از کد اصلی Maps JavaScript API است. برای استفاده از عملکرد موجود در این کتابخانه، ابتدا باید آن را با استفاده از پارامتر libraries
در URL بوت استرپ Maps API بارگیری کنید:
<script async src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY &loading=async&libraries=places&callback=initMap"> </script>
برای اطلاعات بیشتر به نمای کلی کتابخانه ها مراجعه کنید.
خلاصه کلاس ها
API دو نوع ویجت تکمیل خودکار را ارائه می دهد که می توانید به ترتیب از طریق کلاس های Autocomplete
و SearchBox
اضافه کنید. علاوه بر این، میتوانید از کلاس AutocompleteService
برای بازیابی نتایج تکمیل خودکار به صورت برنامهنویسی استفاده کنید (به مرجع Maps JavaScript API مراجعه کنید: کلاس AutocompleteService ).
در زیر خلاصه ای از کلاس های موجود است:
-
Autocomplete
یک فیلد ورودی متن را به صفحه وب شما اضافه می کند و آن فیلد را برای ورود کاراکترها کنترل می کند. همانطور که کاربر متن را وارد می کند، تکمیل خودکار پیش بینی های مکان را در قالب یک لیست انتخاب کشویی برمی گرداند. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به مکان به شی تکمیل خودکار بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود. جزئیات را در زیر مشاهده کنید. -
SearchBox
یک فیلد ورودی متن را به صفحه وب شما اضافه می کند، تقریباً مانندAutocomplete
. تفاوت ها به شرح زیر است:- تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می شوند.
SearchBox
فهرست گستردهای از پیشبینیها را ارائه میکند که میتواند شامل مکانها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاههای مختلف پیتزا باشد. -
SearchBox
گزینه های کمتری نسبت بهAutocomplete
برای محدود کردن جستجو ارائه می دهد. در حالت اول، می توانید جستجو را به سمتLatLngBounds
معین سوگیری کنید. در حالت دوم، میتوانید جستجو را به یک کشور خاص و انواع مکانهای خاص محدود کنید، و همچنین محدودیتها را تعیین کنید. برای اطلاعات بیشتر، زیر را ببینید.
- تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می شوند.
- می توانید یک شی
AutocompleteService
برای بازیابی پیش بینی ها به صورت برنامه ای ایجاد کنید. برای بازیابی مکانهای منطبق باgetPlacePredictions()
یا برای بازیابی مکانهای منطبق و عبارات جستجوی پیشنهادیgetQueryPredictions()
را تماس بگیرید. توجه:AutocompleteService
هیچ کنترل رابط کاربری اضافه نمی کند. در عوض، روشهای فوق آرایهای از اشیاء پیشبینی را برمیگردانند. هر شیء پیشبینی حاوی متن پیشبینی، و همچنین اطلاعات مرجع و جزئیات نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر مشاهده کنید.
افزودن ویجت تکمیل خودکار
ویجت Autocomplete
یک فیلد ورودی متن را در صفحه وب شما ایجاد می کند، پیش بینی مکان ها را در لیست انتخاب رابط کاربری ارائه می دهد و جزئیات مکان را در پاسخ به درخواست getPlace()
برمی گرداند. هر ورودی در لیست انتخاب مربوط به یک مکان واحد است (همانطور که توسط Places API تعریف شده است).
سازنده Autocomplete
دو آرگومان می گیرد:
- یک عنصر
input
HTML از نوعtext
. این فیلد ورودی است که سرویس تکمیل خودکار نتایج آن را نظارت کرده و به آن پیوست می کند. - یک آرگومان اختیاری
AutocompleteOptions
که می تواند حاوی ویژگی های زیر باشد:- آرایه ای از
fields
داده که باید در پاسخPlace Details
برایPlaceResult
انتخابی کاربر گنجانده شود. اگر ویژگی تنظیم نشده باشد یا اگر['ALL']
وارد شود، همه فیلدهای موجود برگردانده شده و برای آنها صورتحساب دریافت میشود (این برای استقرار تولید توصیه نمیشود). برای فهرستی از فیلدها،PlaceResult
ببینید. - آرایه ای از
types
که نوع صریح یا مجموعه نوع را مشخص می کند، همانطور که در انواع پشتیبانی شده فهرست شده است. اگر نوع مشخص نشده باشد، همه انواع برگردانده می شوند. -
bounds
یک شیgoogle.maps.LatLngBounds
است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج به سمت مکانهایی که در این محدودهها قرار دارند، تعصب دارند، اما محدود به آنها نیستند. -
strictBounds
یکboolean
است که مشخص میکند آیا API باید فقط مکانهایی را برگرداند که دقیقاً در منطقه تعریفشده باbounds
داده شده هستند یا خیر. API نتایج خارج از این منطقه را حتی اگر با ورودی کاربر مطابقت داشته باشد برنمیگرداند. -
componentRestrictions
می تواند برای محدود کردن نتایج به گروه های خاص استفاده شود. در حال حاضر، میتوانید ازcomponentRestrictions
برای فیلتر کردن حداکثر ۵ کشور استفاده کنید. کشورها باید به عنوان کد کشوری دو کاراکتری و سازگار با ISO 3166-1 Alpha-2 ارسال شوند. چندین کشور باید به عنوان فهرستی از کدهای کشور ارسال شوند.توجه: اگر نتایج غیرمنتظرهای را با کد کشور دریافت کردید، بررسی کنید که از کدی استفاده میکنید که شامل کشورها، مناطق وابسته و مناطق خاص جغرافیایی مورد نظر شما میشود. اطلاعات کد را میتوانید در ویکیپدیا بیابید: فهرست کدهای کشورها ISO 3166 یا پلتفرم مرور آنلاین ISO .
-
placeIdOnly
میتواند برای دستور دادن به ویجتAutocomplete
برای بازیابی فقط شناسههای مکان استفاده شود. هنگام فراخوانیgetPlace()
در شیءAutocomplete
،PlaceResult
موجود تنها دارایplace id
،types
و خصوصیاتname
است. میتوانید از شناسه مکان برگشتی با تماسهایی که با سرویسهای مکانها، کدگذاری جغرافیایی، مسیرها یا ماتریس فاصله دارد استفاده کنید.
- آرایه ای از
محدود کردن پیشبینیهای تکمیل خودکار
بهطور پیشفرض، «تکمیل خودکار مکان» همه انواع مکانها را ارائه میکند که برای پیشبینیهای نزدیک به مکان کاربر تعصب دارند و همه فیلدهای داده موجود را برای مکان انتخابی کاربر واکشی میکند. گزینههای تکمیل خودکار مکان را تنظیم کنید تا پیشبینیهای مرتبطتری بر اساس مورد استفاده شما ارائه شود.
گزینه ها را در ساخت و ساز تنظیم کنید
سازنده Autocomplete
یک پارامتر AutocompleteOptions
را برای تعیین محدودیت در ایجاد ویجت می پذیرد. مثال زیر گزینههای bounds
، componentRestrictions
و types
برای درخواست مکانهای نوع establishment
، ترجیح میدهد که در منطقه جغرافیایی مشخص شده و پیشبینیها را فقط به مکانهای داخل ایالات متحده محدود میکند. تنظیم گزینه fields
مشخص می کند که چه اطلاعاتی در مورد مکان انتخابی کاربر بازگردانده شود.
برای تغییر مقدار یک گزینه برای ویجت موجود setOptions()
را فراخوانی کنید.
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
فیلدهای داده را مشخص کنید
فیلدهای داده را مشخص کنید تا از دریافت صورتحساب برای مکانهای SKU داده مکانهایی که به آنها نیاز ندارید اجتناب کنید. همانطور که در مثال قبلی نشان داده شد، ویژگی fields
را در AutocompleteOptions
که به سازنده ویجت ارسال می شود، اضافه کنید، یا setFields()
را روی یک شیء Autocomplete
موجود فراخوانی کنید.
autocomplete.setFields(["place_id", "geometry", "name"]);
تعصبات و مرزهای ناحیه جستجو را برای تکمیل خودکار تعریف کنید
میتوانید نتایج تکمیل خودکار را برای یک مکان یا منطقه تقریبی به روشهای زیر سوگیری کنید:
- مرزها را برای ایجاد شی
Autocomplete
تنظیم کنید. - محدوده های موجود در
Autocomplete
موجود را تغییر دهید. - محدوده ها را برای نمای نقشه تنظیم کنید.
- جستجو را محدود کنید.
- جستجو را به یک کشور خاص محدود کنید.
مثال قبلی تعیین حد و مرز در ایجاد را نشان می دهد. مثالهای زیر سایر تکنیکهای بایاسینگ را نشان میدهند.
محدوده یک تکمیل خودکار موجود را تغییر دهید
برای تغییر ناحیه جستجو در یک Autocomplete
موجود به کران های مستطیلی setBounds()
فراخوانی کنید.
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
محدوده ها را برای نمای نقشه تنظیم کنید
از bindTo()
برای سوگیری نتایج به نمای نقشه استفاده کنید، حتی در زمانی که نمایپورت تغییر می کند.
autocomplete.bindTo("bounds", map);
autocomplete.bindTo("bounds", map);
از unbind()
برای جدا کردن پیشبینیهای تکمیل خودکار از نمای نقشه استفاده کنید.
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
جستجو را به محدوده فعلی محدود کنید
گزینه strictBounds
را تنظیم کنید تا نتایج را به کران های فعلی محدود کنید، چه بر اساس نمای نقشه و چه بر اساس مرزهای مستطیلی.
autocomplete.setOptions({ strictBounds: true });
پیش بینی ها را به یک کشور خاص محدود کنید
از گزینه componentRestrictions
استفاده کنید یا setComponentRestrictions()
را فراخوانی کنید تا جستجوی تکمیل خودکار را به مجموعه خاصی از حداکثر پنج کشور محدود کنید.
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
انواع مکان های محدود
از گزینه types
یا فراخوانی setTypes()
برای محدود کردن پیشبینیها به انواع مکانهای خاص استفاده کنید. این محدودیت یک نوع یا یک مجموعه نوع را مشخص می کند، همانطور که در Place Types فهرست شده است. اگر هیچ محدودیتی مشخص نشده باشد، همه انواع برگردانده می شوند.
برای مقدار گزینه types
یا مقدار ارسال شده به setTypes()
می توانید یکی از این موارد را مشخص کنید:
آرایه ای حاوی حداکثر پنج مقدار از جدول 1 یا جدول 2 از انواع مکان . به عنوان مثال:
types: ['hospital', 'pharmacy', 'bakery', 'country']
یا:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- هر یک از فیلترها در جدول 3 از انواع مکان . شما فقط می توانید یک مقدار را از جدول 3 مشخص کنید.
درخواست رد می شود در صورتی که:
- شما بیش از پنج نوع را مشخص می کنید.
- شما انواع ناشناخته را مشخص می کنید.
- هر نوع از جدول 1 یا جدول 2 را با هر فیلتری از جدول 3 مخلوط می کنید.
نسخه ی نمایشی تکمیل خودکار مکان ها تفاوت در پیش بینی ها بین انواع مکان های مختلف را نشان می دهد.
دریافت اطلاعات مکان
وقتی کاربر مکانی را از پیشبینیهای پیوست شده به فیلد متن تکمیل خودکار انتخاب میکند، سرویس یک رویداد place_changed
را فعال میکند. برای دریافت جزئیات مکان:
- یک کنترل کننده رویداد برای رویداد
place_changed
ایجاد کنید، وaddListener()
را در شیAutocomplete
فراخوانی کنید تا کنترل کننده را اضافه کنید. -
Autocomplete.getPlace()
را در شیءAutocomplete
فراخوانی کنید تا یک شیPlaceResult
بازیابی کنید، سپس می توانید از آن برای دریافت اطلاعات بیشتر در مورد مکان انتخاب شده استفاده کنید.
بهطور پیشفرض، وقتی کاربر مکانی را انتخاب میکند، تکمیل خودکار تمام فیلدهای داده موجود را برای مکان انتخابی برمیگرداند و بر اساس آن صورتحساب به شما تعلق میگیرد. از Autocomplete.setFields()
برای تعیین فیلدهای داده مکان برای بازگشت استفاده کنید. درباره شی PlaceResult
، از جمله لیستی از فیلدهای داده مکان که می توانید درخواست کنید، بیشتر بخوانید. برای جلوگیری از پرداخت هزینه برای دادههایی که به آنها نیاز ندارید، حتماً از Autocomplete.setFields()
استفاده کنید تا فقط دادههای مکانی را که استفاده میکنید مشخص کنید.
ویژگی name
حاوی description
مربوط به پیشبینیهای تکمیل خودکار مکانها است. میتوانید درباره description
در مستندات تکمیل خودکار مکانها بیشتر بخوانید.
برای فرم های آدرس، دریافت آدرس در قالب ساختار یافته مفید است. برای برگرداندن آدرس ساخت یافته برای مکان انتخاب شده، Autocomplete.setFields()
را فراخوانی کنید و فیلد address_components
را مشخص کنید.
مثال زیر از تکمیل خودکار برای پر کردن فیلدها در فرم آدرس استفاده می کند.
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
سفارشی کردن متن مکان نگهدار
به طور پیشفرض، فیلد متنی ایجاد شده توسط سرویس تکمیل خودکار حاوی متن متغیر متغیر استاندارد است. برای تغییر متن، ویژگی placeholder
را روی عنصر input
تنظیم کنید:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
توجه: متن مکاننمای پیشفرض بهطور خودکار بومیسازی میشود. اگر مقدار متغیر مکان خود را مشخص کنید، باید محلی سازی آن مقدار را در برنامه خود انجام دهید. برای کسب اطلاعات در مورد نحوه انتخاب زبان مورد استفاده توسط Google Maps JavaScript API، لطفاً اسناد مربوط به بومیسازی را بخوانید.
برای سفارشی کردن ظاهر ویجت ، به ویجتهای تکمیل خودکار و SearchBox نگاه کنید.
افزودن ویجت SearchBox
SearchBox
به کاربران اجازه می دهد تا جستجوی جغرافیایی مبتنی بر متن را انجام دهند، مانند «پیتزا در نیویورک» یا «فروشگاه های کفش در نزدیکی خیابان رابسون». میتوانید SearchBox
به یک فیلد متنی وصل کنید و با وارد کردن متن، سرویس پیشبینیها را در قالب فهرست انتخابی کشویی برمیگرداند.
SearchBox
فهرست گستردهای از پیشبینیها را ارائه میکند که میتواند شامل مکانها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاههای مختلف پیتزا باشد. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به آن مکان به شی SearchBox بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود.
سازنده SearchBox
دو آرگومان می گیرد:
- یک عنصر
input
HTML از نوعtext
. این فیلد ورودی است که سرویسSearchBox
آن را نظارت کرده و نتایج خود را به آن پیوست می کند. - یک آرگومان
options
، که میتواند حاوی ویژگیbounds
باشد:bounds
یک شیgoogle.maps.LatLngBounds
است که منطقهای را که در آن مکانها جستجو میشود را مشخص میکند. نتایج به سمت مکانهایی که در این محدودهها قرار دارند، تعصب دارند، اما محدود به آنها نیستند.
کد زیر از پارامتر کرانهها برای سوگیری نتایج به سمت مکانهایی در یک منطقه جغرافیایی خاص استفاده میکند که از طریق مختصات طول/طول جغرافیایی مشخص شدهاند.
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
تغییر ناحیه جستجو برای SearchBox
برای تغییر ناحیه جستجو برای SearchBox
موجود، setBounds()
در شی SearchBox
فراخوانی کنید و شی LatLngBounds
مربوطه را ارسال کنید.
دریافت اطلاعات مکان
هنگامی که کاربر موردی را از پیشبینیهای پیوست شده به کادر جستجو انتخاب میکند، سرویس یک رویداد places_changed
را فعال میکند. میتوانید getPlaces()
در شی SearchBox
فراخوانی کنید تا آرایهای حاوی چندین پیشبینی را بازیابی کنید که هر کدام یک شی PlaceResult
هستند.
برای اطلاعات بیشتر درباره شی PlaceResult
، به مستندات مربوط به نتایج جزئیات مکان مراجعه کنید.
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
برای سفارشی کردن ظاهر ویجت ، به ویجتهای تکمیل خودکار و SearchBox نگاه کنید.
بازیابی برنامهای پیشبینیهای سرویس تکمیل خودکار مکان
برای بازیابی پیش بینی ها به صورت برنامه ای، از کلاس AutocompleteService
استفاده کنید. AutocompleteService
هیچ کنترل رابط کاربری اضافه نمی کند. در عوض، آرایهای از اشیاء پیشبینی را برمیگرداند که هر کدام حاوی متن پیشبینی، اطلاعات مرجع و جزئیات نحوه مطابقت نتیجه با ورودی کاربر است. اگر میخواهید کنترل بیشتری روی رابط کاربری نسبت به آنچه که توسط Autocomplete
و SearchBox
که در بالا توضیح داده شده است، داشته باشید، مفید است.
AutocompleteService
روش های زیر را در معرض نمایش قرار می دهد:
-
getPlacePredictions()
پیش بینی های مکان را برمی گرداند. توجه: «مکان» میتواند یک مؤسسه، موقعیت جغرافیایی یا نقطهی مهم مورد علاقه باشد که توسط Places API تعریف شده است. -
getQueryPredictions()
لیست گسترده ای از پیش بینی ها را برمی گرداند که می تواند شامل مکان ها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاههای مختلف پیتزا باشد.
هر دو روش فوق آرایه ای از اشیاء پیش بینی را به شکل زیر برمی گرداند:
-
description
پیشبینی منطبق است. -
distance_meters
فاصله بر حسب متر از مکان ازAutocompletionRequest.origin
مشخص شده است. -
matched_substrings
شامل مجموعه ای از زیر رشته ها در توضیحات است که عناصر ورودی کاربر را مطابقت می دهد. این برای برجسته کردن رشته های فرعی در برنامه شما مفید است. در بسیاری از موارد، پرس و جو به عنوان زیر رشته فیلد توضیحات ظاهر می شود.-
length
طول رشته فرعی است. -
offset
عبارت است از آفست کاراکتر که از ابتدای رشته توضیحات اندازه گیری می شود و در آن رشته فرعی مطابقت داده شده ظاهر می شود.
-
-
place_id
یک شناسه متنی است که به طور منحصر به فرد یک مکان را شناسایی می کند. برای بازیابی اطلاعات مربوط به مکان، این شناسه را در قسمتplaceId
درخواست جزئیات مکان ارسال کنید. درباره نحوه ارجاع مکان با شناسه مکان بیشتر بیاموزید. -
terms
آرایه ای است که شامل عناصر پرس و جو است. برای یک مکان، هر عنصر معمولاً بخشی از آدرس را تشکیل می دهد.-
offset
عبارت است از آفست کاراکتر که از ابتدای رشته توضیحات اندازه گیری می شود و در آن رشته فرعی مطابقت داده شده ظاهر می شود. -
value
عبارت تطبیقی است.
-
مثال زیر یک درخواست پیشبینی پرس و جو را برای عبارت «pizza near» اجرا میکند و نتیجه را در یک لیست نمایش میدهد.
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
<html> <head> <title>Retrieving Autocomplete Predictions</title> <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>
Sample را امتحان کنید
نشانه های جلسه
AutocompleteService.getPlacePredictions()
می تواند از نشانه های جلسه (در صورت پیاده سازی) برای گروه بندی درخواست های تکمیل خودکار برای اهداف صورتحساب استفاده کند. نشانههای جلسه، مراحل پرس و جو و انتخاب یک جستجوی تکمیل خودکار کاربر را در یک جلسه مجزا برای اهداف صورتحساب گروهبندی میکنند. جلسه زمانی شروع می شود که کاربر شروع به تایپ یک پرس و جو می کند، و با انتخاب مکان به پایان می رسد. هر جلسه می تواند چندین پرس و جو داشته باشد و به دنبال آن یک مکان انتخاب شود. پس از پایان جلسه، رمز دیگر معتبر نیست. برنامه شما باید برای هر جلسه یک نشانه جدید تولید کند. توصیه می کنیم از نشانه های جلسه برای تمام جلسات تکمیل خودکار استفاده کنید. اگر پارامتر sessionToken
حذف شود، یا اگر از یک نشانه جلسه استفاده مجدد کنید، هزینه جلسه به گونه ای محاسبه می شود که گویی هیچ نشانه جلسه ارائه نشده است (هر درخواست جداگانه صورتحساب می شود).
میتوانید از همان نشانه جلسه برای ایجاد یک درخواست جزئیات مکان در مکانی که از تماس با AutocompleteService.getPlacePredictions()
ناشی میشود، استفاده کنید. در این حالت، درخواست تکمیل خودکار با درخواست جزئیات مکان ترکیب می شود و هزینه تماس به عنوان یک درخواست معمولی جزئیات مکان محاسبه می شود. برای درخواست تکمیل خودکار هزینه ای دریافت نمی شود.
مطمئن شوید که برای هر جلسه جدید یک نشانه جلسه منحصر به فرد ارسال می کنید. استفاده از یک نشانه برای بیش از یک جلسه تکمیل خودکار، آن جلسات تکمیل خودکار را باطل میکند و تمام درخواستهای تکمیل خودکار در جلسات نامعتبر به صورت جداگانه با استفاده از تکمیل خودکار در هر درخواست SKU کسر میشود. درباره نشانه های جلسه بیشتر بخوانید .
مثال زیر ایجاد یک نشانه جلسه، سپس ارسال آن در AutocompleteService
را نشان می دهد (عملکرد displaySuggestions()
برای اختصار حذف شده است):
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
مطمئن شوید که برای هر جلسه جدید یک نشانه جلسه منحصر به فرد ارسال می کنید. استفاده از یک نشانه برای بیش از یک جلسه باعث می شود که هر درخواست به صورت جداگانه صورتحساب شود.
درباره نشانه های جلسه بیشتر بخوانید .
استایل دادن به ویجت های تکمیل خودکار و SearchBox
بهطور پیشفرض، عناصر رابط کاربری ارائهشده توسط Autocomplete
و SearchBox
برای گنجاندن در نقشه Google سبکسازی میشوند. ممکن است بخواهید استایل را مطابق با سایت خود تنظیم کنید. کلاس های CSS زیر در دسترس هستند. همه کلاسهای فهرستشده در زیر برای ویجتهای Autocomplete
و 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 باشد. |
بهینه سازی تکمیل خودکار مکان
این بخش بهترین روشها را توضیح میدهد تا به شما کمک کند از خدمات تکمیل خودکار مکان حداکثر استفاده را ببرید.
در اینجا چند دستورالعمل کلی وجود دارد:
- سریعترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ابزارک تکمیل خودکار Maps JavaScript API، Places SDK برای ویجت تکمیل خودکار Android، یا Places SDK برای کنترل رابط کاربری خودکار iOS است.
- از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان ضروری ایجاد کنید.
- فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
- از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمیگرداند، برنامه شما به خوبی کاهش مییابد.
- مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.
بهترین شیوه های بهینه سازی هزینه
بهینه سازی هزینه پایه
برای بهینهسازی هزینه استفاده از سرویس تکمیل خودکار مکان، از ماسکهای فیلد در ویجتهای Place Details و Place Autocomplete استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.
بهینه سازی هزینه پیشرفته
برای دسترسی به قیمت هر درخواست و درخواست نتایج Geocoding API در مورد مکان انتخابی به جای جزئیات مکان، اجرای برنامهای تکمیل خودکار مکان را در نظر بگیرید. قیمت گذاری هر درخواست جفت شده با Geocoding API مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) است اگر هر دو شرایط زیر رعایت شود:
- اگر فقط به طول/طول جغرافیایی یا آدرس مکان انتخابی کاربر نیاز دارید، API Geocoding این اطلاعات را کمتر از یک تماس با جزئیات مکان ارائه میکند.
- اگر کاربران یک پیشبینی تکمیل خودکار را در چهار درخواست پیشبینی تکمیل خودکار یا کمتر انتخاب کنند، ممکن است قیمتگذاری به ازای هر درخواست مقرونبهصرفهتر از قیمتگذاری در هر جلسه باشد.
آیا برنامه شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیش بینی انتخاب شده نیاز دارد؟
از تکمیل خودکار مکان مبتنی بر جلسه با جزئیات مکان استفاده کنید.
از آنجایی که برنامه شما به جزئیات مکان مانند نام مکان، وضعیت کسب و کار، یا ساعات کاری نیاز دارد، پیاده سازی تکمیل خودکار مکان شما باید از یک نشانه جلسه ( به صورت برنامه نویسی یا تعبیه شده در ویجت های جاوا اسکریپت ، اندروید ، یا iOS ) با هزینه کل 0.017 دلار برای هر استفاده کند. بسته به فیلدهای داده مکانی که درخواست می کنید، session plus SKU های داده مکان های قابل اجرا. 1
پیاده سازی ویجت
مدیریت جلسه به طور خودکار در ویجت های جاوا اسکریپت ، اندروید یا iOS تعبیه شده است. این شامل درخواستهای تکمیل خودکار مکان و درخواست جزئیات مکان در پیشبینی انتخابشده است. حتماً پارامتر fields
را مشخص کنید تا مطمئن شوید که فقط فیلدهای داده مکان مورد نیاز خود را درخواست می کنید.
اجرای برنامه ای
با درخواست های تکمیل خودکار مکان خود از یک نشانه جلسه استفاده کنید. هنگام درخواست جزئیات مکان درباره پیشبینی انتخابشده، پارامترهای زیر را در نظر بگیرید:
- شناسه مکان از پاسخ تکمیل خودکار مکان
- نشانه جلسه مورد استفاده در درخواست تکمیل خودکار مکان
- پارامتر
fields
فیلدهای داده مکان مورد نیاز را مشخص می کند
بسته به عملکرد استفاده از تکمیل خودکار مکان، API جغرافیایی میتواند گزینه مقرونبهصرفهتری نسبت به جزئیات مکان برای برنامه شما باشد. بازده تکمیل خودکار هر برنامه بسته به اینکه چه کاربرانی وارد میشوند، جایی که برنامه در حال استفاده است، و اینکه آیا بهترین شیوههای بهینهسازی عملکرد اجرا شدهاند، متفاوت است.
برای پاسخ به سؤال زیر، قبل از انتخاب پیشبینی تکمیل خودکار مکان در برنامه، تحلیل کنید که کاربر به طور میانگین چند کاراکتر تایپ میکند.
آیا کاربران شما پیشبینی تکمیل خودکار مکان را به طور متوسط در چهار درخواست یا کمتر انتخاب میکنند؟
Place Autocomplete را به صورت برنامهنویسی و بدون نشانههای جلسه اجرا کنید و API Geocoding را در پیشبینی مکان انتخابشده فراخوانی کنید.
Geocoding API آدرس ها و مختصات طول و عرض جغرافیایی را برای هر درخواست 0.005 دلار ارائه می دهد. ایجاد چهار درخواست تکمیل خودکار مکان - به ازای هر درخواست 0.01132 دلار هزینه دارد، بنابراین هزینه کل چهار درخواست به اضافه یک تماس API جغرافیایی در مورد پیش بینی مکان انتخابی 0.01632 دلار خواهد بود که کمتر از قیمت تکمیل خودکار در هر جلسه 0.017 دلار در هر جلسه است. 1
بهترین روشهای عملکرد را برای کمک به کاربران خود در نظر بگیرید تا پیشبینی مورد نظر خود را با نویسههای کمتری دریافت کنند.
از تکمیل خودکار مکان مبتنی بر جلسه با جزئیات مکان استفاده کنید.
از آنجایی که میانگین تعداد درخواستهایی که انتظار دارید قبل از انتخاب یک پیشبینی تکمیل خودکار مکان از سوی کاربر، از هزینه قیمتگذاری در هر جلسه بیشتر باشد، پیادهسازی تکمیل خودکار مکان شما باید از یک نشانه جلسه هم برای درخواستهای تکمیل خودکار مکان و هم برای درخواست جزئیات مکان مرتبط استفاده کند. هزینه کل 0.017 دلار در هر جلسه . 1
پیاده سازی ویجت
مدیریت جلسه به طور خودکار در ویجت های جاوا اسکریپت ، اندروید یا iOS تعبیه شده است. این شامل درخواستهای تکمیل خودکار مکان و درخواست جزئیات مکان در پیشبینی انتخابشده است. حتماً پارامتر fields
را مشخص کنید تا مطمئن شوید که فقط فیلدهای Basic Data را درخواست می کنید.
اجرای برنامه ای
با درخواست های تکمیل خودکار مکان خود از یک نشانه جلسه استفاده کنید. هنگام درخواست جزئیات مکان درباره پیشبینی انتخابشده، پارامترهای زیر را در نظر بگیرید:
- شناسه مکان از پاسخ تکمیل خودکار مکان
- نشانه جلسه مورد استفاده در درخواست تکمیل خودکار مکان
- پارامتر
fields
فیلدهای داده های پایه مانند آدرس و هندسه را مشخص می کند
درخواستهای تکمیل خودکار مکان را به تأخیر بیندازید
میتوانید از استراتژیهایی مانند تأخیر در درخواست تکمیل خودکار مکان استفاده کنید تا زمانی که کاربر سه یا چهار کاراکتر اول را تایپ کند تا برنامه شما درخواستهای کمتری داشته باشد. برای مثال، ایجاد درخواستهای تکمیل خودکار مکان برای هر کاراکتر پس از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه را تایپ کند و سپس پیشبینیای را انتخاب کند که برای آن یک درخواست API Geocoding انجام دهید، کل هزینه 0.01632 دلار (4 * 0.00283 خودکار تکمیل خودکار) خواهد بود. در هر درخواست + 0.005 دلار رمزگذاری جغرافیایی). 1
اگر درخواستهای با تأخیر میتوانند میانگین درخواست برنامهای شما را به زیر چهار برسانند، میتوانید از راهنماییهای مربوط به تکمیل خودکار مکان با اجرای API Geocoding پیروی کنید. توجه داشته باشید که درخواستهای تأخیر را میتوان بهعنوان تأخیر برای کاربری که ممکن است انتظار داشته باشد با هر ضربه کلید جدید، پیشبینیهایی را ببیند، درک شود.
بهترین روشهای عملکرد را برای کمک به کاربران خود در نظر بگیرید تا پیشبینی مورد نظر خود را با نویسههای کمتری دریافت کنند.
هزینه های ذکر شده در اینجا به USD هستند. لطفاً برای اطلاعات کامل قیمت به صفحه صورتحساب پلتفرم Google Maps مراجعه کنید.
بهترین شیوه های عملکرد
دستورالعملهای زیر راههایی را برای بهینهسازی عملکرد تکمیل خودکار مکان توضیح میدهند:
- محدودیتهای کشور، سوگیری موقعیت و اولویت زبان (برای اجرای برنامهای) را به پیادهسازی تکمیل خودکار مکان خود اضافه کنید. اولویت زبان با ویجت ها مورد نیاز نیست زیرا آنها ترجیحات زبان را از مرورگر کاربر یا دستگاه تلفن همراه انتخاب می کنند.
- اگر «تکمیل خودکار مکان» با نقشه همراه باشد، میتوانید مکان را با درگاه نمای نقشه سوگیری کنید.
- در شرایطی که کاربر یکی از پیشبینیهای تکمیل خودکار را انتخاب نمیکند، عموماً چون هیچ یک از آن پیشبینیها نشانی نتیجه دلخواه نیستند، میتوانید از ورودی اصلی کاربر برای تلاش برای دریافت نتایج مرتبطتر دوباره استفاده کنید:
- اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند، از ورودی اصلی کاربر در تماس با API جغرافیایی استفاده مجدد کنید.
- اگر از کاربر انتظار دارید که پرس و جوهایی را برای مکان خاصی با نام یا آدرس وارد کند، از درخواست Find Place استفاده کنید. اگر نتایج فقط در یک منطقه خاص مورد انتظار است، از بایاس مکان استفاده کنید.
- کاربرانی که آدرسهای فرعی را وارد میکنند، مانند آدرسهای واحدها یا آپارتمانهای خاص در یک ساختمان. به عنوان مثال، آدرس چک "Stroupežnického 3191/17, Praha" یک پیش بینی جزئی در تکمیل خودکار مکان به دست می دهد.
- کاربرانی که آدرسهایی را با پیشوندهای بخش جاده مانند «23-30 29th, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره Kauai در هاوایی وارد میکنند.
محدودیت ها و سیاست های استفاده
سهمیه ها
برای اطلاعات سهمیه و قیمت، به مستندات استفاده و صورتحساب برای Places API مراجعه کنید.
سیاست ها
استفاده از کتابخانه مکانها، Maps JavaScript API باید مطابق با خطمشیهای توصیفشده برای Places API باشد.
،این صفحه کتابخانه سمت سرویس گیرنده موجود با 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 Console، در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید، فعال است.
برای مشاهده لیست API های فعال:
- به Google Cloud Console بروید.
- روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
- از لیست APIها در داشبورد ، Places API را جستجو کنید.
- اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
- در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
- Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
- ENABLE را انتخاب کنید. پس از پایان فرآیند، Places API در فهرست APIها در داشبورد ظاهر میشود.
در حال بارگیری کتابخانه
سرویس Places یک کتابخانه مستقل و جدا از کد اصلی Maps JavaScript API است. برای استفاده از عملکرد موجود در این کتابخانه، ابتدا باید آن را با استفاده از پارامتر libraries
در URL بوت استرپ Maps API بارگیری کنید:
<script async src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY &loading=async&libraries=places&callback=initMap"> </script>
برای اطلاعات بیشتر به نمای کلی کتابخانه ها مراجعه کنید.
خلاصه کلاس ها
API دو نوع ویجت تکمیل خودکار را ارائه می دهد که می توانید به ترتیب از طریق کلاس های Autocomplete
و SearchBox
اضافه کنید. علاوه بر این، میتوانید از کلاس AutocompleteService
برای بازیابی نتایج تکمیل خودکار به صورت برنامهنویسی استفاده کنید (به مرجع Maps JavaScript API مراجعه کنید: کلاس AutocompleteService ).
در زیر خلاصه ای از کلاس های موجود است:
-
Autocomplete
یک فیلد ورودی متن را به صفحه وب شما اضافه می کند و آن فیلد را برای ورود کاراکترها کنترل می کند. همانطور که کاربر متن را وارد می کند، تکمیل خودکار پیش بینی های مکان را در قالب یک لیست انتخاب کشویی برمی گرداند. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به مکان به شی تکمیل خودکار بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود. جزئیات را در زیر مشاهده کنید. -
SearchBox
یک فیلد ورودی متن را به صفحه وب شما اضافه می کند، تقریباً مانندAutocomplete
. تفاوت ها به شرح زیر است:- تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می شوند.
SearchBox
فهرست گستردهای از پیشبینیها را ارائه میکند که میتواند شامل مکانها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاههای مختلف پیتزا باشد. -
SearchBox
گزینه های کمتری نسبت بهAutocomplete
برای محدود کردن جستجو ارائه می دهد. در حالت اول، می توانید جستجو را به سمتLatLngBounds
معین سوگیری کنید. در حالت دوم، میتوانید جستجو را به یک کشور خاص و انواع مکانهای خاص محدود کنید، و همچنین محدودیتها را تعیین کنید. برای اطلاعات بیشتر، زیر را ببینید.
- تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می شوند.
- می توانید یک شی
AutocompleteService
برای بازیابی پیش بینی ها به صورت برنامه ای ایجاد کنید. برای بازیابی مکانهای منطبق باgetPlacePredictions()
یا برای بازیابی مکانهای منطبق و عبارات جستجوی پیشنهادیgetQueryPredictions()
را تماس بگیرید. توجه:AutocompleteService
هیچ کنترل رابط کاربری اضافه نمی کند. در عوض، روشهای فوق آرایهای از اشیاء پیشبینی را برمیگردانند. هر شیء پیشبینی حاوی متن پیشبینی، و همچنین اطلاعات مرجع و جزئیات نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر مشاهده کنید.
افزودن ویجت تکمیل خودکار
ویجت Autocomplete
یک فیلد ورودی متن را در صفحه وب شما ایجاد می کند، پیش بینی مکان ها را در لیست انتخاب رابط کاربری ارائه می دهد و جزئیات مکان را در پاسخ به درخواست getPlace()
برمی گرداند. هر ورودی در لیست انتخاب مربوط به یک مکان واحد است (همانطور که توسط Places API تعریف شده است).
سازنده Autocomplete
دو آرگومان می گیرد:
- یک عنصر
input
HTML از نوعtext
. این فیلد ورودی است که سرویس تکمیل خودکار نتایج آن را نظارت کرده و به آن پیوست می کند. - یک آرگومان اختیاری
AutocompleteOptions
که می تواند حاوی ویژگی های زیر باشد:- آرایه ای از
fields
داده که باید در پاسخPlace Details
برایPlaceResult
انتخابی کاربر گنجانده شود. اگر ویژگی تنظیم نشده باشد یا اگر['ALL']
وارد شود، همه فیلدهای موجود برگردانده شده و برای آنها صورتحساب دریافت میشود (این برای استقرار تولید توصیه نمیشود). برای فهرستی از فیلدها،PlaceResult
ببینید. - آرایه ای از
types
که نوع صریح یا مجموعه نوع را مشخص می کند، همانطور که در انواع پشتیبانی شده فهرست شده است. اگر نوع مشخص نشده باشد، همه انواع برگردانده می شوند. -
bounds
یک شیgoogle.maps.LatLngBounds
است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج به سمت مکانهایی که در این محدودهها قرار دارند، تعصب دارند، اما محدود به آنها نیستند. -
strictBounds
یکboolean
است که مشخص میکند آیا API باید فقط مکانهایی را برگرداند که دقیقاً در منطقه تعریفشده باbounds
داده شده هستند یا خیر. API نتایج خارج از این منطقه را حتی اگر با ورودی کاربر مطابقت داشته باشد برنمیگرداند. -
componentRestrictions
می تواند برای محدود کردن نتایج به گروه های خاص استفاده شود. در حال حاضر، میتوانید ازcomponentRestrictions
برای فیلتر کردن حداکثر ۵ کشور استفاده کنید. کشورها باید به عنوان یک کد سازگار با دو شخصیت ، 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()
تماس بگیرید.
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
قسمتهای داده را مشخص کنید
زمینه های داده را مشخص کنید تا از صورتحساب برای مکان های SKU های مورد نیاز خودداری کنید. ویژگی های fields
را در AutocompleteOptions
که به سازنده ویجت منتقل می شوند ، همانطور که در مثال قبلی نشان داده شده است ، یا Call setFields()
روی یک شیء Autocomplete
موجود موجود درج کنید.
autocomplete.setFields(["place_id", "geometry", "name"]);
تعصبات و مرزهای منطقه جستجو را برای اتمام اتو تعریف کنید
شما می توانید نتایج خودکار را به نفع یک مکان یا منطقه تقریبی ، به روش های زیر تعصب کنید:
- مرزها را در ایجاد شیء
Autocomplete
تنظیم کنید. - مرزهای موجود در یک
Autocomplete
موجود را تغییر دهید. - مرزها را روی منظره نقشه تنظیم کنید.
- جستجو را به مرزها محدود کنید.
- جستجو را به یک کشور خاص محدود کنید.
مثال قبلی نشان دهنده تنظیم مرز در ایجاد است. مثالهای زیر تکنیک های تعصب دیگر را نشان می دهد.
مرزهای یک خودکار موجود را تغییر دهید
برای تغییر منطقه جستجو در Autocomplete
موجود در مرزهای مستطیلی موجود setBounds()
تماس بگیرید.
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
مرزها را به نمای نقشه تنظیم کنید
از bindTo()
برای سوگیری نتایج به نمای نقشه استفاده کنید ، حتی در حالی که این دیدگاه تغییر می کند.
autocomplete.bindTo("bounds", map);
autocomplete.bindTo("bounds", map);
برای خنثی کردن پیش بینی های خودکار از نمای نقشه ، از unbind()
استفاده کنید.
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
جستجو را به مرزهای فعلی محدود کنید
گزینه strictBounds
را برای محدود کردن نتایج به مرزهای فعلی ، چه بر اساس نمای نقشه یا مرزهای مستطیل شکل تنظیم کنید.
autocomplete.setOptions({ strictBounds: true });
پیش بینی ها را به یک کشور خاص محدود کنید
برای محدود کردن جستجوی خودکار به مجموعه خاصی از حداکثر پنج کشور ، از گزینه componentRestrictions
یا تماس با setComponentRestrictions()
استفاده کنید.
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
محدود کردن انواع مکان
برای محدود کردن پیش بینی ها به انواع مکان خاص از گزینه types
یا setTypes()
استفاده کنید. این محدودیت یک نوع یا مجموعه نوع را مشخص می کند ، همانطور که در انواع مکان ذکر شده است. اگر هیچ محدودیتی مشخص نشده باشد ، همه نوع بازگردانده می شوند.
برای مقدار گزینه types
یا مقدار منتقل شده به setTypes()
، می توانید یا مشخص کنید:
آرایه ای حاوی پنج مقدار از جدول 1 یا جدول 2 از انواع مکان . به عنوان مثال:
types: ['hospital', 'pharmacy', 'bakery', 'country']
یا:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- هر فیلتر یک در جدول 3 از انواع مکان . فقط می توانید یک مقدار واحد را از جدول 3 مشخص کنید.
درخواست اگر:
- شما بیش از پنج نوع را مشخص می کنید.
- شما انواع ناشناخته را مشخص می کنید.
- شما هر نوع از جدول 1 یا جدول 2 را با هر فیلتر از جدول 3 مخلوط می کنید.
مکان های نسخه ی نمایشی خودکار تفاوت در پیش بینی ها بین انواع مختلف مکان را نشان می دهد.
گرفتن اطلاعات در محل
هنگامی که یک کاربر مکانی را از پیش بینی های متصل به قسمت متن خودکار انتخاب می کند ، این سرویس یک رویداد place_changed
شلیک می کند. برای به دست آوردن جزئیات مکان:
- برای یک رویداد addlistener (
Autocomplete
باaddListener()
در شیءplace_changed
تماس بگیرید تا یک کنترل کننده را اضافه کنید. - برای بازیابی یک شیء
Autocomplete
، که می توانید از آن استفادهPlaceResult
تا اطلاعات بیشتری در مورد مکان انتخاب شده داشته باشید ، باAutocomplete.getPlace()
تماس بگیرید.
به طور پیش فرض ، هنگامی که یک کاربر یک مکان را انتخاب می کند ، Autoclotte تمام قسمت های داده موجود را برای مکان انتخاب شده باز می گرداند و بر این اساس صورتحساب می شود. برای مشخص کردن کدام قسمت از قسمت های داده برای بازگشت ، از Autocomplete.setFields()
استفاده کنید. اطلاعات بیشتر در مورد شیء PlaceResult
، از جمله لیستی از زمینه های داده مکان که می توانید درخواست کنید بخوانید. برای جلوگیری از پرداخت داده هایی که به آن احتیاج ندارید ، حتماً از Autocomplete.setFields()
استفاده کنید تا فقط داده های مکانی را که استفاده می کنید مشخص کنید.
ویژگی name
شامل description
از مکان های پیش بینی های خودکار است. می توانید اطلاعات بیشتر در مورد description
در مکانها مستندات خودکار را بخوانید.
برای فرم های آدرس ، دریافت آدرس در قالب ساختاری مفید است. برای بازگشت آدرس ساختار یافته برای مکان انتخاب شده ، با Autocomplete.setFields()
تماس بگیرید و قسمت address_components
را مشخص کنید.
مثال زیر از AutoClotte برای پر کردن قسمت ها به صورت آدرس استفاده می کند.
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
سفارشی سازی متن نگهدارنده
به طور پیش فرض ، قسمت متن ایجاد شده توسط سرویس AutoClotte حاوی متن استاندارد نگهدارنده است. برای اصلاح متن ، ویژگی placeholder
را بر روی عنصر input
تنظیم کنید:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
توجه: متن پیش فرض مکان یابی به طور خودکار بومی سازی می شود. اگر مقدار مکان نگهدارنده خود را مشخص کرده اید ، باید محلی سازی آن مقدار را در برنامه خود انجام دهید. برای کسب اطلاعات در مورد چگونگی انتخاب Google Maps JavaScript API زبان استفاده شده ، لطفاً مستندات مربوط به محلی سازی را بخوانید.
برای سفارشی کردن ظاهر ویجت ، به یک ظاهر طراحی شده در ابزارک های خودکار و جعبه جستجو مراجعه کنید.
اضافه کردن ویجت جعبه جستجو
SearchBox
به کاربران امکان می دهد یک جستجوی جغرافیایی مبتنی بر متن ، مانند "پیتزا در نیویورک" یا "فروشگاه های کفش در نزدیکی خیابان رابسون" انجام دهند. می توانید SearchBox
را به یک قسمت متن وصل کنید و با وارد کردن متن ، این سرویس پیش بینی ها را به صورت یک لیست انتخاب کشویی باز می گرداند.
SearchBox
فهرست گستردهای از پیشبینیها را ارائه میکند که میتواند شامل مکانها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. به عنوان مثال ، اگر کاربر وارد پیتزا جدید شود ، لیست انتخاب ممکن است عبارت "پیتزا در نیویورک ، نیویورک" و همچنین نام رسانه های مختلف پیتزا را شامل شود. هنگامی که یک کاربر مکانی را از لیست انتخاب می کند ، اطلاعات مربوط به آن مکان به شیء جعبه جستجو بازگردانده می شود و توسط برنامه شما قابل بازیابی است.
سازنده SearchBox
دو استدلال می کند:
- یک عنصر
input
HTML ازtext
. این قسمت ورودی است که سرویسSearchBox
نتایج آن را کنترل کرده و به آن وصل می کند. - یک آرگومان
options
، که می تواند حاوی خاصیتbounds
باشد:bounds
یک شیءgoogle.maps.LatLngBounds
است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج نسبت به مکانهای موجود در این مرزها مغرضانه ، اما محدود نمی شوند.
کد زیر از پارامتر مرزها برای سوگیری نتایج به سمت مکانها در یک منطقه جغرافیایی خاص ، که از طریق مختصات Laitude/طول جغرافیایی مشخص شده است ، استفاده می کند.
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
تغییر منطقه جستجو برای جعبه جستجو
برای تغییر منطقه جستجو برای یک SearchBox
موجود ، با setBounds()
در شیء SearchBox
تماس بگیرید و از شیء مربوط به LatLngBounds
عبور کنید.
گرفتن اطلاعات در محل
هنگامی که کاربر یک مورد را از پیش بینی های متصل به کادر جستجو انتخاب می کند ، این سرویس یک رویداد places_changed
را آتش می زند. برای SearchBox
آرایه ای که حاوی چندین پیش بینی PlaceResult
، می توانید با getPlaces()
تماس بگیرید.
برای کسب اطلاعات بیشتر در مورد شیء PlaceResult
، به اسناد مربوط به نتایج جزئیات مکان مراجعه کنید.
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
برای سفارشی کردن ظاهر ویجت ، به یک ظاهر طراحی شده در ابزارک های خودکار و جعبه جستجو مراجعه کنید.
بازیابی برنامه ای پیش بینی های سرویس دهی خودکار
برای بازیابی پیش بینی ها به صورت برنامه ای ، از کلاس AutocompleteService
استفاده کنید. AutocompleteService
هیچ کنترل رابط کاربری اضافه نمی کند. در عوض ، مجموعه ای از اشیاء پیش بینی را برمی گرداند ، هر یک حاوی متن پیش بینی ، اطلاعات مرجع و جزئیات مربوط به چگونگی نتیجه با ورودی کاربر است. این امر مفید است اگر می خواهید کنترل بیشتری بر رابط کاربری داشته باشید از آنچه توسط جعبه Autocomplete
و SearchBox
توضیح داده شده است.
AutocompleteService
روشهای زیر را در معرض دید قرار می دهد:
-
getPlacePredictions()
پیش بینی های مکان را برمی گرداند. توجه: "مکان" می تواند یک مکان ، موقعیت جغرافیایی یا نکته برجسته مورد علاقه باشد ، همانطور که توسط مکان های API تعریف شده است. -
getQueryPredictions()
لیست گسترده ای از پیش بینی ها را برمی گرداند ، که می تواند شامل مکانهایی (مطابق با مکان های API) به علاوه اصطلاحات جستجوی پیشنهادی باشد. به عنوان مثال ، اگر کاربر وارد پیتزا جدید شود ، لیست انتخاب ممکن است عبارت "پیتزا در نیویورک ، نیویورک" و همچنین نام رسانه های مختلف پیتزا را شامل شود.
هر دو روش فوق مجموعه ای از اشیاء پیش بینی شکل زیر را برمی گردانند:
-
description
پیش بینی همسان است. -
distance_meters
فاصله در متر مکان ازAutocompletionRequest.origin
مشخص شده است. -
matched_substrings
شامل مجموعه ای از بستر ها در توضیحات است که عناصر در ورودی کاربر را مطابقت می دهد. این برای برجسته کردن آن بستر های موجود در برنامه شما مفید است. در بسیاری از موارد ، پرس و جو به عنوان بستری از قسمت توضیحات ظاهر می شود.-
length
طول بستر است. -
offset
جبران شخصیت است که از ابتدای رشته توضیحات اندازه گیری می شود ، که در آن زیر لایه همسان ظاهر می شود.
-
-
place_id
یک شناسه متنی است که به طور منحصر به فرد یک مکان را مشخص می کند. برای بازیابی اطلاعات در مورد مکان ، این شناسه را در قسمتplaceId
یک درخواست جزئیات مکان منتقل کنید. در مورد نحوه مراجعه به مکانی با شناسه مکان بیشتر بدانید. -
terms
آرایه ای است که حاوی عناصر پرس و جو است. برای یک مکان ، هر عنصر به طور معمول بخشی از آدرس را تشکیل می دهد.-
offset
جبران شخصیت است که از ابتدای رشته توضیحات اندازه گیری می شود ، که در آن زیر لایه همسان ظاهر می شود. -
value
اصطلاح تطبیق است.
-
مثال زیر درخواست پیش بینی پرس و جو برای عبارت "پیتزا نزدیک" را اجرا می کند و نتیجه را در یک لیست نشان می دهد.
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
<html> <head> <title>Retrieving Autocomplete Predictions</title> <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>
Sample را امتحان کنید
نشانه های جلسه
AutocompleteService.getPlacePredictions()
می تواند از نشانه های جلسه (در صورت اجرای) استفاده کند تا درخواست های خودکار را برای اهداف صورتحساب گروه بندی کند. نشانههای جلسه، مراحل پرس و جو و انتخاب یک جستجوی تکمیل خودکار کاربر را در یک جلسه مجزا برای اهداف صورتحساب گروهبندی میکنند. جلسه زمانی شروع می شود که کاربر شروع به تایپ یک پرس و جو می کند، و با انتخاب مکان به پایان می رسد. هر جلسه می تواند چندین پرس و جو داشته باشد و به دنبال آن یک مکان انتخاب شود. پس از پایان جلسه ، این نشانه دیگر معتبر نیست. برنامه شما باید برای هر جلسه یک نشانه تازه ایجاد کند. توصیه می کنیم برای همه جلسات خودکار از نشانه های جلسه استفاده کنید. اگر پارامتر sessionToken
حذف شود ، یا اگر از یک جلسه جلسه استفاده مجدد می کنید ، جلسه به نظر می رسد که هیچ نشانه ای از جلسه ارائه نشده است (هر درخواست به طور جداگانه صورتحساب می شود).
شما می توانید از همان Token Session استفاده کنید تا یک درخواست جزئیات یک مکان را در مکانی که از تماس با AutocompleteService.getPlacePredictions()
حاصل می شود ، استفاده کنید. در این حالت ، درخواست خودکار با درخواست جزئیات مکان ترکیب می شود و تماس به عنوان یک درخواست جزئیات مکان معمولی شارژ می شود. هیچ هزینه ای برای درخواست خودکار وجود ندارد.
حتماً برای هر جلسه جدید یک نشانه جلسه منحصر به فرد را پشت سر بگذارید. استفاده از همان نشانه برای بیش از یک جلسه خودکار ، آن جلسات ناقص را باطل می کند و کلیه درخواست های خودکار در جلسات نامعتبر به صورت جداگانه با استفاده از خودکار در هر درخواست SKU شارژ می شود. اطلاعات بیشتر در مورد نشانه های جلسه را بخوانید .
مثال زیر نشان می دهد که یک نشانه جلسه ایجاد می کند ، سپس عبور از آن در یک AutocompleteService
(عملکرد displaySuggestions()
برای کوتاه بودن حذف شده است):
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
حتماً برای هر جلسه جدید یک نشانه جلسه منحصر به فرد را پشت سر بگذارید. استفاده از همان نشانه برای بیش از یک جلسه باعث می شود که هر درخواست به صورت جداگانه صورتحساب شود.
اطلاعات بیشتر در مورد نشانه های جلسه را بخوانید .
طراحی ابزارک های خودکار و جعبه جستجو
به طور پیش فرض ، عناصر UI ارائه شده توسط Autocomplete
و SearchBox
برای گنجاندن در نقشه Google طراحی شده اند. ممکن است بخواهید یک ظاهر طراحی شده را متناسب با سایت خود تنظیم کنید. کلاس های CSS زیر در دسترس است. کلیه کلاسهای ذکر شده در زیر برای هر دو ابزارک Autocomplete
و SearchBox
اعمال می شود.
کلاس 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 AUTOCPLOTE API MAPS ، SDK را برای ویجت خودکار Android قرار می دهد ، یا SDK را برای کنترل UI AUTOCPLETE IOS قرار می دهد
- از ابتدا درک از زمینه های داده خودکار مکان ضروری را ایجاد کنید.
- فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
- از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمیگرداند، برنامه شما به خوبی کاهش مییابد.
- اطمینان حاصل کنید که برنامه شما در صورت عدم انتخاب ، کنترل می کند و راهی برای ادامه کار به کاربران ارائه می دهد.
بهینه سازی هزینه بهترین روشها
بهینه سازی هزینه اساسی
برای بهینهسازی هزینه استفاده از سرویس تکمیل خودکار مکان، از ماسکهای فیلد در ویجتهای Place Details و Place Autocomplete استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.
بهینه سازی هزینه پیشرفته
به منظور دسترسی به قیمت گذاری در هر درخواست ، اجرای برنامه نویسی مکان را به صورت خودکار در نظر بگیرید و به جای جزئیات مکان ، نتایج API GeoCoding را در مورد مکان انتخاب شده درخواست کنید. قیمت گذاری هر درخواست جفت شده با Geocoding API مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) است اگر هر دو شرایط زیر رعایت شود:
- اگر فقط به طول/طول جغرافیایی یا آدرس مکان انتخابی کاربر نیاز دارید، API Geocoding این اطلاعات را کمتر از یک تماس با جزئیات مکان ارائه میکند.
- اگر کاربران یک پیشبینی تکمیل خودکار را در چهار درخواست پیشبینی تکمیل خودکار یا کمتر انتخاب کنند، ممکن است قیمتگذاری به ازای هر درخواست مقرونبهصرفهتر از قیمتگذاری در هر جلسه باشد.
آیا برنامه شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیش بینی انتخاب شده نیاز دارد؟
از مکان مبتنی بر جلسه به صورت خودکار با جزئیات مکان استفاده کنید.
از آنجایی که برنامه شما به جزئیات مکان مانند نام مکان، وضعیت کسب و کار، یا ساعات کاری نیاز دارد، پیاده سازی تکمیل خودکار مکان شما باید از یک نشانه جلسه ( به صورت برنامه نویسی یا تعبیه شده در ویجت های جاوا اسکریپت ، اندروید ، یا iOS ) با هزینه کل 0.017 دلار برای هر استفاده کند. بسته به فیلدهای داده مکانی که درخواست می کنید، session plus SKU های داده مکان های قابل اجرا. 1
اجرای ویجت
مدیریت جلسه به طور خودکار در ابزارک های JavaScript ، Android یا iOS ساخته می شود. این شامل هر دو درخواست AUTOCPLOCTETE PLACE و درخواست جزئیات مکان در پیش بینی انتخاب شده است. برای اطمینان از اینکه فقط از قسمت های داده های مورد نیاز خود درخواست می کنید ، حتماً پارامتر fields
را مشخص کنید.
اجرای برنامه ای
با درخواست های خودکار مکان خود از یک نشانه جلسه استفاده کنید. هنگام درخواست جزئیات مکان در مورد پیش بینی انتخاب شده ، پارامترهای زیر را درج کنید:
- شناسه مکان از پاسخ تکمیل خودکار مکان
- توکن جلسه مورد استفاده در درخواست خودکار در محل
- پارامتر
fields
فیلدهای داده مکان مورد نیاز را مشخص می کند
بسته به عملکرد استفاده از تکمیل خودکار مکان، API جغرافیایی میتواند گزینه مقرونبهصرفهتری نسبت به جزئیات مکان برای برنامه شما باشد. بازده تکمیل خودکار هر برنامه بسته به اینکه چه کاربرانی وارد میشوند، جایی که برنامه در حال استفاده است، و اینکه آیا بهترین شیوههای بهینهسازی عملکرد اجرا شدهاند، متفاوت است.
برای پاسخ به سؤال زیر، قبل از انتخاب پیشبینی تکمیل خودکار مکان در برنامه، تحلیل کنید که کاربر به طور میانگین چند کاراکتر تایپ میکند.
آیا کاربران شما به طور متوسط یک پیش بینی خودکار را در چهار یا کمتر درخواست انتخاب می کنند؟
پیاده سازی خودکار را به صورت برنامه ای به صورت برنامه ای و بدون نشانه های جلسه اجرا کنید و با API GeoCoding در پیش بینی مکان انتخاب شده تماس بگیرید.
Geocoding API آدرس ها و مختصات طول و عرض جغرافیایی را برای هر درخواست 0.005 دلار ارائه می دهد. ساخت چهار مکان به صورت خودکار - درخواست درخواست در هر درخواست 0.01132 دلار هزینه دارد ، بنابراین کل هزینه چهار درخواست به علاوه یک تماس GeoCoding API در مورد پیش بینی مکان انتخاب شده 0.01632 دلار خواهد بود که کمتر از قیمت خودکار در هر جلسه 0.017 دلار در هر جلسه است. 1
در نظر بگیرید که از بهترین شیوه های عملکرد استفاده کنید تا کاربران خود پیش بینی خود را که حتی در شخصیت های کمتری به دنبال آن هستند ، در نظر بگیرند.
از مکان مبتنی بر جلسه به صورت خودکار با جزئیات مکان استفاده کنید.
از آنجا که میانگین تعداد درخواستهایی که انتظار دارید قبل از انتخاب یک مکان پیش بینی خودکار ، از هزینه قیمت گذاری در هر جلسه فراتر رود ، اجرای برنامه شما باید از یک نشانه جلسه برای هر دو درخواست های خودکار و در مورد مکان مرتبط استفاده کند. هزینه کل 0.017 دلار در هر جلسه . 1
اجرای ویجت
مدیریت جلسه به طور خودکار در ابزارک های JavaScript ، Android یا iOS ساخته می شود. این شامل هر دو درخواست AUTOCPLOCTETE PLACE و درخواست جزئیات مکان در پیش بینی انتخاب شده است. حتماً پارامتر fields
را مشخص کنید تا مطمئن شوید که فقط فیلدهای Basic Data را درخواست می کنید.
اجرای برنامه ای
با درخواست های خودکار مکان خود از یک نشانه جلسه استفاده کنید. هنگام درخواست جزئیات مکان در مورد پیش بینی انتخاب شده ، پارامترهای زیر را درج کنید:
- شناسه مکان از پاسخ تکمیل خودکار مکان
- توکن جلسه مورد استفاده در درخواست خودکار در محل
- پارامتر
fields
فیلدهای داده های پایه مانند آدرس و هندسه را مشخص می کند
درخواستهای تکمیل خودکار مکان را به تأخیر بیندازید
شما می توانید از استراتژی هایی مانند تأخیر در درخواست خودکار در مکان استفاده کنید تا اینکه کاربر در سه یا چهار کاراکتر اول تایپ کند تا درخواست شما درخواست های کمتری داشته باشد. برای مثال، ایجاد درخواستهای تکمیل خودکار مکان برای هر کاراکتر پس از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه را تایپ کند و سپس پیشبینیای را انتخاب کند که برای آن یک درخواست API Geocoding انجام دهید، کل هزینه 0.01632 دلار (4 * 0.00283 خودکار تکمیل خودکار) خواهد بود. در هر درخواست + 0.005 $ geoCoding). 1
اگر درخواستهای با تأخیر میتوانند میانگین درخواست برنامهای شما را به زیر چهار برسانند، میتوانید از راهنماییهای مربوط به تکمیل خودکار مکان با اجرای API Geocoding پیروی کنید. توجه داشته باشید که درخواستهای تأخیر را میتوان بهعنوان تأخیر برای کاربری که ممکن است انتظار داشته باشد با هر ضربه کلید جدید، پیشبینیهایی را ببیند، درک شود.
بهترین روشهای عملکرد را برای کمک به کاربران خود در نظر بگیرید تا پیشبینی مورد نظر خود را با نویسههای کمتری دریافت کنند.
هزینه های ذکر شده در اینجا به دلار است. لطفاً برای اطلاعات کامل قیمت گذاری به صفحه صورتحساب پلت فرم Google Maps مراجعه کنید.
بهترین شیوه های عملکرد
دستورالعمل های زیر روشهای بهینه سازی عملکرد خودکار را شرح می دهد:
- محدودیتهای کشور، سوگیری موقعیت و اولویت زبان (برای اجرای برنامهای) را به پیادهسازی تکمیل خودکار مکان خود اضافه کنید. اولویت زبان با ویجت ها مورد نیاز نیست زیرا آنها ترجیحات زبان را از مرورگر کاربر یا دستگاه تلفن همراه انتخاب می کنند.
- اگر Place AutoClotte با یک نقشه همراه باشد ، می توانید مکان تعصب را با نمای نقشه تعصب کنید.
- در مواقعی که کاربر یکی از پیش بینی های خودکار را انتخاب نمی کند ، به طور کلی به دلیل اینکه هیچ یک از این پیش بینی ها آدرس مطلوب نیست ، می توانید از ورودی اصلی کاربر استفاده کنید تا سعی در دستیابی به نتایج مرتبط تر داشته باشید:
- اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند ، از ورودی اصلی کاربر در تماس با API GeoCoding استفاده مجدد کنید.
- اگر از کاربر انتظار دارید که پرس و جوهایی را برای مکان خاصی با نام یا آدرس وارد کند، از درخواست Find Place استفاده کنید. اگر نتایج فقط در یک منطقه خاص انتظار می رود ، از تعصب مکان استفاده کنید.
- کاربرانی که آدرس های فرعی را وارد می کنند ، مانند آدرس برای واحدهای خاص یا آپارتمان ها در یک ساختمان. به عنوان مثال ، آدرس چک "Stroupežnického 3191/17 ، Praha" پیش بینی جزئی در محل را به صورت خودکار انجام می دهد.
- کاربرانی که آدرسهایی را با پیشوندهای بخش جاده مانند «23-30 29th, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره Kauai در هاوایی وارد میکنند.
محدودیت ها و سیاست های استفاده
سهمیه ها
برای سهمیه و اطلاعات مربوط به قیمت گذاری ، به اسناد و مدارک استفاده و صورتحساب برای API مکان ها مراجعه کنید.
سیاست ها
استفاده از کتابخانه مکان ها ، نقشه های API JavaScript باید مطابق با سیاست های شرح داده شده برای API مکان ها باشد.