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

مقدمه

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

شروع کردن

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

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

1. به Google Cloud Console بروید.
2. روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
3. از لیست APIها در داشبورد ، Places API را جستجو کنید.
4. اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
   1. در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
   2. Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
   3. 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);
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 داده مکان‌هایی که به آنها نیاز ندارید اجتناب کنید. همانطور که در مثال قبلی نشان داده شد، ویژگی 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() می توانید یکی از این موارد را مشخص کنید:

• آرایه ای حاوی حداکثر پنج مقدار از جدول 1 یا جدول 2 از انواع مکان . به عنوان مثال:

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

  یا:

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

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

درخواست رد می شود در صورتی که:

• شما بیش از پنج نوع را مشخص می کنید.
• شما انواع ناشناخته را مشخص می کنید.
• هر نوع از جدول 1 یا جدول 2 را با هر فیلتری از جدول 3 مخلوط می کنید.

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

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

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

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

1. یک کنترل کننده رویداد برای رویداد place_changed ایجاد کنید، و addListener() را در شی Autocomplete فراخوانی کنید تا کنترل کننده را اضافه کنید.
2. 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();
}
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 را روی عنصر 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);
});
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

مشاهده نمونه

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

می‌توانید از همان نشانه جلسه برای ایجاد یک درخواست جزئیات مکان در مکانی که از تماس با 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 اعمال می‌شوند.

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

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

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

• سریعترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ابزارک تکمیل خودکار Maps JavaScript API، Places SDK برای ویجت تکمیل خودکار Android، یا Places SDK برای کنترل رابط کاربری خودکار iOS است.
• از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان ضروری ایجاد کنید.
• فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
• از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
• مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.

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

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

برای بهینه‌سازی هزینه استفاده از سرویس تکمیل خودکار مکان، از ماسک‌های فیلد در ویجت‌های Place Details و Place Autocomplete استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.

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

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

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

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

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

دستورالعمل‌های زیر راه‌هایی را برای بهینه‌سازی عملکرد تکمیل خودکار مکان توضیح می‌دهند:

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

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

سهمیه ها

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

سیاست ها

استفاده از کتابخانه مکان‌ها، Maps JavaScript API باید مطابق با خط‌مشی‌های توصیف‌شده برای Places API باشد.

مقدمه

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

شروع کردن

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

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

1. به Google Cloud Console بروید.
2. روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
3. از لیست APIها در داشبورد ، Places API را جستجو کنید.
4. اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
   1. در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
   2. Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
   3. 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);
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 های مورد نیاز خودداری کنید. ویژگی های 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);
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() استفاده کنید. این محدودیت یک نوع یا مجموعه نوع را مشخص می کند ، همانطور که در انواع مکان ذکر شده است. اگر هیچ محدودیتی مشخص نشده باشد ، همه نوع بازگردانده می شوند.

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

• آرایه ای حاوی پنج مقدار از جدول 1 یا جدول 2 از انواع مکان . به عنوان مثال:

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

  یا:

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

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

درخواست اگر:

• شما بیش از پنج نوع را مشخص می کنید.
• شما انواع ناشناخته را مشخص می کنید.
• شما هر نوع از جدول 1 یا جدول 2 را با هر فیلتر از جدول 3 مخلوط می کنید.

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

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

گرفتن اطلاعات در محل

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

1. برای یک رویداد addlistener ( Autocomplete با addListener() در شیء place_changed تماس بگیرید تا یک کنترل کننده را اضافه کنید.
2. برای بازیابی یک شیء 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();
}
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

مثال مشاهده

سفارشی سازی متن نگهدارنده

به طور پیش فرض ، قسمت متن ایجاد شده توسط سرویس 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);
});
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() پیش بینی های مکان را برمی گرداند. توجه: "مکان" می تواند یک مکان ، موقعیت جغرافیایی یا نکته برجسته مورد علاقه باشد ، همانطور که توسط مکان های 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;
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 حذف شود ، یا اگر از یک جلسه جلسه استفاده مجدد می کنید ، جلسه به نظر می رسد که هیچ نشانه ای از جلسه ارائه نشده است (هر درخواست به طور جداگانه صورتحساب می شود).

شما می توانید از همان 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 اعمال می شود.

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

در این بخش بهترین شیوه ها برای کمک به شما در استفاده بیشتر از محل خدمات خودکار به صورت خودکار توضیح داده شده است.

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

• سریعترین راه برای ایجاد رابط کاربری کار استفاده از نقشه های API AUTOCPLOTE API MAPS ، SDK را برای ویجت خودکار Android قرار می دهد ، یا SDK را برای کنترل UI AUTOCPLETE IOS قرار می دهد
• از ابتدا درک از زمینه های داده خودکار مکان ضروری را ایجاد کنید.
• فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
• از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
• اطمینان حاصل کنید که برنامه شما در صورت عدم انتخاب ، کنترل می کند و راهی برای ادامه کار به کاربران ارائه می دهد.

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

بهینه سازی هزینه اساسی

برای بهینه‌سازی هزینه استفاده از سرویس تکمیل خودکار مکان، از ماسک‌های فیلد در ویجت‌های Place Details و Place Autocomplete استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.

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

به منظور دسترسی به قیمت گذاری در هر درخواست ، اجرای برنامه نویسی مکان را به صورت خودکار در نظر بگیرید و به جای جزئیات مکان ، نتایج API GeoCoding را در مورد مکان انتخاب شده درخواست کنید. قیمت گذاری هر درخواست جفت شده با Geocoding API مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) است اگر هر دو شرایط زیر رعایت شود:

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

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

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

دستورالعمل های زیر روشهای بهینه سازی عملکرد خودکار را شرح می دهد:

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

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

سهمیه ها

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

سیاست ها

استفاده از کتابخانه مکان ها ، نقشه های API JavaScript باید مطابق با سیاست های شرح داده شده برای API مکان ها باشد.