Diese Seite wurde von der Cloud Translation API übersetzt.

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

Ziel: Ersetzen Sie Ihre Implementierung der Places API oder der Place-Klasse durch das Places UI Kit.

Für wen ist dieses Handbuch gedacht?

Entwickler, die

HTTP-Anfragen an Endpunkte der Places API (neu oder alt) senden.
Verwendung der Place-Klasse in der Maps JavaScript API.
Die API-Antwort wird verarbeitet, um Ortsinformationen in der Benutzeroberfläche der Webanwendung darzustellen.

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.

Maps JavaScript API-Ladevorgang aktualisieren

Für das Places UI Kit ist die Dynamic Library Import-Methode zum Laden der Maps JavaScript API erforderlich. Wenn Sie das Tag zum direkten Laden von Scripts verwenden, muss es 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, mit denen Details zu einem Ort gerendert werden.

Aktuelle Implementierung

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

Migration zum Element „Place Details“

HTML-Struktur ändern

Identifizieren Sie den HTML-Container, in dem Ortsdetails gerendert werden. Ersetzen Sie Ihre benutzerdefinierten HTML-Elemente (Divs, Spans für Name, Adresse, Fotos usw.) durch das HTML-Element „Ortsdetails“.

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 neues HTML, in dem explizit angegeben wird, welche Inhalte angezeigt werden sollen:

<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

Bestehende Logik

Ihre vorhandene Logik umfasst wahrscheinlich Folgendes:

Orts-ID abrufen
PlacesService().getDetails() verwenden oder einen Webdienstaufruf ausführen.
Geben Sie ein „fields“-Array (für die JS API) oder eine „FieldMask“ (für den Webdienst) an, um bestimmte Daten anzufordern.
Bei der Callback-Auflösung werden Ihre HTML-Elemente manuell ausgewählt und mit den empfangenen Daten gefüllt.

Im Folgenden finden Sie ein Beispiel für die Implementierung von Ortsdetails:

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

Die 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 Ortsobjekt an die Eigenschaft „place“ des Elements <gmp-place-details-place-request>.

Im Folgenden finden Sie ein Beispiel für die Implementierung des Place Details UI Kit in Ihrer JavaScript-Logik. Rufen Sie einen Verweis auf das Element „Ortsdetails“ ab. Wenn es vorhanden ist, rufen Sie eine Referenz auf das Place Details Place Request-Element ab und legen Sie die place-Eigenschaft mit einer Orts-ID fest. Im obigen Beispiel-HTML-Code ist der Stil des Elements „Ortsdetails“ auf display: none festgelegt. Das wurde zu 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 Textsuche oder eine Suche in der Nähe mit einer HTTP-Anfrage durch oder verwenden die Place-Klasse der JavaScript API.
Sie geben Abfrageparameter, Standortbeschränkungen oder ‑gewichtungen, Typen und angeforderte Felder mit FieldMask an.
Sie parsen die API-Antwort, durchlaufen das Array mit Orten und erstellen manuell HTML-Listenelemente.

Migration zum Place Search Element

HTML-Struktur ändern

Identifizieren Sie den HTML-Container, in dem Sie Ihre Ortsliste rendern. 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 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 Place Search-Element wird mit der <gmp-place-search>-Komponente implementiert. Um den Suchtyp zu konfigurieren, fügen Sie eine der folgenden Konfigurationskomponenten mit Platzhaltern ein:

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

Um festzulegen, wie Ergebnisse dargestellt werden, können Sie die <gmp-place-all-content>-Abkürzung verwenden oder eigene einzelne Präsentationskomponenten angeben. Schlüsselattribute wie selectable (um Klicks auf Listenelemente zuzulassen) und orientation (für ein horizontales oder vertikales Layout) können direkt für die übergeordnete 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 die Textsuche

<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 mit document.querySelector() eine Referenz auf die Suchcontrollerkomponente ab. Je nach Einrichtung ist das entweder das <gmp-place-text-search-request>- oder das <gmp-place-nearby-search-request>-Element.

Legen Sie als Nächstes die Eigenschaften für diesen Controller fest, um die Suche zu definieren. Die erforderlichen Eigenschaften hängen vom Suchtyp ab.

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

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

