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

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

مهاجرت به مکان جدید تکمیل خودکار، مهاجرت به مکان جدید تکمیل خودکار، مهاجرت به مکان جدید تکمیل خودکار، مهاجرت به مکان جدید تکمیل خودکار

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

تکمیل خودکار مکان یکی از ویژگی‌های کتابخانه مکان‌ها در API جاوا اسکریپت Maps است. شما می‌توانید از تکمیل خودکار برای دادن رفتار جستجوی پیش از تایپ به برنامه‌های خود در فیلد جستجوی Google Maps استفاده کنید.

این صفحه تفاوت‌های بین ویژگی‌های قدیمی و جدید تکمیل خودکار مکان را توضیح می‌دهد. در هر دو نسخه، دو روش کلی برای ادغام تکمیل خودکار وجود دارد:

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

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

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

`PlacesService` (قدیمی)	`Place` (جدید)
مرجع خدمات تکمیل خودکار مکان‌ها	مرجع تکمیل خودکار داده‌ها (جدید)
`AutocompletionRequest`	`AutocompleteRequest`
`AutocompleteService.getPlacePredictions`	`AutocompleteSuggestion.fetchAutocompleteSuggestions`
`AutocompletePrediction`	`PlacePrediction`
متدها برای مدیریت شیء نتایج و پاسخ `PlacesServiceStatus` نیاز به استفاده از یک تابع فراخوانی (callback) دارند.	از Promiseها استفاده می‌کند و به صورت ناهمگام کار می‌کند.
متدها نیاز به بررسی `PlacesServiceStatus` دارند.	نیازی به بررسی وضعیت نیست، می‌تواند از مدیریت خطای استاندارد استفاده کند. اطلاعات بیشتر .
فیلدهای داده‌ی Place هنگام ایجاد نمونه‌ی `Autocomplete` به عنوان گزینه تنظیم می‌شوند.	فیلدهای داده‌ی Place بعداً هنگام فراخوانی تابع `fetchFields()` تنظیم می‌شوند.
پیش‌بینی‌های پرس‌وجو پشتیبانی می‌شوند (فقط `SearchBox` ).	پیش‌بینی‌های پرس‌وجو در کلاس `Autocomplete` در دسترس نیستند.
محدود به مجموعه‌ای ثابت از انواع مکان‌ها و فیلدهای داده مکان .	دسترسی به مجموعه‌ی گسترده‌ای از انواع مکان‌ها و فیلدهای داده‌های مکانی .

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

مقایسه کد (برنامه‌ای)

این بخش، کد مربوط به تکمیل خودکار را مقایسه می‌کند تا تفاوت‌های بین سرویس Places و کلاس Place، برای رابط‌های برنامه‌نویسی، را نشان دهد.

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

سرویس قدیمی Places به شما امکان می‌دهد پیش‌بینی‌های تکمیل خودکار را به صورت برنامه‌نویسی بازیابی کنید تا کنترل بیشتری بر رابط کاربری نسبت به آنچه کلاس Autocomplete ارائه می‌دهد، داشته باشید. در مثال زیر، یک درخواست واحد برای "par" ارسال می‌شود که شامل یک AutocompletionRequest شامل مقدار ورودی و مجموعه‌ای از محدوده‌ها برای بایاس کردن پیش‌بینی است. این مثال لیستی از نمونه‌های AutocompletePrediction را برمی‌گرداند و توضیحات مربوط به هر یک را نشان می‌دهد. تابع example همچنین یک توکن session ایجاد می‌کند و آن را به درخواست اعمال می‌کند.

function init() {
  const placeInfo = document.getElementById("prediction");
  const service = new google.maps.places.AutocompleteService();
  const placesService = new google.maps.places.PlacesService(placeInfo);
  var sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    bounds: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  }

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const displaySuggestions = function (predictions, status) {
    // Check the status of the Places Service.
    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 placeRequest = {
      placeId: predictions[0].place_id,
      fields: ["name", "formatted_address"],
    };

    placesService.getDetails(placeRequest, (place, status) => {
      if (status == google.maps.places.PlacesServiceStatus.OK && place) {
        placeInfo.textContent = `
          First predicted place: ${place.name} at ${place.formatted_address}`
      }
    });

  };

  // Show the results of the query.
  service.getPlacePredictions(request, displaySuggestions);
}

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

