Places UI Kit : یک کتابخانه آماده برای استفاده که فضایی را برای سفارشی‌سازی و توسعه کم کد فراهم می‌کند. آن را امتحان کنید و نظرات خود را در مورد تجربه کیت UI خود به اشتراک بگذارید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

تکمیل خودکار جا (قدیمی)

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

توجه: کتابخانه‌های سمت سرور

این صفحه کتابخانه سمت کارخواه را که با Maps JavaScript API دردسترس است شرح می‌دهد. اگر می‌خواهید با سرویس وب Places API در سرورتان کار کنید، به Node.js Client for Google Maps Services نگاهی بیندازید. صفحه موجود در آن پیوند همچنین Java Client،‏ Python Client، و Go Client را برای «سرویس‌های Google Maps» معرفی می‌کند.

مقدمه

«تکمیل خودکار» یکی‌از ویژگی‌های کتابخانه «جاها» در Maps JavaScript API است. می‌توانید از تکمیل خودکار استفاده کنید تا به برنامه‌هایتان رفتار جستجوی پیش‌تایپ فیلد جستجوی Google Maps را بدهید. سرویس تکمیل خودکار می‌تواند با کلمات کامل و رشته‌های فرعی مطابقت داشته باشد و نام مکان‌ها، نشانی‌ها، و کدهای Plus را حل کند. بنابراین، برنامه‌ها می‌توانند هم‌زمان با تایپ کردن کاربر پُرسمان ارسال کنند تا پیش‌بینی‌های مکان را درلحظه ارائه دهند. همان‌طور که Places API تعریف کرده است، «مکان» می‌تواند یک مؤسسه، مکان جغرافیایی، یا نقطه موردعلاقه برجسته باشد.

درحال شروع کردن

قبل‌از استفاده از کتابخانه «جاها» در Maps JavaScript API، ابتدا بررسی کنید که Places API در کنسول Google Cloud، در همان پروژه‌ای که برای Maps JavaScript API راه‌اندازی کرده‌اید، فعال باشد.

برای مشاهده فهرست میاناهای برنامه‌سازی کاربردی فعال‌شده:

به کنسول Google Cloud بروید.
روی دکمه انتخاب پروژه کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API راه‌اندازی کرده‌اید انتخاب کنید و روی باز کردن کلیک کنید.
از فهرست میاناهای برنامه‌سازی کاربردی در داشبورد، Places API را پیدا کنید.
اگر API را در فهرست می‌بینید، همه تنظیمات انجام شده است. اما این پروژه در وضعیت «قدیمی» است. برای اطلاعات بیشتر درباره مرحله «قدیمی» و نحوه انتقال از «قدیمی» به سرویس‌های جدیدتر، محصولات و ویژگی‌های قدیمی را ببینید. یک استثنا برای ابزاره‌های تکمیل خودکار و SearchBox وجود دارد که هنوز به‌عنوان محصول GA در Places API (جدید) دردسترس نیستند.

بار کردن کتابخانه

سرویس «مکان‌ها» کتابخانه‌ای مستقل است که از کد اصلی Maps JavaScript API جدا است. برای استفاده از ویژگی‌های موجود در این کتابخانه، ابتدا باید آن را بااستفاده از پارامتر libraries در نشانی وب راه‌انداز Maps API بار کنید:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

برای اطلاعات بیشتر، به نمای کلی کتابخانه‌ها مراجعه کنید.

خلاصه کلاس‌ها

این میانای برنامه‌سازی کاربردی دو نوع ابزاره تکمیل خودکار ارائه می‌دهد که می‌توانید آن‌ها را به‌ترتیب بااستفاده از کلاس‌های Autocomplete و SearchBox اضافه کنید. علاوه‌براین، می‌توانید از کلاس AutocompleteService برای بازیابی نتایج تکمیل خودکار به‌صورت برنامه‌نویسی‌شده استفاده کنید (به مرجع Maps JavaScript API مراجعه کنید: کلاس AutocompleteService).

در زیر خلاصه‌ای از کلاس‌های دردسترس آمده است:

Autocomplete فیلد ورودی نوشتاری به صفحه وب شما اضافه می‌کند، و آن فیلد را برای ورودی‌های نویسه نظارت می‌کند. وقتی کاربر نوشتار وارد می‌کند، تکمیل خودکار پیش‌بینی‌های مکان را به‌صورت فهرست کرکره‌ای برمی‌گرداند. وقتی کاربر مکانی را از فهرست انتخاب می‌کند، اطلاعات مربوط به آن مکان به شیء تکمیل خودکار برگردانده می‌شود و می‌تواند توسط برنامه شما بازیابی شود. جزئیات را در زیر ببینید.

شکل ۱: فیلد نوشتار تکمیل خودکار و فهرست انتخاب

