Zum neuen Place Autocomplete migrieren

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 „Places Autocomplete“-Funktionen erläutert. In beiden Versionen gibt es zwei allgemeine Möglichkeiten, die automatische Vervollständigung zu integrieren:

• Programmierbare Schnittstelle: Für Entwickler, die die automatische Vervollständigung stärker anpassen und steuern möchten.
• Place Autocomplete-Widget: Eine Suchleiste, die in eine Karte oder Webseite eingebettet werden kann.

Programmatische Benutzeroberfläche für die automatische Vervollständigung

In der folgenden Tabelle sind einige der Hauptunterschiede bei der Verwendung von programmatischem Place Autocomplete zwischen dem Places Autocomplete-Dienst (alt) und der Autocomplete Data API (neu) aufgeführt:

PlacesService (alt)	Place (neu)
Referenz zum Places Autocomplete-Dienst	Referenz zu Autocomplete-Daten (neu)
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.
Für Methoden ist eine PlacesServiceStatus-Prüfung erforderlich.	Keine Statusprüfung erforderlich, Standardfehlerbehandlung kann verwendet werden.
Die Felder für Ortsdaten werden beim Erstellen der Autocomplete-Instanz als Optionen festgelegt.	Felder für „Place“-Daten werden später beim Aufruf von fetchFields() festgelegt.
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 Ortsdatenfeldern.	Zugriff auf eine erweiterte Auswahl an Ortstypen und Feldern für Ortsdaten

Die folgenden Parameter werden sowohl von der alten als auch von der neuen Autocomplete API verwendet:

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

Codevergleich (programmatisch)

In diesem Abschnitt wird Code für die automatische Vervollständigung verglichen, um die Unterschiede zwischen dem Places-Dienst und der Place-Klasse für programmatische Schnittstellen zu veranschaulichen.

Automatische Vervollständigungen abrufen (alt)

Mit dem bisherigen Places-Dienst können Sie Vorschläge für die automatische Vervollständigung programmatisch abrufen. So haben Sie mehr Kontrolle über die Benutzeroberfläche als mit der Klasse Autocomplete. Im folgenden Beispiel wird eine einzelne Anfrage für „par“ mit einem AutocompletionRequest gestellt, das aus dem Eingabewert und einer Reihe von Grenzwerten besteht, um die Vorhersage zu beeinflussen. Im Beispiel wird eine Liste von AutocompletePrediction-Instanzen zurückgegeben und die Beschreibung für jede Instanz angezeigt. Die Beispielfunktion erstellt außerdem 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 automatisch vervollständigte Vorschläge programmatisch abrufen, um die Benutzeroberfläche besser zu steuern als mit der PlaceAutocompleteElement-Klasse. Im folgenden Beispiel wird eine einzelne Anfrage für „par“ mit einem AutocompleteRequest gesendet, das aus dem Eingabewert und einer Reihe von Grenzwerten zur Voreinnahme der Vorhersage besteht. Im Beispiel wird eine Liste von placePrediction-Instanzen zurückgegeben und die Beschreibung für jede Instanz angezeigt. Die Beispielfunktion erstellt außerdem 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 Datenvorhersagen mit Place Autocomplete
• Beispiel für Datensitzungen von Place Autocomplete
• Sitzungstokens
• AutocompleteRequest-Referenz
• AutocompleteSuggestion-Klassenreferenz
• PlacePrediction-Klassenreferenz

Widget für Place Autocomplete

In der folgenden Tabelle sind einige der Hauptunterschiede bei der Verwendung von Autocomplete-Widgets zwischen dem Google Places-Dienst (alte Version) und der Place-Klasse (neue Version) aufgeführt:

Places Service (Legacy)	Ort (neu)
Autocomplete-Klasse für Ortsvorschläge.	PlaceAutocompleteElement-Klasse für Ortsvorschläge.
SearchBox-Klasse für Abfragevorhersagen.	Abfragevorschläge sind in der Autocomplete-Klasse 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.
Im Widget wird setBounds() oder autocomplete.bindTo() verwendet, um die Suche auf die angegebenen Grenzen einzugrenzen (zu beeinflussen), und strictBounds, um die Ergebnisse auf die angegebenen Grenzen einzuschränken.	Im Widget wird das Attribut locationBias verwendet, um die Ergebnisse auf die angegebenen Grenzen auszurichten, und das Attribut locationRestriction, um die Suche auf die angegebenen Grenzen einzugrenzen.
Widgets können nur mit einem standardmäßigen HTML-Eingabeelement eingebunden werden.	Das Widget kann über ein standardmäßiges HTML-Eingabeelement oder ein gmp-place-autocomplete-Element eingebunden werden.
Bei der Verwendung des Widgets können Nutzer möglicherweise ungültige Suchanfragen stellen (z. B. „bisneyland“). Dieser Fall muss ausdrücklich behandelt werden.	Das Widget gibt nur Ergebnisse für die angegebenen Vorschläge zurück und kann keine Anfragen für beliebige Werte senden. Daher müssen potenziell ungültige Anfragen nicht verarbeitet werden.
Gibt die Legacy-Instanz PlaceResult zurück.	Gibt eine Instanz von Place zurück.
Felder für „Place“-Daten werden als Optionen für das Autocomplete-Objekt festgelegt.	Ortsdatenfelder werden festgelegt, wenn der Nutzer eine Auswahl trifft und fetchFields() aufgerufen wird.
Beschränkt auf eine feste Anzahl von Ortstypen und Ortsdatenfeldern.	Zugriff auf eine erweiterte Auswahl an Ortstypen und Feldern für Ortsdaten

Codevergleich (Widgets)

In diesem Abschnitt wird der Code für die automatische Vervollständigung verglichen, um die Unterschiede zwischen dem bisherigen Place Autocomplete-Widget und dem neuen Place Autocomplete-Element zu veranschaulichen.

Place Autocomplete-Widget (alt)

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 Kartenkontrollelement hinzugefügt oder direkt in eine Webseite eingebettet werden. Im folgenden Codebeispiel wird ein Autocomplete-Widget als Kartenkontrollelement eingebettet.

• Der Konstruktor des Autocomplete-Widgets verwendet zwei Argumente:
  • Ein HTML-input-Element des Typs text. Das ist das Eingabefeld, das vom Dienst zur automatischen Vervollständigung überwacht wird und an das die Ergebnisse angehängt werden.
  • Optionales AutocompleteOptions-Argument, mit dem Sie weitere Optionen angeben können, um die Abfrage einzuschränken.
• Um Grenzen festzulegen, kann die Autocomplete-Instanz durch Aufrufen von autocomplete.bindTo() explizit an die Karte gebunden werden.
• Geben Sie in den Optionen für die automatische Vervollständigung Felder für Ortsdaten 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);
  });
}

• Place Autocomplete-Dokumentation
• Beispiel für ein Place Autocomplete-Widget
• Beispiel für ein Suchfeld für Orte
• Autocomplete-Klassenreferenz

Place Autocomplete-Widget (neu)

Die „Place“-Klasse bietet die PlaceAutocompleteElement, eine HTMLElement-Unterklasse, die eine UI-Komponente bereitstellt, die einer Karte als Kartenkontrollelement 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.

Zu den wichtigsten Implementierungsunterschieden gehören:

• Abfragevorschläge sind in der Klasse Autocomplete nicht verfügbar.
• PlaceAutocompleteElement wird mit PlaceAutocompleteElementOptions erstellt.
• Felder für „Place“-Daten werden bei der Auswahl (beim Aufrufen von fetchFields()) angegeben.
• Legen Sie Grenzen mit der Option locationBounds oder locationRestriction fest.
• Verknüpfe PlaceAutocompleteElement mit einem HTML-Texteingabeelement. Verwende dazu das Attribut id, das von HTMLElement übernommen wird.

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

• Dokumentation zum Widget für Place Autocomplete (Vorabversion)
• Beispiel für ein Place Autocomplete-Widget
• Beispiel für das Place Autocomplete-Element
• PlaceAutocompleteElement-Klassenreferenz