Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Places UI Kit für bestehende Places API-Nutzer verwenden

Hier erfahren Sie, wie Sie Ihre vorhandene Places API- oder Place-Klassen-Implementierung zu den Places UI Kit-Komponenten migrieren.

Für wen ist dieses Handbuch gedacht?

Dieser Leitfaden richtet sich an Entwickler, die bereits eine Implementierung mit der Places API haben und ihren Code aktualisieren möchten, um das Places UI Kit zu verwenden. Am hilfreichsten ist es, wenn Sie bereits:

HTTP-Anfragen an Endpunkte der Places API (neue oder alte Version) stellen
Verwendung der Place-Klasse in der Maps JavaScript API
Verarbeiten der API-Antwort, um Ortsinformationen in der Benutzeroberfläche Ihrer Webanwendung zu rendern.

Vorbereitung

Aktivieren Sie das Places UI Kit in Ihrem Google Cloud-Projekt. Sie können Ihren vorhandenen API-Schlüssel weiterhin verwenden oder einen neuen für das Places UI Kit generieren. Weitere Informationen, auch zum Einschränken eines Schlüssels, finden Sie unter API-Schlüssel verwenden.

Laden der Maps JavaScript API aktualisieren

Für das Places UI Kit ist die Methode Dynamic Library Import zum Laden der Maps JavaScript API erforderlich. Wenn Sie das Tag zum direkten Laden von Scripts verwenden, muss dieses aktualisiert werden.

Nachdem Sie das Ladeskript für die Maps JavaScript API aktualisiert haben, importieren Sie die erforderlichen Bibliotheken, um das Places UI Kit zu verwenden.

Place Details-Element implementieren

Das Place Details-Element und das Place Details Compact-Element sind HTML-Elemente, die Details zu einem Ort rendern.

Aktuelle Implementierung

Sie führen einen Place Details-Aufruf mit einer HTTP-Anfrage oder der JavaScript API-Klasse „Place“ aus.
Sie parsen die API-Antwort und zeigen die Ortsdetails mit HTML und CSS an.

Migration zum Place Details-Element

HTML-Struktur ändern

Identifizieren Sie den HTML-Container, in dem die Ortsdetails gerendert werden. Ersetzen Sie Ihre benutzerdefinierten HTML-Elemente (divs, spans für Name, Adresse, Fotos usw.) durch das HTML-Element für Place Details.

Sie können zwischen zwei Elementen wählen:

Kompaktes Element „Place Details“
Place Details-Element

Weitere Informationen dazu, welches Element Sie verwenden sollten, finden Sie unter Place Details-Element.

Ihr vorhandener HTML-Code könnte so aussehen.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Beispiel für neuen HTML-Code, in dem explizit angegeben wird, welcher Inhalt angezeigt werden soll:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

JavaScript-Logik anpassen

Vorhandene Logik

Ihre bestehende Logik umfasst wahrscheinlich Folgendes:

Orts-ID abrufen
PlacesService().getDetails() verwenden oder einen Webdienstaufruf ausführen.
Angabe eines Felds-Arrays (für die JS API) oder einer FieldMask (für den Webdienst), um bestimmte Daten anzufordern.
In der Callback-Auflösung werden die HTML-Elemente manuell ausgewählt und mit den empfangenen Daten gefüllt.

Hier ein Beispiel für die Implementierung von Place Details:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}

Neue Logik

Ihre neue Logik umfasst Folgendes:

Rufen Sie Ihre Orts-ID oder Ihr Ortsobjekt ab.
Rufen Sie einen Verweis auf das <gmp-place-details-place-request>-Element ab.
Übergeben Sie die Orts-ID oder das Place-Objekt an das Attribut „place“ des <gmp-place-details-place-request>-Elements.