شکل ۲: فرم نشانی تکمیل‌شده
SearchBox فیلد ورودی نوشتار را به صفحه وب شما اضافه می‌کند، تقریباً به همان روش Autocomplete. تفاوت‌ها به شرح زیر است:
- تفاوت اصلی در نتایجی است که در فهرست انتخاب ظاهر می‌شود. SearchBox فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌دهد که می‌تواند شامل مکان‌ها (همان‌طور که توسط Places API تعریف شده است) به‌علاوه عبارت‌های جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در نیو» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام‌های پیتزافروشی‌های مختلف باشد.
- SearchBox گزینه‌های کمتری نسبت به Autocomplete برای محدود کردن جستجو ارائه می‌دهد. در حالت اول، می‌توانید جستجو را به‌سمت LatLngBounds خاصی متمایل کنید. در مورد دوم، می‌توانید جستجو را به کشور خاص و انواع مکان‌های خاص محدود کنید، و همچنین مرزها را تنظیم کنید. برای اطلاعات بیشتر، زیر را ببینید.
شکل ۳: SearchBox عبارت‌های جستجو و پیش‌بینی‌های مکان را ارائه می‌دهد.

جزئیات را در زیر ببینید.
می‌توانید شیء AutocompleteService ایجاد کنید تا پیش‌بینی‌ها را به‌صورت برنامه‌نویسی‌شده بازیابی کنید. برای بازیابی مکان‌های منطبق، با getPlacePredictions() تماس بگیرید، یا برای بازیابی مکان‌های منطبق به‌علاوه عبارت‌های جستجوی پیشنهادی، با getQueryPredictions() تماس بگیرید. توجه: AutocompleteService هیچ کنترل میانای کاربری اضافه نمی‌کند. درعوض، روش‌های بالا آرایه‌ای از اشیای پیش‌بینی را برمی‌گردانند. هر شیء پیش‌بینی حاوی نوشتار پیش‌بینی و همچنین اطلاعات مرجع و جزئیات نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر ببینید.

افزودن ابزاره «تکمیل خودکار»

ابزاره Autocomplete یک فیلد ورودی نوشتار در صفحه وب شما ایجاد می‌کند، پیش‌بینی‌های مکان‌ها را در فهرست انتخاب واسط کاربر ارائه می‌دهد، و جزئیات مکان را در پاسخ به درخواست getPlace() برمی‌گرداند. هر ورودی در فهرست انتخاب با یک مکان (همان‌طور که توسط Places API تعریف شده است) مطابقت دارد.

سازنده Autocomplete دو آرگومان می‌گیرد:

عنصر HTML input از نوع text. این فیلد ورودی است که سرویس تکمیل خودکار آن را نظارت می‌کند و نتایجش را به آن پیوست می‌کند.
یک متغیر مستقل اختیاری AutocompleteOptions که می‌تواند حاوی ویژگی‌های زیر باشد:
- آرایه‌ای از داده‌های fields که باید در پاسخ Place Details برای PlaceResult انتخاب‌شده کاربر گنجانده شود. اگر ویژگی تنظیم نشده باشد یا اگر ['ALL'] ارسال شود، همه فیلدهای دردسترس برگردانده می‌شوند و صورت‌حساب برای آن‌ها صادر می‌شود (این کار برای استقرار تولید توصیه نمی‌شود). برای مشاهده فهرست فیلدها، PlaceResult را ببینید.
- آرایه‌ای از types که نوع صریح یا مجموعه نوع را مشخص می‌کند، همان‌طور که در انواع پشتیبانی‌شده فهرست شده است. اگر نوعی مشخص نشده باشد، همه انواع برگردانده می‌شوند.
- bounds یک شیء google.maps.LatLngBounds است که منطقه جستجوی مکان‌ها را مشخص می‌کند. نتایج به مکان‌های موجود در این مرزها متمایل است، اما به آن‌ها محدود نمی‌شود.
- strictBounds یک boolean است که مشخص می‌کند آیا API باید فقط مکان‌هایی را برگرداند که دقیقاً در منطقه تعریف‌شده توسط bounds داده‌شده قرار دارند یا نه. میانای برنامه‌سازی کاربردی نتایج خارج از این منطقه را برنمی‌گرداند، حتی اگر با ورودی کاربر مطابقت داشته باشند.
  توجه: محدودیت مکان فقط برای کل مسیرها اعمال می‌شود، نتایج مصنوعی واقع در خارج از محدودیت مکان ممکن است براساس مسیری که با محدودیت مکان هم‌پوشانی دارد برگردانده شود.
- از componentRestrictions می‌توان برای محدود کردن نتایج به گروه‌های خاص استفاده کرد. می‌توانید از componentRestrictions برای فیلتر کردن براساس حداکثر ۵ کشور استفاده کنید. کشورها باید به‌صورت کد کشور دوحرفی سازگار با ISO 3166-1 Alpha-2 ارسال شوند. چند کشور باید به‌صورت فهرستی از کدهای کشور ارسال شوند.
  توجه: اگر نتایج غیرمنتظره‌ای با کد کشور دریافت کردید، بررسی کنید که از کدی استفاده می‌کنید که شامل کشورها، قلمروهای وابسته، و مناطق ویژه جغرافیایی موردنظر شما باشد. می‌توانید اطلاعات کد را در ویکی‌پدیا: فهرست کدهای کشور ISO 3166 یا پلاتفرم مرور آنلاین ISO پیدا کنید.
