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

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

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

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

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

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

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

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

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

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

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

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 را برمی‌گرداند و شرح هر یک را نشان می‌دهد. تابع مثال همچنین یک نشانه جلسه ایجاد می کند و آن را به درخواست اعمال می کند.

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 برمی گرداند.
فیلدهای داده مکان به عنوان گزینه برای شی Autocomplete تنظیم می شوند. فیلدهای داده مکان زمانی تنظیم می شوند که کاربر یک انتخاب انجام می دهد و fetchFields() فراخوانی می شود.
محدود به مجموعه ثابتی از انواع مکان و فیلدهای داده مکان . دسترسی به مجموعه گسترده ای از انواع مکان و فیلدهای داده مکان .

مقایسه کد (ویجت ها)

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

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

سرویس Places دو نوع ویجت تکمیل خودکار را ارائه می دهد که می توانید با استفاده از کلاس های 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 که یک مؤلفه UI را ارائه می دهد که می تواند به عنوان کنترل نقشه به نقشه اضافه شود یا مستقیماً در یک صفحه وب جاسازی شود. مثال کد زیر تعبیه یک ویجت PlaceAutocompleteElement را به عنوان کنترل نقشه نشان می دهد.

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

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

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

  • پیش‌بینی‌های پرس و جو در کلاس Autocomplete در دسترس نیستند.
  • PlaceAutocompleteElement با استفاده از PlaceAutocompleteElementOptions ساخته شده است.
  • فیلدهای داده مکان در زمان انتخاب مشخص می شوند (زمانی که fetchFields() فراخوانی می شود.
  • با استفاده از گزینه locationBounds یا locationRestriction محدوده ها را تنظیم کنید.
  • با استفاده از ویژگی id (به ارث رسیده از HTMLElement ) PlaceAutocompleteElement با یک عنصر ورودی متن HTML مرتبط کنید. 
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-placeselect listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
    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,
  });
}
،

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

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

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

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

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

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

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

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

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

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

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 را برمی‌گرداند و شرح هر یک را نشان می‌دهد. تابع مثال همچنین یک نشانه جلسه ایجاد می کند و آن را به درخواست اعمال می کند.

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 برمی گرداند.
فیلدهای داده مکان به عنوان گزینه برای شی Autocomplete تنظیم می شوند. فیلدهای داده مکان زمانی تنظیم می شوند که کاربر یک انتخاب انجام می دهد و fetchFields() فراخوانی می شود.
محدود به مجموعه ثابتی از انواع مکان و فیلدهای داده مکان . دسترسی به مجموعه گسترده ای از انواع مکان و فیلدهای داده مکان .

مقایسه کد (ویجت ها)

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

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

سرویس Places دو نوع ویجت تکمیل خودکار را ارائه می دهد که می توانید با استفاده از کلاس های 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 که یک مؤلفه UI را ارائه می دهد که می تواند به عنوان کنترل نقشه به نقشه اضافه شود یا مستقیماً در یک صفحه وب جاسازی شود. مثال کد زیر تعبیه یک ویجت PlaceAutocompleteElement را به عنوان کنترل نقشه نشان می دهد.

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

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

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

  • پیش‌بینی‌های پرس و جو در کلاس Autocomplete در دسترس نیستند.
  • PlaceAutocompleteElement با استفاده از PlaceAutocompleteElementOptions ساخته شده است.
  • فیلدهای داده مکان در زمان انتخاب مشخص می شوند (زمانی که fetchFields() فراخوانی می شود.
  • با استفاده از گزینه locationBounds یا locationRestriction محدوده ها را تنظیم کنید.
  • با استفاده از ویژگی id (به ارث رسیده از HTMLElement ) PlaceAutocompleteElement با یک عنصر ورودی متن HTML مرتبط کنید. 
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-placeselect listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
    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,
  });
}