Bermigrasi ke Place Autocomplete baru

Place Autocomplete adalah fitur Places Library di Maps JavaScript API. Anda dapat menggunakan pelengkapan otomatis untuk memberi aplikasi Anda perilaku prediksi penelusuran di kolom penelusuran Google Maps.

Halaman ini menjelaskan perbedaan antara fitur Place Autocomplete lama dan baru. Di kedua versi tersebut, ada dua cara umum untuk mengintegrasikan Autocomplete:

Antarmuka terprogram Autocomplete

Tabel berikut mencantumkan beberapa perbedaan utama dalam penggunaan Pelengkapan Otomatis Tempat terprogram antara Layanan Pelengkapan Otomatis Tempat (lama) dan Autocomplete Data API (baru):

PlacesService (Lama) Place (Baru)
Referensi Layanan Place Autocomplete Referensi Data Autocomplete (baru)
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
Metode memerlukan penggunaan callback untuk menangani objek hasil dan respons PlacesServiceStatus. Menggunakan Promise, dan berfungsi secara asinkron.
Metode memerlukan pemeriksaan PlacesServiceStatus. Tidak diperlukan pemeriksaan status, dapat menggunakan penanganan error standar.
Kolom data tempat ditetapkan sebagai opsi saat instance Autocomplete dibuat. Kolom data tempat ditetapkan nanti saat fetchFields() dipanggil.
Prediksi kueri didukung (khusus SearchBox). Prediksi kueri tidak tersedia di class Autocomplete.
Dibatasi untuk kumpulan tetap jenis tempat dan kolom data tempat. Akses ke pilihan jenis tempat dan kolom data tempat yang diperluas.

Berikut adalah API yang digunakan oleh Autocomplete API lama dan baru:

Perbandingan kode (terprogram)

Bagian ini membandingkan kode untuk pelengkapan otomatis guna mengilustrasikan perbedaan antara layanan Places dan class Place, untuk antarmuka terprogram.

Mengambil prediksi pelengkapan otomatis (lama)

Layanan Places lama memungkinkan Anda mengambil prediksi pelengkapan otomatis secara terprogram, untuk kontrol yang lebih besar atas antarmuka pengguna daripada yang ditawarkan oleh class Autocomplete. Dalam contoh berikut, satu permintaan dibuat untuk "par", dengan AutocompletionRequest yang terdiri dari nilai input dan kumpulan batas untuk membiaskan prediksi. Contoh ini menampilkan daftar instance AutocompletePrediction, dan menampilkan deskripsi untuk setiap instance. Fungsi contoh juga membuat token sesi dan menerapkannya ke permintaan.

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);
}

Mengambil prediksi pelengkapan otomatis (baru)