- از placeIdOnly می‌توان برای دستور دادن به ابزارک Autocomplete برای بازیابی فقط «شناسه‌های مکان» استفاده کرد. هنگام فراخوانی getPlace() در شیء Autocomplete، PlaceResult دردسترس قرارگرفته فقط ویژگی‌های place id، types، و name را تنظیم خواهد کرد. می‌توانید از شناسه مکان برگردانده‌شده برای تماس با سرویس‌های «مکان‌ها»، «زمین‌کدیابی»، «مسیرها»، یا «ماتریس فاصله» استفاده کنید.
  توجه: ویژگی name حاوی description از پیش‌بینی‌های «تکمیل خودکار مکان‌ها» خواهد بود. می‌توانید درباره description در AutocompleteService اسناد بیشتر بخوانید.
  
  توجه: placeIdOnly از ۱۵ ژانویه ۲۰۱۹ منسوخ شده است و در ۱۵ ژانویه ۲۰۲۰ خاموش خواهد شد. درعوض از آرایه fields در میانای AutocompleteOptions استفاده کنید: fields: ['place_id', 'name', 'types'].

محدود کردن پیش‌بینی‌های «تکمیل خودکار»

به‌طور پیش‌فرض، «تکمیل خودکار جا» همه انواع مکان را ارائه می‌دهد، برای پیش‌بینی‌های نزدیک به مکان کاربر سوگیری دارد، و همه فیلدهای داده دردسترس را برای مکان انتخابی کاربر واکشی می‌کند. گزینه‌های «تکمیل خودکار جا» را تنظیم کنید تا پیش‌بینی‌های مرتبط‌تری براساس مورد استفاده شما ارائه شود.

تنظیم گزینه‌ها در ساختار

سازنده Autocomplete پارامتر AutocompleteOptions را برای تنظیم محدودیت‌ها در زمان ایجاد ابزاره می‌پذیرد. مثال زیر گزینه‌های bounds،‏ componentRestrictions، و types را برای درخواست مکان‌های نوع establishment تنظیم می‌کند، مکان‌های داخل منطقه جغرافیایی مشخص‌شده را ترجیح می‌دهد، و پیش‌بینی‌ها را فقط به مکان‌های داخل ایالات متحده محدود می‌کند. تنظیم گزینه fields مشخص می‌کند چه اطلاعاتی درباره مکان انتخابی کاربر برگردانده شود.

برای تغییر دادن مقدار گزینه برای ابزاره موجود، setOptions() را فراخوانی کنید.

TypeScript

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);index.ts

JavaScript

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);
index.js

مشخص کردن فیلدهای داده

فیلدهای داده را مشخص کنید تا برای شناسه‌های یکتای کالا در «داده‌های مکان‌ها» که نیاز ندارید صورت‌حساب دریافت نکنید. ویژگی fields را در AutocompleteOptions که به سازنده ابزاره ارسال می‌شود اضافه کنید، همان‌طور که در مثال قبلی نشان داده شده است، یا setFields() را در شیء Autocomplete موجود فراخوانی کنید.

autocomplete.setFields(["place_id", "geometry", "name"]);

تعریف سوگیری‌ها و مرزهای ناحیه جستجو برای تکمیل خودکار

می‌توانید نتایج تکمیل خودکار را به‌روش‌های زیر به‌سمت مکان یا منطقه تقریبی متمایل کنید:

محدودیت‌های ایجاد شیء Autocomplete را تنظیم کنید.
تغییر مرزهای Autocomplete موجود.
مرزها را روی ناحیه نمایش نقشه تنظیم کنید.
جستجو را به مرزها محدود می‌کند.
جستجو را به کشوری خاص محدود می‌کند.

مثال قبلی تنظیم مرزها را هنگام ایجاد نشان می‌دهد. مثال‌های زیر دیگر روش‌های سوگیری را نشان می‌دهد.

توجه: اگر هیچ محدوده یا نمای نقشه ارائه نکنید، API تلاش می‌کند مکان کاربر را از نشانی IP او تشخیص دهد و نتایج را براساس آن مکان سوگیری کند. هرزمان ممکن بود، مرز تنظیم کنید. درغیراین‌صورت، کاربران مختلف ممکن است پیش‌بینی‌های متفاوتی دریافت کنند. همچنین، برای بهبود کلی پیش‌بینی‌ها، مهم است که نمای معقولی ارائه دهید، مانند نمایی که با جابه‌جایی یا بزرگ‌نمایی روی نقشه تنظیم می‌کنید، یا نمایی که توسعه‌دهنده براساس مکان و شعاع دستگاه تنظیم کرده است. وقتی شعاع دردسترس نباشد، ۵ کیلومتر به‌عنوان پیش‌فرض منطقی برای «تکمیل خودکار جا» درنظر گرفته می‌شود. نمای هدف را با شعاع صفر (یک نقطه)، نمای هدفی که فقط چند متر عرض دارد (کمتر از ۱۰۰ متر)، یا نمای هدفی که کل جهان را دربرمی‌گیرد تنظیم نکنید.

تغییر مرزهای «تکمیل خودکار» موجود

برای تغییر دادن منطقه جستجو در Autocomplete موجود به مرزهای مستطیلی، setBounds() را فراخوانی کنید.

TypeScript

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);index.ts

JavaScript

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);
index.js

تنظیم کردن مرزها برای ناحیه نمایش نقشه

از bindTo() برای سوگیری نتایج به نمای نقشه استفاده کنید، حتی زمانی که آن نما تغییر می‌کند.

TypeScript

autocomplete.bindTo("bounds", map);index.ts

JavaScript

autocomplete.bindTo("bounds", map);
index.js

از unbind() برای لغو اتصال پیش‌بینی‌های «تکمیل خودکار» از نمای نقشه استفاده کنید.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });index.ts

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });index.js