کلاس جدید Place همچنین به شما امکان می‌دهد پیش‌بینی‌های تکمیل خودکار را به صورت برنامه‌نویسی بازیابی کنید تا کنترل بیشتری بر رابط کاربری نسبت به آنچه توسط کلاس PlaceAutocompleteElement ارائه می‌شود، داشته باشید. در مثال زیر، یک درخواست واحد برای "par" ارسال می‌شود که یک AutocompleteRequest شامل مقدار ورودی و مجموعه‌ای از محدوده‌ها برای بایاس کردن پیش‌بینی است. این مثال لیستی از نمونه‌های placePrediction را برمی‌گرداند و توضیحات مربوط به هر یک را نشان می‌دهد. تابع example همچنین یک توکن session ایجاد می‌کند و آن را به درخواست اعمال می‌کند.

async function init() {
  let sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    locationBias: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  };

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

  const resultsElement = document.getElementById("results");

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    const listItem = document.createElement("li");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.text),
    );

    resultsElement.appendChild(listItem);
  }

  // Show the first predicted place.
  let place = suggestions[0].placePrediction.toPlace();

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent = `
    First predicted place: ${place.displayName} at ${place.formattedAddress}`
}

جدول زیر برخی از تفاوت‌های اصلی در استفاده از ویجت‌های تکمیل خودکار بین سرویس Places (قدیمی) و کلاس Place (جدید) را فهرست می‌کند:

خدمات اماکن (قدیمی)	مکان (جدید)
کلاس `Autocomplete` برای پیش‌بینی مکان‌ها.	کلاس `PlaceAutocompleteElement` برای پیش‌بینی مکان.
کلاس `SearchBox` برای پیش‌بینی‌های پرس‌وجو.	پیش‌بینی‌های پرس‌وجو در کلاس `Autocomplete` در دسترس نیستند.
فقط متن پیش‌فرضِ جای‌نگهدار ورودی، بومی‌سازی شده است.	محل قرارگیری متن برای ورود اطلاعات، لوگوی لیست پیش‌بینی‌ها و پیش‌بینی مکان‌ها، همگی از محلی‌سازی منطقه‌ای پشتیبانی می‌کنند.
ویجت از `setBounds()` یا `autocomplete.bindTo()` برای محدود کردن (بایاس کردن) جستجو به مرزهای مشخص شده و `strictBounds` برای محدود کردن نتایج به مرزهای مشخص شده استفاده می‌کند.	ویجت از ویژگی `locationBias` برای جهت‌دهی نتایج به مرزهای مشخص‌شده و از ویژگی `locationRestriction` برای محدود کردن جستجو به مرزهای مشخص‌شده استفاده می‌کند.
ویجت‌ها فقط می‌توانند با استفاده از یک عنصر ورودی استاندارد HTML ادغام شوند.	ویجت را می‌توان با استفاده از یک عنصر ورودی استاندارد HTML یا یک عنصر `gmp-place-autocomplete` ادغام کرد.
هنگام استفاده از ویجت، ممکن است کاربران مواردی را درخواست کنند که معتبر نباشند (برای مثال "bisneyland")؛ این مورد باید به صراحت مدیریت شود.	این ویجت فقط نتایج مربوط به پیشنهادهای ارائه شده را برمی‌گرداند و نمی‌تواند درخواست‌هایی برای مقادیر دلخواه ارسال کند؛ بنابراین نیازی به مدیریت درخواست‌های نامعتبر احتمالی نیست.
نمونه‌ی قدیمی `PlaceResult` را برمی‌گرداند.	نمونه‌ای از `Place` برمی‌گرداند.
فیلدهای داده‌ی Place به عنوان گزینه‌هایی برای شیء `Autocomplete` تنظیم می‌شوند.	فیلدهای داده‌ی Place زمانی تنظیم می‌شوند که کاربر انتخابی انجام می‌دهد و تابع `fetchFields()` فراخوانی می‌شود.
محدود به مجموعه‌ای ثابت از انواع مکان‌ها و فیلدهای داده مکان .	دسترسی به مجموعه‌ی گسترده‌ای از انواع مکان‌ها و فیلدهای داده‌های مکانی .

مقایسه کد (ابزارک‌ها)

این بخش کد مربوط به تکمیل خودکار را مقایسه می‌کند تا تفاوت‌های بین ویجت تکمیل خودکار مکان قدیمی و عنصر تکمیل خودکار مکان جدید را نشان دهد.

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

سرویس مکان‌ها دو نوع ویجت تکمیل خودکار ارائه می‌دهد که می‌توانید با استفاده از کلاس‌های Autocomplete و SearchBox آنها را اضافه کنید. هر نوع ویجت را می‌توان به عنوان یک کنترل نقشه به نقشه اضافه کرد یا مستقیماً در یک صفحه وب جاسازی کرد. مثال کد زیر جاسازی یک ویجت Autocomplete به عنوان یک کنترل نقشه نشان می‌دهد.