Im Folgenden finden Sie ein Beispiel dafür, wie Sie das Place Details UI-Kit in Ihre JavaScript-Logik einbinden können. Rufen Sie einen Verweis auf das Place Details-Element ab. Wenn sie vorhanden ist, rufen Sie einen Verweis auf das Element „Place Details Place Request“ ab und legen Sie die Eigenschaft „place“ mithilfe einer Orts-ID fest. Im obigen HTML-Beispielcode ist der Stil des Place Details-Elements auf display: none festgelegt. Dieser wird auf display: block aktualisiert.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Place Search-Element implementieren

Das Place Search-Element ist ein HTML-Element, mit dem die Ergebnisse einer Ortssuche in einer Liste gerendert werden.

Aktuelle Implementierung

Sie führen eine Text Search- oder Nearby Search-Anfrage über eine HTTP-Anfrage aus oder verwenden die JavaScript API-Klasse „Place“.
Sie geben Suchparameter, Standorteinschränkungen oder ‑gewichtungen, Typen und angeforderte Felder mit FieldMask an.
Sie parsen die API-Antwort, iterieren durch das Array von Orten und erstellen manuell HTML-Listenelemente.

Migration zum Element „Place Search“

HTML-Struktur ändern

Ermitteln Sie den HTML-Container, in dem die Ortsliste gerendert wird. Ersetzen Sie Ihre benutzerdefinierten HTML-Elemente (divs, spans für Name, Adresse usw.) durch das HTML-Element „Place Search Element“.

Ihr vorhandener HTML-Code könnte etwa so aussehen:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

Das Element „Place Search“ wird mit der Komponente <gmp-place-search> implementiert. Wenn Sie den Suchtyp konfigurieren möchten, fügen Sie eine der folgenden Slotted-Konfigurationskomponenten ein:

<gmp-place-text-search-request> für eine Textsuche.
<gmp-place-nearby-search-request> für eine Nearby Search-Anfrage.

Wenn Sie festlegen möchten, wie Ergebnisse angezeigt werden, können Sie das Kürzel <gmp-place-all-content> verwenden oder eigene Präsentationskomponenten angeben. Wichtige Attribute wie selectable (um Klicks auf Listenelemente zuzulassen) und orientation (für ein horizontales oder vertikales Layout) können direkt in der übergeordneten Komponente festgelegt werden.

Beispiel für Nearby Search

<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>

Beispiel für Text Search

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-all-content> </gmp-place-all-content>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

JavaScript-Logik anpassen

Rufen Sie in Ihrem JavaScript-Code mit document.querySelector() einen Verweis auf die Suchcontroller-Komponente ab. Je nach Einrichtung ist dies entweder das Element <gmp-place-text-search-request> oder <gmp-place-nearby-search-request>.

Legen Sie als Nächstes die Attribute für diesen Controller fest, um die Suche zu definieren. Die erforderlichen Attribute hängen vom Typ der Suche ab, die Sie ausführen.

Bei einer Textsuche (<gmp-place-text-search-request>) ist das primäre Attribut textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Bei einer Nearby Search (<gmp-place-nearby-search-request>) müssen Sie den Suchbereich mit einem locationRestriction definieren. Anschließend können Sie mit includedTypes nach bestimmten Arten von Orten in diesem Bereich filtern:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Die übergeordnete <gmp-place-search>-Komponente startet automatisch eine neue Suche, sobald die erforderlichen Attribute des Controllers festgelegt sind.

Bei einer Textsuche wird die Suche ausgeführt, sobald Sie textQuery einen Wert zuweisen.
Bei einer Nearby Search-Anfrage wird die Suche ausgeführt, nachdem ein gültiger locationRestriction-Wert angegeben wurde.

Einfaches Place Autocomplete-Element implementieren

Für Entwickler, die eine Suchfunktion ohne die bereitgestellte Benutzeroberfläche des Place Search-Elements benötigen, ist das Element Basic Place Autocomplete verfügbar.