مشاهده نمونه

محدود کردن جستجو به مرزهای فعلی

گزینه strictBounds را تنظیم کنید تا نتایج را به مرزهای فعلی محدود کنید، چه براساس ناحیه نمایش نقشه باشد یا مرزهای مستطیلی.

autocomplete.setOptions({ strictBounds: true });

محدود کردن پیش‌بینی‌ها به کشوری خاص

از گزینه componentRestrictions استفاده کنید یا با setComponentRestrictions() تماس بگیرید تا جستجوی تکمیل خودکار را به مجموعه خاصی از حداکثر پنج کشور محدود کنید.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});index.ts

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

مشاهده نمونه

محدود کردن انواع مکان

از گزینه types استفاده کنید یا setTypes() را فراخوانی کنید تا پیش‌بینی‌ها را به انواع مکان‌های خاص محدود کنید. این محدودیت نوع یا مجموعه‌ای از انواع را مشخص می‌کند، همان‌طور که در انواع مکان فهرست شده است. اگر محدودیتی مشخص نشده باشد، همه انواع برگردانده می‌شوند.

برای مقدار گزینه types یا مقدار ارسال‌شده به setTypes()، می‌توانید یکی از موارد زیر را مشخص کنید:

آرایه‌ای حاوی حداکثر پنج مقدار از جدول ۱ یا جدول ۲ از انواع مکان. برای مثال:
```
types: ['hospital', 'pharmacy', 'bakery', 'country']
```
یا:
```
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
```
هر فیلتری در جدول ۳ از انواع مکان. فقط می‌توانید یک مقدار از جدول ۳ مشخص کنید.

درخواست در شرایط زیر رد خواهد شد:

بیش‌از پنج نوع مشخص کنید.
هر نوع ناشناخته‌ای را مشخص کنید.
هر نوعی از جدول ۱ یا جدول ۲ را با هر فیلتری از جدول ۳ ترکیب کنید.

نسخه نمایشی «تکمیل خودکار جاها» تفاوت‌های پیش‌بینی‌ها را بین انواع مختلف جا نشان می‌دهد.

بازدید از نسخه نمایشی

درحال دریافت اطلاعات مکان

وقتی کاربر مکانی را از پیش‌بینی‌های پیوست‌شده به فیلد نوشتاری تکمیل خودکار انتخاب می‌کند، سرویس رویداد place_changed را فعال می‌کند. برای دریافت جزئیات مکان:

یک گرداننده رویداد برای رویداد place_changed ایجاد کنید و addListener() را در شیء Autocomplete فراخوانی کنید تا گرداننده اضافه شود.
Autocomplete.getPlace() را در شیء Autocomplete فراخوانی کنید تا شیء PlaceResult را بازیابی کنید، سپس می‌توانید از آن برای دریافت اطلاعات بیشتر درباره مکان انتخاب‌شده استفاده کنید.

به‌طور پیش‌فرض، وقتی کاربر مکانی را انتخاب می‌کند، تکمیل خودکار همه فیلدهای داده دردسترس را برای مکان انتخاب‌شده برمی‌گرداند و صورت‌حساب شما براساس آن صادر می‌شود. از Autocomplete.setFields() برای مشخص کردن فیلدهای داده مکان برای برگرداندن استفاده کنید. درباره شیء PlaceResult، ازجمله فهرست فیلدهای داده مکان که می‌توانید درخواست کنید، بیشتر بخوانید. برای اینکه هزینه داده‌هایی را که نیاز ندارید پرداخت نکنید، حتماً از Autocomplete.setFields() برای مشخص کردن فقط داده‌های مکانی که استفاده خواهید کرد استفاده کنید.

مهم: استفاده از تکمیل خودکار برای بازآوری «شناسه‌های مکان» توصیه نمی‌شود، زیرا هر جلسه مشمول هزینه خواهد بود. درعوض، getDetails() را فراخوانی کنید و فقط فیلد place_id را مشخص کنید.

خصوصیت name حاوی description از پیش‌بینی‌های «تکمیل خودکار مکان‌ها» است. می‌توانید درباره description در سند تکمیل خودکار جاها بیشتر بخوانید.

برای فرم‌های نشانی، دریافت نشانی در قالب ساختاریافته مفید است. برای برگرداندن نشانی ساختاریافته برای مکان انتخاب‌شده، Autocomplete.setFields() را فراخوانی کنید و فیلد address_components را مشخص کنید.

مثال زیر از تکمیل خودکار برای پر کردن فیلدها در فرم نشانی استفاده می‌کند.

TypeScript

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();
}index.ts

JavaScript

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;
index.js

مشاهده نمونه

ممکن است مؤلفه نشانی street_number در پاسخ‌های «جزئیات جا» برای شناسه‌های جا در برخی‌از پیش‌بینی‌های تکمیل خودکار وجود نداشته باشد. این اتفاق معمولاً زمانی می‌افتد که نشانی را نتوان برای مکانی درون‌یابی کرد. در این موارد، آرایه types پیش‌بینی حاوی «route» خواهد بود. برای پیش‌بینی‌های تکمیل خودکار با شماره در شرح (پرسمان ورودی مطابقت دارد)، پاسخ «جزئیات جا» برای شناسه جا فقط درصورتی حاوی شماره خیابان است که آرایه types برای پیش‌بینی حداقل یکی از موارد زیر را داشته باشد:

