محل تکمیل خودکار

مقدمه

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

شروع به کار

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

برای مشاهده لیست API های فعال خود:

1. به کنسول گوگل کلود بروید.
2. روی دکمه‌ی «انتخاب پروژه» کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API تنظیم کرده‌اید، انتخاب کنید و روی «باز کردن» کلیک کنید.
3. از لیست APIهای موجود در داشبورد ، به دنبال Places API بگردید.
4. اگر API را در لیست مشاهده کردید، همه چیز آماده است. با این حال، این پروژه در وضعیت Legacy است. برای اطلاعات بیشتر در مورد مرحله Legacy و نحوه مهاجرت از Legacy به سرویس‌های جدیدتر، به محصولات و ویژگی‌های Legacy مراجعه کنید. یک استثنا برای ویجت‌های Autocomplete و SearchBox وجود دارد که هنوز به عنوان یک محصول GA در Places API (جدید) در دسترس نیستند.

کتابخانه را بارگذاری کنید

سرویس Places یک کتابخانه مستقل است که از کد اصلی Maps JavaScript API جدا می‌باشد. برای استفاده از ویژگی‌های موجود در این کتابخانه، ابتدا باید آن را با استفاده از پارامتر libraries در URL bootstrap مربوط به 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 برای بازیابی نتایج تکمیل خودکار به صورت برنامه‌نویسی استفاده کنید (به مرجع API جاوا اسکریپت Maps: کلاس AutocompleteService مراجعه کنید).

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

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

  

  

• SearchBox یک فیلد ورودی متن به صفحه وب شما اضافه می‌کند، تقریباً مشابه Autocomplete . تفاوت‌ها به شرح زیر است:
  • تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می‌شوند. SearchBox لیست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌دهد که می‌تواند شامل مکان‌ها (مطابق تعریف API Places) به علاوه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر عبارت «pizza in new» را وارد کند، لیست انتخاب ممکن است شامل عبارت «pizza in New York, NY» و همچنین نام پیتزافروشی‌های مختلف باشد.
  • 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 تنظیم شده خواهد بود. می‌توانید از شناسه مکان برگردانده شده با فراخوانی سرویس‌های Places، Geocoding، Directions یا Distance Matrix استفاده کنید.

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

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

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

سازنده‌ی 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);
index.ts

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

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

فیلدهای داده را مشخص کنید تا از پرداخت هزینه SKUهای Places Data که نیازی به آنها ندارید، جلوگیری شود. همانطور که در مثال قبلی نشان داده شد، ویژگی 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);
index.ts

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() برای تطبیق نتایج با نمای نقشه استفاده کنید، حتی اگر آن نمای تغییر کند.

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

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

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

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

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

مشاهده مثال

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

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

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

مشاهده مثال

انواع مکان‌های محدود

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

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

• آرایه‌ای شامل حداکثر پنج مقدار از جدول ۱ یا جدول ۲ از نوع مکان . برای مثال:

  types: ['hospital', 'pharmacy', 'bakery', 'country']

  یا:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• هر یک از فیلترهای جدول ۳ از نوع مکان . شما فقط می‌توانید یک مقدار واحد را از جدول ۳ مشخص کنید.

درخواست رد خواهد شد اگر:

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

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

از نسخه آزمایشی دیدن کنید

گرفتن اطلاعات مکان

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

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

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

ویژگی name شامل description از پیش‌بینی‌های Places Autocomplete است. می‌توانید اطلاعات بیشتر در مورد description را در مستندات Places Autocomplete مطالعه کنید.

برای فرم‌های آدرس، دریافت آدرس در قالب ساختاریافته مفید است. برای بازگرداندن آدرس ساختاریافته برای مکان انتخاب‌شده، تابع 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();
}
index.ts

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

مشاهده مثال

متن جایگذاری را سفارشی کنید

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

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

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

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

یک ویجت SearchBox اضافه کنید

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

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

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

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

کد زیر از پارامتر 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

برای تغییر ناحیه جستجو برای یک SearchBox موجود، تابع setBounds() را روی شیء SearchBox فراخوانی کنید و شیء LatLngBounds مربوطه را به آن ارسال کنید.

مشاهده مثال

گرفتن اطلاعات مکان

وقتی کاربر یک آیتم را از پیش‌بینی‌های پیوست شده به کادر جستجو انتخاب می‌کند، سرویس یک رویداد places_changed را فعال می‌کند. می‌توانید getPlaces() را روی شیء SearchBox فراخوانی کنید تا آرایه‌ای حاوی چندین پیش‌بینی را بازیابی کنید که هر کدام یک شیء PlaceResult هستند.

برای اطلاعات بیشتر در مورد شیء PlaceResult ، به مستندات مربوط به place detail results مراجعه کنید.

// 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

// 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

مشاهده مثال

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

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

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

AutocompleteService متدهای زیر را ارائه می‌دهد:

• getPlacePredictions() پیش‌بینی‌های مکان را برمی‌گرداند. توجه: یک «مکان» می‌تواند یک موسسه، موقعیت جغرافیایی یا یک نقطه برجسته مورد توجه باشد، همانطور که توسط Places API تعریف شده است.
• getQueryPredictions() فهرستی گسترده از پیش‌بینی‌ها را برمی‌گرداند که می‌تواند شامل مکان‌ها (مطابق تعریف API مکان‌ها) به علاوه‌ی عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر عبارت «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام پیتزافروشی‌های مختلف باشد.

