انتقال به «تکمیل خودکار جا» جدید

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

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

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

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

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

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

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

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

این بخش کد تکمیل خودکار را مقایسه می‌کند تا تفاوت‌های بین «خدمات مکان‌ها» و کلاس «مکان» را برای میاناهای برنامه‌نویسی نشان دهد.

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

«سرویس مکان‌های» قدیمی به شما امکان می‌دهد پیش‌بینی‌های تکمیل خودکار را به‌صورت برنامه‌نویسی‌شده بازیابی کنید تا کنترل بیشتری بر میانای کاربر نسبت‌به آنچه کلاس 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}`
}

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

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

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

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

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

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

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

  • سازنده ابزاره Autocomplete دو آرگومان می‌گیرد:
    • عنصر HTML input از نوع 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);
  });
}

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

کلاس «مکان» 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 ( event ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location", "viewport"],
    });
    // 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,
  });
}