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

معرفی

تکمیل خودکار یکی از ویژگی های کتابخانه 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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 اعمال می‌شوند.

از مولفه Place Picker استفاده کنید

توجه: این نمونه از یک کتابخانه متن باز استفاده می کند. برای پشتیبانی و بازخورد مربوط به کتابخانه به README مراجعه کنید.

کامپوننت های وب را امتحان کنید. از مؤلفه وب Place Picker برای فعال کردن ورودی متن استفاده کنید که به کاربران نهایی امکان می دهد آدرس یا مکان خاصی را با استفاده از تکمیل خودکار جستجو کنند.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سهمیه ها

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

سیاست های

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