street_address
محل
کارگاه

سفارشی‌سازی کردن نوشتار جای‌بان

به‌طور پیش‌فرض، فیلد نوشتاری ایجادشده توسط سرویس تکمیل خودکار حاوی نوشتار جای‌بان استاندارد است. برای اصلاح نوشتار، مشخصه placeholder را در عنصر input تنظیم کنید:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

توجه: نوشتار جای‌بان پیش‌فرض به‌طور خودکار بومی‌سازی می‌شود. اگر مقدار جای‌بان خودتان را مشخص کنید، باید بومی‌سازی آن مقدار را در برنامه‌تان مدیریت کنید. برای کسب اطلاعات درباره نحوه انتخاب زبان توسط Google Maps JavaScript API، سند مربوط به بومی‌سازی را بخوانید.

برای سفارشی‌سازی کردن ظاهر ابزاره، به سبک‌بندی ابزاره‌های «تکمیل خودکار» و SearchBox مراجعه کنید.

SearchBox به کاربران اجازه می‌دهد جستجوی جغرافیایی مبتنی بر نوشتار انجام دهند، مثلاً «پیتزا در نیویورک» یا «کفش‌فروشی‌های نزدیک خیابان رابسون». می‌توانید SearchBox را به فیلد نوشتاری پیوست کنید و با وارد شدن نوشتار، سرویس پیش‌بینی‌ها را به‌صورت فهرست انتخاب کرکره‌ای برمی‌گرداند.

SearchBox فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌دهد که می‌تواند شامل مکان‌ها (همان‌طور که توسط Places API تعریف شده است) به‌علاوه عبارت‌های جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در نیو» را وارد کند، فهرست انتخاب ممکن است عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام‌های مختلف پیتزافروشی‌ها را شامل شود. وقتی کاربر مکانی را از فهرست انتخاب می‌کند، اطلاعات مربوط به آن مکان به شیء SearchBox برگردانده می‌شود و می‌تواند توسط برنامه شما بازیابی شود.

سازنده SearchBox دو آرگومان می‌گیرد:

عنصر HTML input از نوع text. این فیلد ورودی است که سرویس SearchBox بر آن نظارت خواهد کرد و نتایجش را به آن پیوست خواهد کرد.
یک آرگومان options که می‌تواند حاوی ویژگی bounds باشد: bounds یک شیء google.maps.LatLngBounds است که منطقه‌ای را که باید در آن مکان‌ها جستجو شود مشخص می‌کند. نتایج به مکان‌های موجود در این مرزها متمایل هستند، اما به آن‌ها محدود نمی‌شوند.

کد زیر از پارامتر bounds برای سوگیری نتایج به‌سمت مکان‌های درون یک منطقه جغرافیایی خاص استفاده می‌کند که بااستفاده از مختصات عرض جغرافیایی/طول جغرافیایی مشخص شده است.

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 را راه‌اندازی می‌کند. می‌توانید 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", () => {
  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);
});index.ts

JavaScript

// 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);
});index.js

مشاهده نمونه

برای سفارشی‌سازی کردن ظاهر ابزاره، به سبک‌بندی ابزاره‌های «تکمیل خودکار» و 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 عبارت منطبق است.

نمونه زیر درخواست پیش‌بینی پُرسمان را برای عبارت «پیتزا در نزدیکی» اجرا می‌کند و نتیجه را در فهرست نمایش می‌دهد.

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">
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;index.ts

JavaScript

// 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;index.js

CSS

style.css

HTML

<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>index.html

مشاهده نمونه

کدهای جلسه

AutocompleteService.getPlacePredictions() می‌تواند از کد جلسه (درصورت پیاده‌سازی) برای گروه‌بندی درخواست‌های تکمیل خودکار برای اهداف صورت‌حساب استفاده کند. کدهای جلسه، مراحل پُرسمان و انتخاب جستجوی تکمیل خودکار کاربر را برای اهداف صورت‌حساب در یک جلسه مجزا گروه‌بندی می‌کنند. جلسه زمانی شروع می‌شود که کاربر شروع به تایپ کردن پُرسمان می‌کند و زمانی به‌پایان می‌رسد که مکانی را انتخاب می‌کند. هر جلسه می‌تواند چندین پُرسمان داشته باشد و پس‌از آن یک مکان انتخاب شود. وقتی جلسه به پایان می‌رسد، دیگر آن کد معتبر نیست. برنامه شما باید برای هر جلسه یک کد جدید تولید کند. توصیه می‌کنیم از کد جلسه برای همه جلسه‌های تکمیل خودکار استفاده کنید. اگر پارامتر sessionToken حذف شود یا اگر از کد جلسه مجدداً استفاده کنید، هزینه جلسه به‌گونه‌ای محاسبه می‌شود که گویی هیچ کد جلسه‌ای ارائه نشده است (هر درخواست به‌طور جداگانه صورت‌حساب می‌شود).

باید از همان کد جلسه برای ایجاد یک درخواست جزئیات جا در مکانی که از تماس با AutocompleteService.getPlacePredictions() حاصل می‌شود استفاده کنید. در این حالت، درخواست تکمیل خودکار با درخواست «جزئیات جا» ترکیب می‌شود و هزینه تماس به‌عنوان درخواست «جزئیات جا» معمولی محاسبه می‌شود. درخواست تکمیل خودکار رایگان است. اگر از کد جلسه برای درخواست استفاده نکنید، هم برای درخواست تکمیل خودکار و هم برای درخواست «جزئیات جا» هزینه دریافت می‌شود.