Für eine „Nearby Search“-Anfrage (<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 Gebiet 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 initiiert automatisch eine neue Suche, sobald die erforderlichen Attribute des zugehörigen 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ültiges locationRestriction 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 Basic Place Autocomplete-Element verfügbar.

Dieses Element eignet sich ideal zum Erstellen eines Suchfelds, während Sie die vollständige Kontrolle darüber behalten, wie die Ergebnisse in Ihrer benutzerdefinierten Benutzeroberfläche angezeigt werden. Die einzige Aufgabe des Autocomplete-Elements besteht darin, 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 sind keine anderen programmatisch zugänglichen Informationen verfügbar.

Aktuelle Implementierung

Ihre vorhandene Logik umfasst wahrscheinlich Folgendes:

Ein Textfeld auf Ihrer Seite rendern, in dem Place Autocomplete aufgerufen wird, während der Nutzer tippt, und Ergebnisse angezeigt werden.
Die Orts-ID des vom Nutzer ausgewählten Orts wird verwendet, 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 Sie das HTML-Element, an das Sie das Autocomplete-Widget anhängen, und entfernen Sie es. Wahrscheinlich wird ein standardmäßiges HTML-Eingabefeld verwendet.

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

Beispiel für neues HTML, in dem die Webkomponente verwendet wird, um ein Basic 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 place_changed-Ereignis und löst eine Aktion mit den zurückgegebenen Daten aus.

Beispiel für vorhandenen JavaScript-Code, der 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 eine Referenz 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 in der Drop-down-Liste für die automatische Vervollständigung ausgewählt wird, wird das gmp-select-Ereignis ausgelöst. Die Orts-ID des ausgewählten Orts kann aus dem event-Objekt abgerufen werden. Die Orts-ID kann dann verwendet werden, um eine Instanz des Place Details Element zu initialisieren und die Details des ausgewählten Orts anzuzeigen.

Alias anpassen

„Place Details“-Element anpassen

Ausrichtung

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

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

Felder für das Rendern auswählen

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

Das Hinzufügen oder Entfernen von Feldern aus dem Element „Ortsdetails“ ändert nicht die Kosten für das Rendern des Elements auf der Seite.

CSS-Stile festlegen

Benutzerdefinierte CSS-Eigenschaften sind verfügbar, um die Farben und Schriftarten des Elements zu konfigurieren. Wenn Sie beispielsweise den Elementhintergrund auf Grün festlegen möchten, legen Sie die folgende CSS-Eigenschaft fest:

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

Weitere Informationen finden Sie in der Referenzdokumentation zu PlaceDetailsCompactElement.

„Place Search“-Element anpassen

Ausrichtung

Das Element „Ortssuche“ kann sowohl horizontal als auch vertikal gerendert werden. Mit dem Attribut orientation für <gmp-place-search> können Sie zwischen vertikal und horizontal wählen. Beispiel:

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

Felder für das Rendern auswählen

Mit Inhaltselementen können Sie den Inhalt angeben, der im Place Search-Element gerendert werden soll. Mit dem Element <gmp-place-all-content> kann der gesamte Inhalt angezeigt werden. Alternativ kann eine Auswahl von HTML-Tags verwendet werden, um den gerenderten Inhalt 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-Properties lässt sich das Erscheinungsbild des Elements für die automatische Vervollständigung anpassen. Wenn Sie beispielsweise die Hintergrundfarbe auf Hellviolett festlegen möchten, müssen Sie das Attribut background-color für das Element festlegen.

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 programmatisch auf Ereignisse reagieren und Daten abrufen können.

Auf Ereignisse warten

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

Auswahlereignis

gmp-select: Dieses Ereignis wird ausgelöst, wenn ein Nutzer eine Auswahl trifft.
- Beim Element „Ortsuche“ 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 in der Drop-down-Liste auf einen Vorschlag 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 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 das Place Search-Element und das Place Details-Element können Sie die folgenden Informationen abrufen:
- Orts-ID
- Standort (Breitengrad und Längengrad)
- Darstellungsbereich
Für das einfache Place Autocomplete-Element können Sie die folgenden Informationen abrufen:
- Orts-ID

Alle anderen Daten, die in den Elementen enthalten sind, sind nicht programmatisch zugänglich.

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

Nachdem Sie Elemente des Places UI Kit integriert haben, sind Tests entscheidend für einen reibungslosen Übergang und eine positive User Experience. Ihre Tests sollten mehrere wichtige Bereiche abdecken und alle implementierten Elemente berücksichtigen: Place Details, Place Search und Basic Place Autocomplete.

Element „Ortsdetails“

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

Element für die Ortssuche

Wenn Sie das Place Search Element implementiert haben, prüfen Sie, wie es in verschiedenen Suchszenarien gerendert wird und wie es sich verhält.

Für die Textsuche testen Sie, indem Sie das Attribut textQuery für das Element <gmp-place-text-search-request> mit verschiedenen Eingaben festlegen: allgemeine Anfragen, bestimmte Adressen und Anfragen mit Ortsangaben.
Bei einer „Nearby Search“-Anfrage testen Sie, indem Sie die Attribute locationRestriction und includedTypes für das <gmp-place-nearby-search-request>-Element festlegen. Verwenden Sie verschiedene Standortgrößen und Typfilter.

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

Einfaches Place Autocomplete-Element

Konzentrieren Sie sich beim Testen des Basic Place Autocomplete-Elements auf die Nutzerinteraktion und die Daten, die vom Auswahlereignis übergeben werden. Prüfen Sie, ob das gmp-select-Ereignis zuverlässig ausgelöst wird, wenn ein Nutzer auf eine Vorhersage klickt. Prüfen Sie, ob das Objekt event.place im Ereignishandler eine gültige Orts-ID enthält.

Am wichtigsten ist es, den End-to-End-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 zu füllen, z. B. das Place Details-Element.

Fehlerbehandlung

Eine gründliche Prüfung der Fehlerbehandlung ist für alle Komponenten unerlässlich. Simulieren Sie das Übergeben 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 gmp-requesterror-Ereignis aus, indem Sie Netzwerkprobleme simulieren oder einen ungültigen API-Schlüssel verwenden, um sicherzustellen, dass Ihre Anwendung es ordnungsgemäß verarbeitet. Implementieren Sie benutzerfreundliche Fehlermeldungen und Protokollierung, 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

Maps JavaScript API-Ladevorgang aktualisieren

„Place Details“-Element implementieren

Aktuelle Implementierung

Migration zum Element „Place Details“

HTML-Struktur ändern

JavaScript-Logik anpassen

Bestehende Logik

Neue Logik

„Place Search Element“ implementieren

Aktuelle Implementierung

Migration zum Place Search Element

HTML-Struktur ändern

Beispiel für „Nearby Search“

Beispiel für die Textsuche

JavaScript-Logik anpassen

Einfaches Place Autocomplete-Element implementieren

Aktuelle Implementierung

Migration zum Place Autocomplete-Element

HTML-Struktur ändern

JavaScript-Logik anpassen

Alias anpassen

„Place Details“-Element anpassen

Ausrichtung

Felder für das Rendern auswählen

CSS-Stile festlegen

„Place Search“-Element anpassen

Ausrichtung

Felder für das 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