Place Autocomplete ist eine Funktion der Places Library in der Maps JavaScript API. Mit der automatischen Vervollständigung erhalten Sie in Ihren Anwendungen dasselbe Vervollständigungsverhalten bei Suchen wie im Suchfeld von Google Maps.
Auf dieser Seite werden die Unterschiede zwischen den alten und den neuen Place Autocomplete-Funktionen erläutert. In beiden Versionen gibt es zwei allgemeine Möglichkeiten, die automatische Vervollständigung einzubinden:
- Programmatische Schnittstelle: Für Entwickler, die mehr Anpassungsmöglichkeiten und Kontrolle über die automatische Vervollständigung wünschen.
- Place Autocomplete-Widget: Eine Suchleiste, die in eine Karte oder Webseite eingebettet werden kann.
Programmatische Schnittstelle für die automatische Vervollständigung
In der folgenden Tabelle sind einige der wichtigsten Unterschiede bei der Verwendung des programmatischen Place Autocomplete zwischen dem Place Autocomplete-Dienst (Legacy) und der Autocomplete Data API (neu) aufgeführt:
PlacesService (alt) |
Place (neu) |
|---|---|
| Referenz für den „Place Autocomplete“-Dienst | Autocomplete Data (New)-Referenz |
AutocompletionRequest |
AutocompleteRequest |
AutocompleteService.getPlacePredictions |
AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction |
PlacePrediction |
Für Methoden ist ein Callback erforderlich, um das Ergebnisobjekt und die PlacesServiceStatus-Antwort zu verarbeiten. |
Verwendet Promises und funktioniert asynchron. |
Methoden erfordern eine PlacesServiceStatus-Prüfung. |
Keine Statusprüfung erforderlich, Standardfehlerbehandlung kann verwendet werden. Weitere Informationen |
Felder für Ortsdaten werden als Optionen festgelegt, wenn die Autocomplete-Instanz erstellt wird. |
Die Datenfelder für „Place“ werden später beim Aufruf von fetchFields() festgelegt. |
Abfragevervollständigungen werden unterstützt (nur SearchBox). |
Abfragevervollständigungen sind in der Klasse Autocomplete nicht verfügbar. |
| Beschränkt auf eine feste Gruppe von Ortstypen und Ortsdatenfeldern. | Zugriff auf eine erweiterte Auswahl an Orttypen und Ortsdatenfeldern. |
Die folgenden werden sowohl von der alten als auch von der neuen Autocomplete API verwendet:
Codevergleich (programmatisch)
In diesem Abschnitt wird Code für die automatische Vervollständigung verglichen, um die Unterschiede zwischen dem Places Service und der Klasse „Place“ für programmatische Schnittstellen zu veranschaulichen.
Automatische Vervollständigungen abrufen (Legacy)
Mit dem alten Places Service können Sie Vorschläge für die automatische Vervollständigung programmatisch abrufen. So haben Sie mehr Kontrolle über die Benutzeroberfläche, als die Klasse Autocomplete bietet. Im folgenden Beispiel wird eine einzelne Anfrage für „par“ gestellt, wobei ein AutocompletionRequest aus dem Eingabewert und einer Reihe von Grenzen besteht, um die Vervollständigung zu beeinflussen. Im Beispiel wird eine Liste von AutocompletePrediction-Instanzen zurückgegeben und die Beschreibung für jede Instanz angezeigt. Die Beispielfunktion erstellt auch ein Sitzungstoken und wendet es auf die Anfrage an.
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);
}
- Vorschläge des „Place Autocomplete“-Dienstes programmatisch abrufen
- Beispiel für „Place Autocomplete“
- Sitzungstokens
- Referenz zu
AutocompletionRequest - Referenz zu
AutocompletePrediction
Automatische Vervollständigungen abrufen (neu)
Mit der neuen Place-Klasse können Sie auch programmatisch automatische Vervollständigung abrufen, um mehr Kontrolle über die Benutzeroberfläche zu haben, als die Klasse PlaceAutocompleteElement bietet. Im folgenden Beispiel wird eine einzelne Anfrage für „par“ gestellt, wobei ein AutocompleteRequest-Objekt aus dem Eingabewert und einer Reihe von Grenzen besteht, um die Vervollständigung zu beeinflussen. Im Beispiel wird eine Liste von placePrediction-Instanzen zurückgegeben und die Beschreibung für jede Instanz angezeigt. Die Beispielfunktion erstellt auch ein Sitzungstoken und wendet es auf die Anfrage an.
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
- Beispiel für Datenprognosen mit Place Autocomplete
- Beispiel für Place Autocomplete-Datensitzungen
- Sitzungstokens
AutocompleteRequest-SchnittstellenreferenzAutocompleteSuggestion-KlassenreferenzPlacePrediction-Klassenreferenz
Widget für Place Autocomplete
In der folgenden Tabelle sind einige der wichtigsten Unterschiede bei der Verwendung von Autocomplete-Widgets zwischen dem Places-Dienst (Legacy) und der Place-Klasse (neu) aufgeführt:
| Places Service (Legacy) | Place (Neu) |
|---|---|
Autocomplete-Klasse für Ortsvorschläge.
|
PlaceAutocompleteElement-Klasse für Ortsvorschläge.
|
SearchBox-Klassefür Abfragevorhersagen. |
Abfragevervollständigungen sind in der Klasse Autocomplete nicht verfügbar.
|
| Nur der Standardplatzhaltertext für die Eingabe wird lokalisiert. | Der Texteingabeplatzhalter, das Logo der Liste mit Vorschlägen und die Ortsvorschläge unterstützen die regionale Lokalisierung. |
Das Widget verwendet setBounds() oder autocomplete.bindTo(), um die Suche auf die angegebenen Grenzen zu beschränken (Bias), und strictBounds, um die Ergebnisse auf die angegebenen Grenzen zu beschränken.
|
Das Widget verwendet das Attribut locationBias, um die Ergebnisse auf die angegebenen Grenzen zu gewichten, und das Attribut locationRestriction, um die Suche auf die angegebenen Grenzen zu beschränken.
|
| Widgets können nur über ein Standard-HTML-Eingabeelement eingebunden werden. | Das Widget kann über ein Standard-HTML-Eingabeelement oder ein gmp-place-autocomplete-Element eingebunden werden. |
| Bei der Verwendung des Widgets können Nutzer Dinge anfordern, die möglicherweise nicht gültig sind (z. B. „bisneyland“). Dieser Fall muss explizit behandelt werden. | Das Widget gibt nur Ergebnisse für die bereitgestellten Vorschläge zurück und kann keine Anfragen für beliebige Werte senden. Daher müssen potenziell ungültige Anfragen nicht verarbeitet werden. |
Gibt eine Legacy-PlaceResult-Instanz zurück. |
Gibt eine Place-Instanz zurück. |
Felder für Ortsdaten werden als Optionen für das Objekt Autocomplete festgelegt. |
Ortsdatenfelder werden festgelegt, wenn der Nutzer eine Auswahl trifft und fetchFields() aufgerufen wird. |
| Beschränkt auf eine feste Gruppe von Ortstypen und Ortsdatenfeldern. | Zugriff auf eine erweiterte Auswahl an Ortstypen und Ortsdatenfeldern. |
Codevergleich (Widgets)
In diesem Abschnitt wird der Code für die automatische Vervollständigung verglichen, um die Unterschiede zwischen dem alten „Place Autocomplete“-Widget und dem neuen „Place Autocomplete“-Element zu veranschaulichen.
Widget für Place Autocomplete (Legacy)
Der Places-Dienst bietet zwei Arten von Widgets zur automatischen Vervollständigung, die Sie über die Klassen Autocomplete und SearchBox hinzufügen können.
Jede Art von Widget kann einer Karte als Steuerelement hinzugefügt oder direkt in eine Webseite eingebettet werden. Im folgenden Codebeispiel wird ein Autocomplete-Widget als Kartensteuerelement eingebettet.
- Der Konstruktor des Widgets
Autocompleteverwendet zwei Argumente:- Ein HTML-
input-Element des Typstext. Das ist das Eingabefeld, das vom Dienst zur automatischen Vervollständigung überwacht wird und an das die Ergebnisse angehängt werden. - Ein optionales
AutocompleteOptions-Argument, mit dem Sie weitere Optionen zum Einschränken der Abfrage angeben können.
- Ein HTML-
- Wenn Sie Grenzen festlegen möchten, können Sie die
Autocomplete-Instanz explizit an die Karte binden, indem Sieautocomplete.bindTo()aufrufen. - Geben Sie in den Optionen für die automatische Vervollständigung Ortsdatenfelder an.
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);
});
}
- Dokumentation zu Place Autocomplete
- Beispiel für das Widget „Place Autocomplete“
- Beispiel für ein Suchfeld für Orte
Autocomplete-Klassenreferenz
Widget für Place Autocomplete (neu)
Die Klasse „Place“ bietet PlaceAutocompleteElement, eine Unterklasse von HTMLElement, die eine UI-Komponente bereitstellt, die einer Karte als Kartensteuerelement hinzugefügt oder direkt in eine Webseite eingebettet werden kann. Im folgenden Codebeispiel wird ein PlaceAutocompleteElement-Widget als Kartensteuerelement eingebettet.
Das „Place Autocomplete“-Widget wurde in den folgenden Bereichen optimiert:
- Die Benutzeroberfläche des Autocomplete-Widgets unterstützt die regionale Lokalisierung (einschließlich RTL-Sprachen) für den Texteingabeplatzhalter, das Logo der Liste mit Vorschlägen und die Ortsvorschläge.
- Die Bedienungshilfen wurden weiter verbessert, einschließlich Unterstützung für Screenreader und Tastaturinteraktionen.
- Das Autocomplete-Widget gibt die neue
Place-Klasse zurück, um die Verarbeitung des zurückgegebenen Objekts zu vereinfachen. - Bessere Unterstützung für Mobilgeräte und kleine Bildschirme.
- Bessere Leistung und grafische Darstellung.
Wichtige Unterschiede bei der Implementierung:
- Das
PlaceAutocompleteElementstellt ein eigenes Eingabefeld bereit und wird direkt über HTML oder JavaScript in die Seite eingefügt (im Gegensatz zur Bereitstellung eines vorhandenen Eingabeelements). - Abfragevorhersagen sind in der Klasse
Autocompletenicht verfügbar. - Der
PlaceAutocompleteElementwird mitPlaceAutocompleteElementOptionserstellt.- Ortsdatenfelder werden bei der Auswahl angegeben (wenn
fetchFields()aufgerufen wird).
- Ortsdatenfelder werden bei der Auswahl angegeben (wenn
- Legen Sie Grenzen mit der Option
locationBoundsoderlocationRestrictionfest.
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,
});
}