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 neuen Place Autocomplete-Funktionen erläutert. In beiden Versionen gibt es zwei allgemeine Möglichkeiten, die automatische Vervollständigung zu integrieren:
- 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 der programmatischen Place Autocomplete-Funktion zwischen dem Places Autocomplete Service (alt) und der Autocomplete Data API (neu) aufgeführt:
PlacesService (alt) |
Place (neu) |
|---|---|
| Referenz zum Places Autocomplete Service | Referenz zu Autocomplete Data (neu) |
AutocompletionRequest |
AutocompleteRequest |
AutocompleteService.getPlacePredictions |
AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction |
PlacePrediction |
Für die Methoden muss ein Callback verwendet werden, um das Ergebnisobjekts und
PlacesServiceStatus Antwort zu verarbeiten. |
Verwendet Promises und funktioniert asynchron. |
Für die Methoden ist eine PlacesServiceStatus-Prüfung erforderlich. |
Keine Statusprüfung erforderlich, Standardfehlerbehandlung kann verwendet werden. Weitere Informationen. |
Die Felder für „Place“-Daten werden als Optionen festgelegt, wenn die Autocomplete
Instanz erstellt wird. |
Die Felder für „Place“-Daten werden später festgelegt, wenn fetchFields() aufgerufen wird. |
Abfragevorschläge werden unterstützt (nur SearchBox). |
Abfragevorschläge sind in der Autocomplete-Klasse nicht verfügbar. |
| Beschränkt auf eine feste Anzahl von Ortstypen und Feldern für „Place“-Daten. | Zugriff auf eine erweiterte Auswahl an Ortstypen und Feldern für „Place“-Daten. |
Die folgenden Elemente werden sowohl von den alten als auch von den neuen Autocomplete APIs verwendet:
Codevergleich (programmatisch)
In diesem Abschnitt wird Code für die automatische Vervollständigung verglichen, um die Unterschiede zwischen dem Places Service und der Place-Klasse für programmatische Schnittstellen zu veranschaulichen.
Automatische Vervollständigungen abrufen (alt)
Mit dem alten Places Service können Sie automatische Vervollständigungen programmatisch abrufen, um mehr Kontrolle über die Benutzeroberfläche zu haben, als mit der Autocomplete-Klasse möglich ist. Im folgenden Beispiel wird eine einzelne Anfrage für „par“ mit einer AutocompletionRequest gestellt, die den Eingabewert und eine Reihe von Grenzen zur Gewichtung der Vorhersage enthält. Das Beispiel
gibt eine Liste von
AutocompletePrediction
Instanzen zurück und zeigt die Beschreibung für jede Instanz. 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 automatische Vervollständigungen programmatisch abrufen, um mehr Kontrolle über die Benutzeroberfläche zu haben, als mit der PlaceAutocompleteElement-Klasse möglich ist. Im folgenden Beispiel wird eine einzelne Anfrage für „par“ mit einer AutocompleteRequest gestellt, die den Eingabewert und eine Reihe von Grenzen zur Gewichtung der Vorhersage enthält. Das Beispiel gibt eine Liste von placePrediction-Instanzen zurück und zeigt die Beschreibung für jede Instanz. 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 Place Autocomplete Data Predictions
- Beispiel für Place Autocomplete Data Sessions
- Sitzungstokens
- Referenz zur
AutocompleteRequestSchnittstelle - Referenz zur
AutocompleteSuggestionKlasse - Referenz zur
PlacePredictionKlasse
Place Autocomplete-Widget
In der folgenden Tabelle sind einige der wichtigsten Unterschiede bei der Verwendung von Autocomplete-Widgets zwischen dem Places Service (alt) und der Place-Klasse (neu) aufgeführt:
| Places Service (alt) | Place (neu) |
|---|---|
Autocomplete class
für Ortsvorschläge.
|
PlaceAutocompleteElement-Klasse
für Ortsvorschläge.
|
SearchBox Klassefür Abfragevorschläge. |
Abfragevorschläge sind in der Autocomplete-Klasse nicht verfügbar.
|
| Nur der Standardplatzhaltertext für die Eingabe wird lokalisiert. | Der Platzhalter für die Texteingabe, 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 einzugrenzen (zu gewichten), und
strictBounds , um die Ergebnisse auf die angegebenen
Grenzen zu beschränken.
|
Das Widget verwendet die locationBias
Eigenschaft, um die Ergebnisse auf die angegebenen Grenzen zu gewichten, und die locationRestriction
Eigenschaft, um die Suche auf die angegebenen Grenzen zu beschränken.
|
| Widgets können nur mit einem Standard-HTML-Eingabeelement eingebunden werden. | Das Widget kann mit einem Standard-HTML-Eingabeelement oder einem
gmp-place-autocomplete Element eingebunden werden. |
| Bei Verwendung des Widgets können Nutzer Dinge anfordern, die möglicherweise ungültig sind (z. B. „bisneyland“). Dieser Fall muss explizit behandelt werden. | Das Widget gibt nur Ergebnisse für die angegebenen Vorschläge zurück und kann keine Anfragen für beliebige Werte stellen. Daher ist es nicht erforderlich, potenziell ungültige Anfragen zu verarbeiten. |
Gibt eine alte
PlaceResult-Instanz zurück. |
Gibt eine
Place-Instanz zurück. |
Die Felder für „Place“-Daten werden als Optionen für das Autocomplete
Objekt festgelegt. |
Die Felder für „Place“-Daten werden festgelegt, wenn der Nutzer eine Auswahl trifft und
fetchFields() aufgerufen wird. |
| Beschränkt auf eine feste Anzahl von Ortstypen und Feldern für „Place“-Daten. | Zugriff auf eine erweiterte Auswahl an Ortstypen und Feldern für „Place“-Daten. |
Codevergleich (Widgets)
In diesem Abschnitt wird 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.
Place Autocomplete-Widget (alt)
Der Places Service bietet zwei Arten von Autocomplete-Widgets, die Sie mit den Klassen Autocomplete und SearchBox hinzufügen können.
Jede Art von Widget kann einer Karte als Kartensteuerelement hinzugefügt oder direkt in eine Webseite eingebettet werden. Das folgende Codebeispiel zeigt, wie ein Autocomplete-Widget als Kartensteuerelement eingebettet wird.
- Der Konstruktor des
Autocomplete-Widgets verwendet zwei Argumente:- Ein HTML-
input-Element vom Typtext. Das ist das Eingabefeld, das vom Dienst zur automatischen Vervollständigung überwacht wird und an das die Ergebnisse angehängt werden. - Ein optionales
AutocompleteOptionsArgument, mit dem Sie weitere Optionen angeben können, um die Abfrage einzuschränken.
- Ein HTML-
- Um Grenzen festzulegen, kann die
Autocomplete-Instanz explizit an die Karte gebunden werden, indem Sieautocomplete.bindTo()aufrufen. - Geben Sie die Felder für „Place“-Daten in den Optionen für die automatische Vervollständigung 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 Place Autocomplete-Widget
- Beispiel für das Suchfeld für Orte
- Referenz zur
AutocompleteKlasse
Place Autocomplete-Widget (neu)
Die Place-Klasse bietet das
PlaceAutocompleteElement,
eine HTMLElement Unterklasse, die eine UI-Komponente bereitstellt, die einer
Karte als Kartensteuerelement hinzugefügt oder direkt in eine Webseite eingebettet werden kann. Das folgende Codebeispiel zeigt, wie ein PlaceAutocompleteElement-Widget als Kartensteuerelement eingebettet wird.
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
PlaceAutocompleteElementbietet ein eigenes Eingabefeld und wird direkt mit HTML oder JavaScript in die Seite eingefügt (im Gegensatz dazu, dass ein vorhandenes Eingabeelement bereitgestellt wird). - Abfragevorschläge sind in der
AutocompleteKlasse nicht verfügbar. - Das
PlaceAutocompleteElementwird mitPlaceAutocompleteElementOptionserstellt.- Die Felder für „Place“-Daten werden bei der Auswahl angegeben (wenn
fetchFields()aufgerufen wird).
- Die Felder für „Place“-Daten 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 ( place ) => {
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,
});
}
- Dokumentation zum Place Autocomplete-Widget (Vorabversion)
- Beispiel für das Place Autocomplete-Widget
- Beispiel für das Place Autocomplete-Element
- Referenz zur
PlaceAutocompleteElementKlasse