Class Place baru juga memungkinkan Anda mengambil prediksi pelengkapan otomatis secara terprogram untuk kontrol yang lebih besar atas antarmuka pengguna daripada yang ditawarkan oleh class PlaceAutocompleteElement. Dalam contoh berikut, satu permintaan dibuat untuk "par", dengan AutocompleteRequest yang terdiri dari nilai input dan kumpulan batas untuk membiaskan prediksi. Contoh ini menampilkan daftar instance placePrediction dan menampilkan deskripsi untuk setiap instance. Fungsi contoh juga membuat token sesi dan menerapkannya ke permintaan.

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}`
}

Widget Place Autocomplete

Tabel berikut mencantumkan beberapa perbedaan utama dalam penggunaan widget pelengkapan otomatis antara layanan Places (lama), dan class Place (baru):

Layanan Places (Lama) Tempat (Baru)
Class Autocomplete untuk prediksi tempat. Class PlaceAutocompleteElement untuk prediksi tempat.
Class SearchBox
untuk prediksi kueri. 		Prediksi kueri tidak tersedia di class Autocomplete.
Hanya teks placeholder input default yang dilokalkan. Placeholder input teks, logo daftar prediksi, dan prediksi tempat semuanya mendukung pelokalan regional.
Widget menggunakan setBounds() atau autocomplete.bindTo() untuk membatasi (bias) penelusuran ke batas yang ditentukan, dan strictBounds untuk membatasi hasil ke batas yang ditentukan. Widget menggunakan properti locationBias untuk membiaskan hasil ke batas yang ditentukan, dan properti locationRestriction untuk membatasi penelusuran ke batas yang ditentukan.
Widget hanya dapat diintegrasikan menggunakan elemen input HTML standar. Widget dapat diintegrasikan menggunakan elemen input HTML standar atau elemen gmp-place-autocomplete.
Saat menggunakan widget, pengguna dapat meminta hal-hal yang mungkin tidak valid (misalnya "bisneyland"); kasus ini harus ditangani secara eksplisit. Widget hanya akan menampilkan hasil untuk saran yang diberikan, dan tidak dapat mengeluarkan permintaan untuk nilai arbitrer; sehingga tidak perlu menangani permintaan yang berpotensi tidak valid.
Menampilkan instance PlaceResult lama. Menampilkan instance Place.
Kolom data tempat ditetapkan sebagai opsi untuk objek Autocomplete. Kolom data tempat ditetapkan saat pengguna membuat pilihan dan fetchFields() dipanggil.
Dibatasi untuk kumpulan tetap jenis tempat dan kolom data tempat. Akses ke pilihan jenis tempat dan kolom data tempat yang diperluas.

Perbandingan kode (widget)

Bagian ini membandingkan kode untuk pelengkapan otomatis guna mengilustrasikan perbedaan antara Widget Place Autocomplete lama dan elemen Place Autocomplete baru.

Widget Place Autocomplete (lama)

Layanan Places menawarkan dua jenis widget autocomplete, yang dapat Anda tambahkan menggunakan class Autocomplete dan SearchBox. Setiap jenis widget dapat ditambahkan ke peta sebagai kontrol peta, atau disematkan langsung ke halaman web. Contoh kode berikut menunjukkan penyematan widget Autocomplete sebagai kontrol peta.

  • Konstruktor widget Autocomplete menggunakan dua argumen:
    • Elemen input HTML dari jenis text. Ini adalah kolom input yang akan dipantau oleh layanan pelengkapan otomatis dan untuk melampirkan hasilnya.
    • Argumen AutocompleteOptions opsional, tempat Anda dapat menentukan opsi lebih lanjut untuk membatasi kueri.
  • Untuk menetapkan batas, instance Autocomplete dapat secara eksplisit terikat ke peta dengan memanggil autocomplete.bindTo().
  • Tentukan kolom data tempat di opsi untuk pelengkapan otomatis.
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);
  });
}

Widget Place Autocomplete (Baru)

Class Place menawarkan PlaceAutocompleteElement, subclass HTMLElement yang menyediakan komponen UI yang dapat ditambahkan ke peta sebagai kontrol peta, atau disematkan langsung ke halaman web. Contoh kode berikut menunjukkan penyematan widget PlaceAutocompleteElement sebagai kontrol peta.

Widget Place Autocomplete telah ditingkatkan dengan cara berikut:

  • UI widget Autocomplete mendukung pelokalan regional (termasuk bahasa RTL), untuk placeholder input teks, logo daftar prediksi, dan prediksi tempat.
  • Aksesibilitas yang ditingkatkan, termasuk dukungan untuk pembaca layar dan interaksi keyboard.
  • Widget Autocomplete menampilkan class Place baru untuk menyederhanakan penanganan objek yang ditampilkan.
  • Dukungan yang lebih baik untuk perangkat seluler dan layar kecil.
  • Performa dan tampilan grafis yang lebih baik.

Perbedaan penerapan utamanya meliputi:

  • Prediksi kueri tidak tersedia di class Autocomplete.
  • PlaceAutocompleteElement dibuat menggunakan PlaceAutocompleteElementOptions.
  • Kolom data tempat ditentukan pada waktu pemilihan (saat fetchFields() dipanggil).
  • Tetapkan batas menggunakan opsi locationBounds atau locationRestriction.
  • Kaitkan PlaceAutocompleteElement dengan elemen input teks HTML dengan menggunakan atribut id (diwarisi dari HTMLElement).
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,
  });
}