هر دو روش فوق آرایه‌ای از اشیاء پیش‌بینی به شکل زیر را برمی‌گردانند:

• description پیش‌بینی منطبق است.
• distance_meters فاصله مکان از AutocompletionRequest.origin مشخص شده بر حسب متر است.
• matched_substrings شامل مجموعه‌ای از زیررشته‌ها در توضیحات است که با عناصر ورودی کاربر مطابقت دارند. این برای برجسته کردن آن زیررشته‌ها در برنامه شما مفید است. در بسیاری از موارد، پرس‌وجو به عنوان زیررشته‌ای از فیلد توضیحات ظاهر می‌شود.
  • length طول زیررشته است.
  • offset ، فاصله‌ی کاراکتری است که از ابتدای رشته‌ی توصیفی، جایی که زیررشته‌ی منطبق ظاهر می‌شود، اندازه‌گیری می‌شود.
• place_id یک شناسه متنی است که به طور منحصر به فرد یک مکان را مشخص می‌کند. برای بازیابی اطلاعات در مورد مکان، این شناسه را در فیلد placeId از درخواست Place Details ارسال کنید. درباره نحوه ارجاع به یک مکان با place ID بیشتر بیاموزید.
• 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;
index.ts

// 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

style.css

<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 حذف شود، یا اگر از یک توکن جلسه دوباره استفاده کنید، جلسه طوری محاسبه می‌شود که انگار هیچ توکن جلسه‌ای ارائه نشده است (هزینه هر درخواست جداگانه محاسبه می‌شود).

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

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

مثال زیر ایجاد یک توکن نشست و سپس ارسال آن به یک AutocompleteService (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

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

بهینه‌سازی تکمیل خودکار مکان (Legacy)

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

در اینجا چند دستورالعمل کلی آورده شده است:

• سریع‌ترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ویجت Maps JavaScript API Place Autocomplete (Legacy) ، ویجت Places SDK برای اندروید Place Autocomplete (Legacy) یا کنترل رابط کاربری Places SDK برای iOS Place Autocomplete (Legacy) است.
• از همان ابتدا فیلدهای داده ضروری Place Autocomplete (Legacy) را درک کنید.
• فیلدهای Location biasing و location restriction اختیاری هستند اما می‌توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
• از مدیریت خطا استفاده کنید تا مطمئن شوید که برنامه شما در صورت بروز خطا توسط API، به طور مناسب از رده خارج می‌شود.
• مطمئن شوید که برنامه شما وقتی هیچ انتخابی وجود ندارد، کار می‌کند و به کاربران راهی برای ادامه ارائه می‌دهد.

بهترین شیوه‌های بهینه‌سازی هزینه

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

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

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

پیاده‌سازی برنامه‌ریزی‌شده‌ی Place Autocomplete (Legacy) را برای دسترسی به SKU در نظر بگیرید: Autocomplete - Per Request pricing و درخواست نتایج Geocoding API در مورد مکان انتخاب‌شده به جای Place Details (Legacy). قیمت‌گذاری بر اساس درخواست همراه با Geocoding API در صورت برآورده شدن هر دو شرط زیر، مقرون‌به‌صرفه‌تر از قیمت‌گذاری بر اساس هر جلسه (مبتنی بر جلسه) است:

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

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

بهترین شیوه‌های عملکرد

The following guidelines describe ways to optimize Place Autocomplete (Legacy) performance:

• Add country restrictions, location biasing , and (for programmatic implementations) language preference to your Place Autocomplete (Legacy) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
• If Place Autocomplete (Legacy) is accompanied by a map, you can bias location by map viewport.
• In situations when a user does not choose one of the Place Autocomplete (Legacy) predictions, generally because none of those predictions are the result-address wanted, you can reuse the original user input to attempt to get more relevant results:
  • If you expect the user to enter only address information, reuse the original user input in a call to the Geocoding API .
  • If you expect the user to enter queries for a specific place by name or address, use a Place Details (Legacy) request . If results are only expected in a specific region, use location biasing .
  Other scenarios when it's best to fall back to the Geocoding API include:
  • Users inputting subpremise addresses, such as addresses for specific units or apartments within a building. For example, the Czech address "Stroupežnického 3191/17, Praha" yields a partial prediction in Place Autocomplete (Legacy).
  • Users inputting addresses with road-segment prefixes like "23-30 29th St, Queens" in New York City or "47-380 Kamehameha Hwy, Kaneohe" on the island of Kauai in Hawai'i.

Location biasing

Bias results to a specified area by passing a location parameter and a radius parameter. This instructs Place Autocomplete (Legacy) to prefer showing results within the defined area. Results outside of the defined area may still be displayed. You can use the components parameter to filter results to show only those places within a specified country.

Location restricting

Restrict results to a specified area by passing a locationRestriction parameter.

You may also restrict results to the region defined by location and a radius parameter, by adding the strictbounds parameter. This instructs Place Autocomplete (Legacy) to return only results within that region.

محدودیت‌های استفاده

Quotas

For quota and pricing information, see the Usage and Billing documentation for the Places API.