سازنده‌ی ویجت Autocomplete دو آرگومان می‌گیرد:
- یک عنصر input HTML از نوع text . این فیلد ورودی است که سرویس تکمیل خودکار آن را نظارت کرده و نتایج خود را به آن پیوست می‌کند.
- یک آرگومان اختیاری AutocompleteOptions ، که در آن می‌توانید گزینه‌های بیشتری را برای محدود کردن پرس‌وجو مشخص کنید.
برای تعیین مرزها، می‌توان نمونه‌ی Autocomplete را با فراخوانی autocomplete.bindTo() به طور صریح به نقشه متصل کرد.
فیلدهای داده را در گزینه‌های تکمیل خودکار مشخص کنید.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapTypeControl: false,
  });
  const card = document.getElementById("pac-card");
  const input = document.getElementById("pac-input");
  const options = {
    fields: ["formatted_address", "geometry", "name"],
    strictBounds: false,
  };

  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  const autocomplete = new google.maps.places.Autocomplete(input, options);

  // Bind the map's bounds (viewport) property to the autocomplete object,
  // so that the autocomplete requests use the current map bounds for the
  // bounds option in the request.
  autocomplete.bindTo("bounds", map);

  const infowindow = new google.maps.InfoWindow();
  const infowindowContent = document.getElementById("infowindow-content");

  infowindow.setContent(infowindowContent);

  const marker = new google.maps.Marker({
    map,
    anchorPoint: new google.maps.Point(0, -29),
  });

  autocomplete.addListener("place_changed", () => {
    infowindow.close();
    marker.setVisible(false);

    const place = autocomplete.getPlace();

    if (!place.geometry || !place.geometry.location) {
      // User entered the name of a Place that was not suggested and
      // pressed the Enter key, or the Place Details request failed.
      window.alert("No details available for input: '" + place.name + "'");
      return;
    }

    // If the place has a geometry, then present it on a map.
    if (place.geometry.viewport) {
      map.fitBounds(place.geometry.viewport);
    } else {
      map.setCenter(place.geometry.location);
      map.setZoom(17);
    }

    marker.setPosition(place.geometry.location);
    marker.setVisible(true);
    infowindowContent.children["place-name"].textContent = place.name;
    infowindowContent.children["place-address"].textContent =
      place.formatted_address;
    infowindow.open(map, marker);
  });
}

ابزارک تکمیل خودکار مکان (جدید)

کلاس Place، PlaceAutocompleteElement ارائه می‌دهد، یک زیرکلاس HTMLElement که یک کامپوننت رابط کاربری ارائه می‌دهد که می‌تواند به عنوان یک کنترل نقشه به نقشه اضافه شود یا مستقیماً در یک صفحه وب جاسازی شود. مثال کد زیر، جاسازی یک ویجت PlaceAutocompleteElement به عنوان یک کنترل نقشه نشان می‌دهد.

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

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

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

عنصر PlaceAutocompleteElement فیلد ورودی مخصوص به خود را ارائه می‌دهد و مستقیماً با استفاده از HTML یا جاوا اسکریپت (به جای اینکه یک عنصر ورودی موجود ارائه شود) در صفحه وارد می‌شود.
پیش‌بینی‌های پرس‌وجو در کلاس Autocomplete در دسترس نیستند.
PlaceAutocompleteElement با استفاده از PlaceAutocompleteElementOptions ساخته شده است.
- فیلدهای داده محل قرارگیری در زمان انتخاب (هنگام فراخوانی تابع fetchFields() ) مشخص می‌شوند.
با استفاده از گزینه‌های locationBounds یا locationRestriction ، محدودیت‌ها را تعیین کنید.

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  const placeAutocomplete =
    new google.maps.places.PlaceAutocompleteElement({
      locationRestriction: map.getBounds(),
    });

  placeAutocomplete.id = "place-autocomplete-input";
  const card = document.getElementById("place-autocomplete-card");

  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  // Create the marker and infowindow.
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});

  // Add the gmp-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( place ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location"],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      map.fitBounds(place.viewport);
    } else {
      map.setCenter(place.location);
      map.setZoom(17);
    }

    let content =
      '<div id="infowindow-content">' +
      '<span id="place-displayname" class="title">' +
      place.displayName +
      '</span><br />' +
      '<span id="place-address">' +
      place.formattedAddress +
      '</span>' +
      '</div>';

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}