Place Autocomplete adalah fitur Places Library di Maps JavaScript API. Anda dapat menggunakan Autocomplete 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, ada dua cara umum untuk mengintegrasikan Autocomplete:
- Antarmuka terprogram: Untuk developer yang menginginkan penyesuaian dan kontrol yang lebih besar atas pengalaman pelengkapan otomatis.
- Widget Place Autocomplete: Kotak penelusuran yang dapat disematkan di peta atau halaman web.
Antarmuka terprogram pelengkapan otomatis
Tabel berikut mencantumkan beberapa perbedaan utama dalam penggunaan Place Autocomplete terprogram antara Layanan Place Autocomplete (lama) dan Autocomplete Data API (baru):
PlacesService (Lama) |
Place (Baru) |
|---|---|
| Referensi Layanan Place Autocomplete | Referensi Autocomplete Data (baru) |
AutocompletionRequest |
AutocompleteRequest |
AutocompleteService.getPlacePredictions |
AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction |
PlacePrediction |
Metode memerlukan penggunaan callback untuk menangani objek hasil dan
PlacesServiceStatus respons. |
Menggunakan Promise, dan berfungsi secara asinkron. |
Metode memerlukan pemeriksaan PlacesServiceStatus. |
Tidak ada pemeriksaan status yang diperlukan, dapat menggunakan penanganan error standar. Pelajari lebih lanjut. |
Kolom data tempat ditetapkan sebagai opsi saat Autocomplete
instance dibuat. |
Kolom data tempat ditetapkan nanti saat fetchFields() dipanggil. |
Prediksi kueri didukung (hanya SearchBox). |
Prediksi kueri tidak tersedia di class Autocomplete. |
| Terbatas pada kumpulan tetap jenis tempat dan kolom data tempat. | Akses ke pilihan jenis tempat dan kolom data tempat yang diperluas. |
Berikut 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 memengaruhi prediksi. Contoh ini menampilkan daftar instance, dan menunjukkan deskripsi untuk setiap instance.AutocompletePrediction 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 Layanan Place Autocomplete secara terprogram
- Contoh Place Autocomplete
- Token sesi
- Referensi
AutocompletionRequest - Referensi
AutocompletePrediction
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 memengaruhi prediksi. Contoh ini menampilkan daftar instance placePrediction dan menunjukkan 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}`
}
- Place Autocomplete Data API
- Contoh Prediksi Data Place Autocomplete
- Contoh Sesi Data Place Autocomplete
- Token sesi
- Referensi antarmuka
AutocompleteRequest - Referensi class
AutocompleteSuggestion - Referensi class
PlacePrediction
Widget pelengkapan otomatis tempat
Tabel berikut mencantumkan beberapa perbedaan utama dalam penggunaan widget pelengkapan otomatis antara Layanan Places (lama) dan class Place (baru):
| Layanan Places (Lama) | Place (Baru) |
|---|---|
Autocomplete class
untuk prediksi tempat.
|
PlaceAutocompleteElement class
untuk prediksi tempat.
|
SearchBox kelasuntuk 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 uses
setBounds() or autocomplete.bindTo()
to constrain (bias) the search to the specified bounds, and
strictBounds to restrict results to the specified
bounds.
|
Widget uses the locationBias
property to bias results to the specified bounds, and the locationRestriction
property to restrict the search to the specified bounds.
|
| 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; oleh karena itu, tidak perlu menangani permintaan yang berpotribusi tidak valid. |
Menampilkan instance
PlaceResult lama. |
Menampilkan
Place instance. |
Kolom data tempat ditetapkan sebagai opsi untuk objek Autocomplete. |
Kolom data tempat ditetapkan saat pengguna membuat pilihan dan
fetchFields() dipanggil. |
| Terbatas pada 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 pelengkapan otomatis, 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 cara menyematkan widget Autocomplete sebagai kontrol peta.
- Konstruktor widget
Autocompletemenggunakan dua argumen:- Elemen
inputHTML dari jenistext. Ini adalah kolom input yang akan dipantau oleh layanan pelengkapan otomatis dan untuk melampirkan hasilnya. - Argumen
AutocompleteOptionsopsional, tempat Anda dapat menentukan opsi lebih lanjut untuk membatasi kueri.
- Elemen
- Untuk menetapkan batas, instance
Autocompletedapat terikat secara eksplisit ke peta dengan memanggilautocomplete.bindTo(). - Tentukan kolom data tempat dalam 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);
});
}
- Dokumentasi Place Autocomplete
- Contoh Widget Place Autocomplete
- Contoh Kotak Penelusuran Places
- Referensi class
Autocomplete
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 cara menyematkan 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 dioptimalkan, termasuk dukungan untuk pembaca layar dan interaksi keyboard.
- Widget Autocomplete menampilkan class
Placebaru untuk menyederhanakan penanganan objek yang ditampilkan. - Dukungan yang lebih baik untuk perangkat seluler dan layar kecil.
- Performa dan tampilan grafis yang lebih baik.
Perbedaan utama dalam penerapan meliputi:
PlaceAutocompleteElementmenyediakan kolom inputnya sendiri, dan langsung dimasukkan ke halaman menggunakan HTML atau JavaScript (bukan disediakan elemen input yang ada).- Prediksi kueri tidak tersedia di
Autocompleteclass. PlaceAutocompleteElementdibuat menggunakanPlaceAutocompleteElementOptions.- Kolom data tempat ditentukan pada waktu pemilihan (saat
fetchFields()dipanggil).
- Kolom data tempat ditentukan pada waktu pemilihan (saat
- Tetapkan batas menggunakan opsi
locationBoundsataulocationRestriction.
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"],
});
// 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,
});
}
- Dokumentasi Widget Place Autocomplete (Pratinjau)
- Contoh widget Place Autocomplete
- Contoh Elemen Place Autocomplete
- Referensi class
PlaceAutocompleteElement