Dieses Element eignet sich ideal zum Erstellen eines Sucheingabefelds, während Sie die vollständige Kontrolle darüber behalten, wie die Ergebnisse in Ihrer benutzerdefinierten Benutzeroberfläche angezeigt werden. Das Autocomplete-Element ist ausschließlich dafür verantwortlich, Ortsvorschläge zu liefern, während der Nutzer tippt, und programmatisch eine Orts-ID für den ausgewählten Ort bereitzustellen.

Es werden keine Details angezeigt und es werden keine anderen programmatisch zugänglichen Informationen bereitgestellt.

Aktuelle Implementierung

Ihre bestehende Logik umfasst wahrscheinlich Folgendes:

Auf Ihrer Seite wird ein Texteingabefeld gerendert, das während der Eingabe durch den Nutzer Place Autocomplete aufruft und Ergebnisse anzeigt.
Die Orts-ID des vom Nutzer ausgewählten Orts verwenden, um weitere Details abzurufen, z. B. mit der Place Details API.
Details zum ausgewählten Ort werden angezeigt.

Migration zum Place Autocomplete-Element

HTML-Struktur ändern

Suchen und entfernen Sie das HTML-Element, an das Sie das Autocomplete-Widget angehängt haben. Wahrscheinlich wird ein Standard-HTML-Eingabefeld verwendet.

<input id="pac-input" type="text" placeholder="Search for a location" />

Beispiel für neuen HTML-Code, bei dem der Webkomponentenansatz verwendet wird, um ein einfaches Place Autocomplete-Element auf Ihrer Seite zu initialisieren.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

JavaScript-Logik anpassen

Ihre JavaScript-Logik umfasst wahrscheinlich das Erstellen des Autocomplete-Widgets, das an ein input-HTML-Element angehängt ist. Dieses Widget wartet dann auf das Ereignis place_changed und löst eine Aktion mit den zurückgegebenen Daten aus.

Beispiel für vorhandenes JavaScript, das entfernt werden muss:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Ihre neue JavaScript-Logik erhält einen Verweis auf das Basic Place Autocomplete-Element und wartet auf gmp-select-Ereignisse:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Wenn ein Ort im Drop-down-Menü für die automatische Vervollständigung ausgewählt wird, wird das Ereignis gmp-select ausgelöst. Die Orts-ID des ausgewählten Orts kann aus dem event-Objekt abgerufen werden. Mit der Orts-ID kann dann eine Instanz des Place Details-Elements initialisiert werden, um die Details des ausgewählten Orts anzuzeigen.

Alias anpassen

Anpassung des Place Details-Elements

Ausrichtung

Das Element „Place Details“ kann sowohl horizontal als auch vertikal gerendert werden. Verwenden Sie das Attribut orientation für gmp-place-details-compact, um zwischen vertikal und horizontal zu wählen. Beispiel:

<gmp-place-details-compact orientation="vertical">

Felder zum Rendern auswählen

Mit Inhaltselementen können Sie den Inhalt angeben, der im Element „Place Details“ gerendert werden soll. Wenn Sie beispielsweise das Inhaltselement <gmp-place-type> ausschließen, wird der Ortstyp des ausgewählten Orts nicht mehr im Place Details-Element gerendert. Eine vollständige Liste der Inhaltselemente finden Sie in der Referenzdokumentation zu PlaceContentConfigElement.

Das Hinzufügen oder Entfernen von Feldern im Place Details-Element hat keine Auswirkungen auf die Kosten für das Rendern des Elements auf der Seite.

CSS-Stile festlegen

Es sind benutzerdefinierte CSS-Eigenschaften verfügbar, mit denen Sie die Farben und Schriftarten des Elements konfigurieren können. Wenn Sie beispielsweise den Hintergrund des Elements auf Grün festlegen möchten, legen Sie die folgende CSS-Property fest:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Weitere Informationen finden Sie in der Referenzdokumentation zu PlaceDetailsCompactElement.

Anpassung des Place Search-Elements

Ausrichtung

Das Element „Place Search“ kann sowohl im horizontalen als auch im vertikalen Format gerendert werden. Verwenden Sie das Attribut orientation für <gmp-place-search>, um zwischen vertikal und horizontal zu wählen. Beispiel:

<gmp-place-search orientation="horizontal" selectable>

Felder zum Rendern auswählen

Verwenden Sie Inhaltselemente, um den Inhalt anzugeben, der im Element „Place Search“ gerendert werden soll. Mit dem Element <gmp-place-all-content> können Sie alle Inhalte anzeigen lassen. Alternativ können Sie eine Auswahl von HTML-Tags verwenden, um die gerenderten Inhalte zu konfigurieren.

Wenn Sie <gmp-place-address> in <gmp-place-content-config> einfügen, wird nur die Adresse für jeden Ort gerendert, z. B.:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Einfache Anpassung des Place Autocomplete-Elements

CSS-Stile festlegen

Mit benutzerdefinierten CSS-Eigenschaften können Sie das Design des Autocomplete-Elements anpassen. Wenn Sie beispielsweise die Hintergrundfarbe auf Hellviolett festlegen möchten, legen Sie die Eigenschaft background-color für das Element fest.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Weitere Informationen finden Sie in der Referenzdokumentation zu BasicPlaceAutocompleteElement.

Ereignisse und Daten verarbeiten

Die Places UI Kit-Elemente sind interaktive Komponenten, mit denen Sie Ereignisse erfassen und Daten programmatisch abrufen können.

Auf Ereignisse warten

Sie können den Elementen Event-Listener hinzufügen, um Aktionen basierend auf Nutzerinteraktionen oder dem Status des Elements auszulösen.

Auswahlereignis

gmp-select: Dieses Ereignis wird ausgelöst, wenn ein Nutzer eine Auswahl trifft.
- Beim Place Search-Element wird es ausgelöst, wenn ein Nutzer in der Ergebnisliste auf einen Ort klickt.
- Beim Basic Place Autocomplete-Element wird es ausgelöst, wenn ein Nutzer auf einen Vorschlag in der Drop-down-Liste klickt.

Häufige Ereignisse

Die Elemente „Place Search“, „Place Details“ und „Basic Place Autocomplete“ unterstützen die folgenden Ereignisse:

gmp-load: Wird ausgelöst, wenn das Element und sein Inhalt vollständig geladen und gerendert wurden.
gmp-requesterror: Wird ausgelöst, wenn eine Anfrage an den Server fehlschlägt, z. B. aufgrund eines ungültigen API-Schlüssels.

Programmatisch auf Elementdaten zugreifen

Sie können bestimmte Daten aus den Elementen programmatisch abrufen, nachdem mit ihnen interagiert wurde oder sie geladen wurden.

Für die Elemente „Place Search“ und „Place Details“ können Sie die folgenden Informationen abrufen:
- Orts-ID
- Standort (Breiten- und Längengrad)
- Darstellungsbereich
Für das Basic Place Autocomplete-Element können Sie die folgenden Informationen abrufen:
- Orts-ID

Auf alle anderen in den Elementen enthaltenen Daten kann nicht programmatisch zugegriffen werden.

Ausführlichere Beispiele finden Sie in der Dokumentation zum Place Search-Element, zum Place Details-Element und zum Basic Place Autocomplete-Element.

Nachdem Sie die Elemente des Places UI Kit eingebunden haben, sind Tests entscheidend für einen reibungslosen Übergang und eine positive Nutzererfahrung. Ihre Tests sollten mehrere wichtige Bereiche abdecken und alle von Ihnen implementierten Elemente umfassen: Place Details, Place Search und Basic Place Autocomplete.

Place Details-Element

Prüfen Sie zuerst, ob die Details für eine Vielzahl von Orten korrekt angezeigt werden. Testen Sie die Funktion, indem Sie verschiedene Orts-IDs an das Attribut .place des Elements <gmp-place-details-place-request> übergeben. Verwenden Sie IDs, die verschiedene Arten von Einrichtungen (Unternehmen mit Rich-Daten, POIs, einfache Adressen) und Orte in verschiedenen Regionen oder Sprachen darstellen. Achten Sie genau auf die Formatierung, das Layout und das Vorhandensein der Inhalte.