حتماً برای هر جلسه جدید، یک کد جلسه یکتا ارسال کنید. استفاده از یک کد برای بیش‌از یک جلسه «تکمیل خودکار» باعث نامعتبر شدن آن جلسه‌های «تکمیل خودکار» می‌شود و هزینه همه درخواست‌های «تکمیل خودکار» در جلسه‌های نامعتبر به‌طور جداگانه بااستفاده از واحد نگهداری موجودی «تکمیل خودکار» به‌ازای هر درخواست محاسبه می‌شود. درباره کد جلسه بیشتر بخوانید.

مثال زیر ایجاد یک کد جلسه و سپس ارسال آن در یک 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);

حتماً برای هر جلسه جدید، یک کد جلسه یکتا ارسال کنید. استفاده از یک کد برای بیش از یک جلسه باعث می‌شود که هر درخواست به‌صورت جداگانه صورت‌حساب شود.

درباره کد جلسه بیشتر بخوانید.

سبک‌بندی ابزاره‌های «تکمیل خودکار» و «جعبه جستجو»

به‌طور پیش‌فرض، عناصر میانای کاربر ارائه‌شده توسط Autocomplete و SearchBox برای گنجاندن در Google Map سبک‌بندی شده‌اند. شاید بخواهید سبک‌بندی را متناسب با سایت خودتان تنظیم کنید. کلاس‌های CSS زیر دردسترس است. همه کلاس‌های فهرست‌شده در زیر هم برای ابزاره Autocomplete و هم برای ابزاره SearchBox اعمال می‌شوند.

تصویر گرافیکی از کلاس‌های CSS برای ابزاره‌های «تکمیل خودکار» و
«چارگوش جستجو» — کلاس‌های 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` که بخش اصلی پیش‌بینی است. برای مکان‌های جغرافیایی، این شامل نام مکان، مانند «سیدنی»، یا نام و شماره خیابان، مانند «خیابان کینگ ۱۰» است. برای جستجوهای نوشتاری مثل «پیتزا در نیویورک»، این پارامتر حاوی نوشتار کامل پُرسمان است. به‌طور پیش‌فرض، `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 for Android، یا کنترل میانای کاربر تکمیل خودکار جا (قدیمی) در Places SDK for iOS است.
از همان ابتدا، فیلدهای داده «تکمیل خودکار جا» (قدیمی) را درک کنید.
فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامه‌سازی کاربردی خطایی برگرداند، برنامه شما به‌خوبی تنزل پیدا می‌کند.
مطمئن شوید که برنامه‌تان وقتی انتخابی وجود ندارد، این وضعیت را مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

برای بهینه‌سازی هزینه استفاده از سرویس «تکمیل خودکار جا» (قدیمی)، از ماسک‌های فیلد در ابزاره‌های «جزئیات جا» (قدیمی) و «تکمیل خودکار جا» (قدیمی) استفاده کنید تا فقط فیلدهای داده «تکمیل خودکار جا» (قدیمی) موردنیازتان برگردانده شود.

بهینه‌سازی پیشرفته هزینه

پیاده‌سازی برنامه‌نویسی‌شده «تکمیل خودکار جا (قدیمی)» را برای دسترسی به SKU: تکمیل خودکار - قیمت‌گذاری به‌ازای درخواست و درخواست نتایج Geocoding API درباره مکان انتخاب‌شده به‌جای «جزئیات جا (قدیمی)» درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمت‌گذاری به‌ازای درخواست همراه با Geocoding API مقرون‌به‌صرفه‌تر از قیمت‌گذاری به‌ازای جلسه (جلسه‌محور) است:

اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، Geocoding API این اطلاعات را با هزینه کمتری نسبت‌به فراخوانی Place Details (Legacy) ارائه می‌دهد.
اگر کاربران پیش‌بینی تکمیل خودکار را در میانگین چهار درخواست پیش‌بینی «تکمیل خودکار جا (قدیمی)» یا کمتر انتخاب کنند، قیمت‌گذاری براساس درخواست می‌تواند مقرون‌به‌صرفه‌تر از قیمت‌گذاری براساس جلسه باشد.

برای دریافت راهنمایی درباره انتخاب پیاده‌سازی «تکمیل خودکار جا (قدیمی)» که با نیازهایتان مطابقت داشته باشد، برگه‌ای را انتخاب کنید که با پاسخ شما به سؤال زیر مطابقت دارد.

آیا برنامه شما به اطلاعاتی غیراز نشانی و طول/عرض جغرافیایی پیش‌بینی انتخاب‌شده نیاز دارد؟

بله، به جزئیات بیشتری نیاز است