Place Search Element

Wenn Sie das Place Search-Element implementiert haben, prüfen Sie das Rendering und Verhalten in verschiedenen Suchszenarien.

Legen Sie für eine Textsuche das Attribut textQuery für das Element <gmp-place-text-search-request> mit verschiedenen Eingaben fest: allgemeine Suchanfragen, bestimmte Adressen und Suchanfragen mit Standortgewichtung.
Wenn Sie eine Nearby Search-Anfrage testen möchten, legen Sie die Attribute locationRestriction und includedTypes für das Element <gmp-place-nearby-search-request> fest. Verwenden Sie verschiedene Standortgrößen und Typfilter.

Prüfen Sie, ob die Liste mit relevanten Ergebnissen gefüllt wird und ob das Ereignis gmp-select bei der Auswahl korrekt ausgelöst wird.

Einfaches Place Autocomplete-Element

Konzentrieren Sie sich beim Testen des Elements „Place Autocomplete (Basic)“ auf die Nutzerinteraktion und die vom Auswahlereignis übergebenen Daten. Prüfen Sie, ob das Ereignis gmp-select zuverlässig ausgelöst wird, wenn ein Nutzer auf eine Vervollständigung klickt. Prüfen Sie, ob das Objekt event.place im Event-Handler eine gültige Orts-ID enthält.

Am wichtigsten ist es, den gesamten Ablauf zu testen: Wählen Sie einen Ort aus dem Autocomplete-Drop-down-Menü aus und prüfen Sie, ob die Orts-ID erfolgreich verwendet werden kann, um ein anderes Element wie das Place Details-Element zu füllen.

Fehlerbehandlung

Eine gründliche Prüfung der Fehlerbehandlung ist für alle Komponenten unerlässlich. Simulieren Sie die Übergabe ungültiger oder nicht vorhandener Orts-IDs an das Place Details-Element oder die Verwendung ungültiger Suchparameter für das Place Search-Element. Lösen Sie das Ereignis gmp-requesterror aus, indem Sie Netzwerkprobleme simulieren oder einen ungültigen API-Schlüssel verwenden, um zu prüfen, ob Ihre Anwendung ordnungsgemäß damit umgeht. Implementieren Sie nutzerfreundliche Fehlermeldungen und Logging, um eine fehlerhafte oder verwirrende Benutzeroberfläche zu vermeiden.

Places UI Kit für bestehende Places API-Nutzer verwenden Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Für wen ist dieses Handbuch gedacht?

Vorbereitung

Laden der Maps JavaScript API aktualisieren

Place Details-Element implementieren

Aktuelle Implementierung

Migration zum Place Details-Element

HTML-Struktur ändern

JavaScript-Logik anpassen

Vorhandene Logik

Neue Logik

Place Search-Element implementieren

Aktuelle Implementierung

Migration zum Element „Place Search“

HTML-Struktur ändern

Beispiel für Nearby Search

Beispiel für Text Search

JavaScript-Logik anpassen

Einfaches Place Autocomplete-Element implementieren

Aktuelle Implementierung

Migration zum Place Autocomplete-Element

HTML-Struktur ändern

JavaScript-Logik anpassen

Alias anpassen

Anpassung des Place Details-Elements

Ausrichtung

Felder zum Rendern auswählen

CSS-Stile festlegen

Anpassung des Place Search-Elements

Ausrichtung

Felder zum Rendern auswählen

Einfache Anpassung des Place Autocomplete-Elements

CSS-Stile festlegen

Ereignisse und Daten verarbeiten

Auf Ereignisse warten

Auswahlereignis

Häufige Ereignisse

Programmatisch auf Elementdaten zugreifen

Testen und Optimieren

Places UI Kit für bestehende Places API-Nutzer verwenden