از «تکمیل خودکار جا» (قدیمی) مبتنی بر جلسه با «جزئیات جا» (قدیمی) استفاده کنید.
ازآنجایی‌که برنامه شما به «جزئیات جا (قدیمی)» نیاز دارد، مثل نام مکان، وضعیت کسب‌وکار، یا ساعت کاری، پیاده‌سازی شما از «تکمیل خودکار جا (قدیمی)» باید از کد جلسه استفاده کند (به‌صورت برنامه‌نویسی‌شده یا تعبیه‌شده در ابزاره‌های JavaScript، Android، یا iOS) به‌ازای هر جلسه به‌علاوه شناسه‌های محصول داده‌های Places قابل‌اعمال، بسته به اینکه کدام فیلدهای داده مکان را درخواست می‌کنید.^۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای داده «تکمیل خودکار جا (قدیمی)» موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ای
از کد جلسه با درخواست‌های «تکمیل خودکار جا» (قدیمی) استفاده کنید. هنگام درخواست «جزئیات مکان (قدیمی)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

شناسه جا از پاسخ «تکمیل خودکار جا» (قدیمی)
کد جلسه استفاده‌شده در درخواست «تکمیل خودکار جا» (قدیمی)
پارامتر fields که فیلدهای داده «تکمیل خودکار جا» (قدیمی) موردنیازتان را مشخص می‌کند

نه، فقط به نشانی و مکان نیاز دارد

Geocoding API می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت‌به Place Details (Legacy) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Place Autocomplete (Legacy). کارایی «تکمیل خودکار جا» (قدیمی) هر برنامه بسته به آنچه کاربران وارد می‌کنند، جایی که برنامه استفاده می‌شود، و اینکه آیا روال‌های مطلوب بهینه‌سازی عملکرد اجرا شده‌اند یا نه متفاوت است.

برای پاسخ دادن به سؤال زیر، تحلیل کنید که کاربر به‌طور میانگین چند نویسه تایپ می‌کند تا پیش‌بینی «تکمیل خودکار جا» (قدیمی) را در برنامه‌تان انتخاب کند.

آیا کاربران شما به‌طور میانگین با چهار درخواست یا کمتر، پیش‌بینی «تکمیل خودکار جا (قدیمی)» را انتخاب می‌کنند؟

بله

«تکمیل خودکار جا» (قدیمی) را به‌صورت برنامه‌نویسی‌شده بدون کد جلسه پیاده‌سازی کنید و Geocoding API را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API نشانی‌ها و مختصات طول/عرض جغرافیایی را ارائه می‌دهد. ایجاد چهار درخواست تکمیل خودکار - به‌ازای هر درخواست به‌علاوه یک فراخوانی Geocoding API درباره پیش‌بینی مکان انتخاب‌شده کمتر از هزینه «تکمیل خودکار جا (قدیمی)» به‌ازای هر جلسه است.^۱

برای کمک به کاربران در دریافت پیش‌بینی موردنظرشان با نویسه‌های کمتر، روال‌های مطلوب عملکرد را به‌کار بگیرید.

نه

از «تکمیل خودکار جا» (قدیمی) مبتنی بر جلسه با «جزئیات جا» (قدیمی) استفاده کنید.
ازآنجایی‌که میانگین تعداد درخواست‌هایی که انتظار دارید قبل‌از انتخاب پیش‌بینی «تکمیل خودکار جا» (قدیمی) توسط کاربر انجام شود، از هزینه قیمت‌گذاری هر جلسه فراتر می‌رود، پیاده‌سازی شما از «تکمیل خودکار جا» (قدیمی) باید از یک کد جلسه برای هر دو درخواست «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی) مرتبط استفاده کند در هر جلسه. ^۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست می‌کنید.

شناسه جا از پاسخ «تکمیل خودکار جا» (قدیمی)
کد جلسه استفاده‌شده در درخواست «تکمیل خودکار جا» (قدیمی)
پارامتر fields که فیلدهای داده‌های پایه مثل نشانی و هندسه را مشخص می‌کند

به‌تأخیر انداختن درخواست‌های «تکمیل خودکار جا» (قدیمی) را مدنظر قرار دهید
می‌توانید از استراتژی‌هایی مثل به‌تأخیر انداختن درخواست «تکمیل خودکار جا» (قدیمی) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامه‌تان درخواست‌های کمتری ارسال کند. برای مثال، ارسال درخواست‌های «تکمیل خودکار جا (قدیمی)» برای هر نویسه پس‌از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال می‌کنید، هزینه کل برای ۴ «تکمیل خودکار جا (قدیمی)» به‌ازای هر درخواست + Geocoding خواهد بود.^۱

اگر با به‌تأخیر انداختن درخواست‌ها می‌توانید میانگین درخواست‌های برنامه‌ای را به کمتر از چهار برسانید، می‌توانید از راهنمای پیاده‌سازی «تکمیل خودکار جا» (قدیمی) با Geocoding API پیروی کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند از دید کاربری که ممکن است انتظار داشته باشد با هر کلید جدید پیش‌بینی‌ها را ببیند، به‌عنوان تأخیر درک شود.

روال‌های مطلوب عملکرد را به‌کار بگیرید تا به کاربران کمک کنید پیش‌بینی موردنظرشان را با نویسه‌های کمتری دریافت کنند.

برای اطلاع از هزینه‌ها، فهرست‌های قیمت‌گذاری «پلاتفرم Google Maps» را ببینید.

روال‌های مطلوب عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد «تکمیل خودکار جا» (قدیمی) را شرح می‌دهد:

محدودیت‌های کشور، سوگیری مکان، و (برای پیاده‌سازی‌های برنامه‌ای) اولویت زبان را به پیاده‌سازی «تکمیل خودکار جا» (قدیمی) اضافه کنید. برای ابزاره‌ها به اولویت زبان نیازی نیست چون آن‌ها اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
اگر «تکمیل خودکار جا» (قدیمی) با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
در شرایطی که کاربر یکی از پیش‌بینی‌های «تکمیل خودکار جا (قدیمی)» را انتخاب نمی‌کند، معمولاً به این دلیل که هیچ‌کدام از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی اصلی کاربر دوباره استفاده کنید تا نتایج مرتبط‌تری دریافت کنید:
- اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، از ورودی اصلی کاربر در فراخوانی به Geocoding API مجدداً استفاده کنید.
- اگر انتظار دارید کاربر پُرسمان‌ها را برای مکان خاصی براساس نام یا نشانی وارد کند، از درخواست «جزئیات جا (قدیمی)» استفاده کنید. اگر نتایج فقط در منطقه خاصی موردانتظار است، از سوگیری مکان استفاده کنید.
سناریوهای دیگری که در آن‌ها بهتر است به Geocoding API برگردید عبارت‌اند از:
- کاربرانی که نشانی‌های فرعی را وارد می‌کنند، مانند نشانی‌های مربوط به واحدها یا آپارتمان‌های خاص در یک ساختمان. برای مثال، نشانی چکی «Stroupežnického 3191/17, Praha» پیش‌بینی جزئی در «تکمیل خودکار جا» (قدیمی) ارائه می‌دهد.
- کاربرانی که نشانی‌ها را با پیشوندهای بخش جاده وارد می‌کنند، مانند «23-30 29th St, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره کائوآئی در هاوایی.

سوگیری مکانی

با ارسال پارامتر location و پارامتر radius، نتایج را به منطقه مشخصی متمایل کنید. این کار به «تکمیل خودکار جا» (قدیمی) دستور می‌دهد که نمایش نتایج را در منطقه تعریف‌شده ترجیح دهد. ممکن است نتایج خارج از منطقه تعریف‌شده همچنان نمایش داده شود. می‌توانید از پارامتر includedRegionCodes برای فیلتر کردن نتایج استفاده کنید تا فقط مکان‌های داخل کشور مشخص‌شده نشان داده شود.

هشدار: اگر radius ارائه نشود، پارامتر location نادیده گرفته می‌شود.

نتایج مربوط به مؤسسه‌ها معمولاً رتبه بالایی ندارند که درصورت بزرگ بودن منطقه جستجو در نتایج نشان داده شوند. اگر می‌خواهید مؤسسه‌ها در نتایج ترکیبی مؤسسه/ زمین‌کدیاب نشان داده شوند، می‌توانید شعاع کوچک‌تری را مشخص کنید. همچنین می‌توانید از types=establishment برای محدود کردن نتایج به مؤسسه‌ها استفاده کنید.

محدود کردن مکان

با ارسال پارامتر locationRestriction، نتایج را به منطقه مشخصی محدود کنید.

همچنین می‌توانید با افزودن پارامتر strictbounds ، نتایج را به منطقه‌ای که با location و پارامتر radius تعریف شده است محدود کنید. این کار به «تکمیل خودکار جا» (قدیمی) دستور می‌دهد فقط نتایج درون آن منطقه را برگرداند.

حدود استفاده

سهمیه‌ها

برای اطلاعات مربوط به سهمیه و قیمت‌گذاری، به سند استفاده و صورت‌حساب برای Places API مراجعه کنید.

تکمیل خودکار جا (قدیمی) با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مقدمه

درحال شروع کردن

بار کردن کتابخانه

خلاصه کلاس‌ها

افزودن ابزاره «تکمیل خودکار»

محدود کردن پیش‌بینی‌های «تکمیل خودکار»

تنظیم گزینه‌ها در ساختار

TypeScript

JavaScript

مشخص کردن فیلدهای داده

تعریف سوگیری‌ها و مرزهای ناحیه جستجو برای تکمیل خودکار

تغییر مرزهای «تکمیل خودکار» موجود

TypeScript

JavaScript

تنظیم کردن مرزها برای ناحیه نمایش نقشه

TypeScript

JavaScript

TypeScript

JavaScript

محدود کردن جستجو به مرزهای فعلی

محدود کردن پیش‌بینی‌ها به کشوری خاص

TypeScript

JavaScript

محدود کردن انواع مکان

درحال دریافت اطلاعات مکان

TypeScript

JavaScript

سفارشی‌سازی کردن نوشتار جای‌بان

افزودن ابزاره SearchBox

تغییر دادن منطقه جستجو برای SearchBox

درحال دریافت اطلاعات مکان

TypeScript

JavaScript

بازیابی پیش‌بینی‌های «سرویس تکمیل خودکار جا» به‌صورت برنامه‌نویسی‌شده

TypeScript

JavaScript

CSS

HTML

کدهای جلسه

سبک‌بندی ابزاره‌های «تکمیل خودکار» و «جعبه جستجو»

بهینه‌سازی «تکمیل خودکار جا (قدیمی)»

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

بهینه‌سازی پیشرفته هزینه

بله، به جزئیات بیشتری نیاز است

نه، فقط به نشانی و مکان نیاز دارد

بله

نه

روال‌های مطلوب عملکرد

سوگیری مکانی

محدود کردن مکان

حدود استفاده

سهمیه‌ها

تکمیل خودکار جا (قدیمی)