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

Informationen zum Migrieren Ihrer vorhandenen Places API- oder Place Class-Implementierung zu den Places UI Kit -Komponenten.

Für wen ist dieses Handbuch gedacht?

Dieses Handbuch richtet sich an Entwickler, die eine vorhandene Implementierung mit der Places API haben und ihren Code aktualisieren möchten, um das Places UI Kit zu verwenden. Es ist besonders hilfreich, wenn Sie bereits:

HTTP-Anfragen an Places API-Endpunkte (neu oder Legacy) senden.
Die Place-Klasse in der Maps JavaScript API verwenden.
Die API-Antwort verarbeiten, um Ortsinformationen in der UI 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, einschließlich zum Einschränken eines Schlüssels, finden Sie unter Use API Keys.

Maps JavaScript API-Ladevorgang aktualisieren

Für das Places UI Kit ist die Methode zum dynamischen Importieren von Bibliotheken zum Laden der Maps JavaScript API erforderlich. Wenn Sie das Tag zum direkten Laden von Skripts 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 kompakte „Place Details“-Element sind HTML-Elemente, die Details zu einem Ort rendern.

Aktuelle Implementierung

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

Zu „Place Details“-Element migrieren

HTML-Struktur ändern

Suchen 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 des „Place Details“-Elements.

Sie können zwischen zwei Elementen wählen:

Kompaktes „Place Details“-Element
„Place Details“-Element

Weitere Informationen zur Auswahl des richtigen Elements finden Sie unter „Place Details“ Element.

Ihr vorhandenes HTML 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

Vorhandene Logik

Ihre vorhandene Logik umfasst wahrscheinlich Folgendes:

Abrufen einer Orts-ID
Verwenden von PlacesService().getDetails() oder Ausführen eines Webdienstaufrufs
Angeben eines Felds-Arrays (für die JS API) oder einer FieldMask (für den Webdienst), um bestimmte Daten anzufordern
Manuelles Auswählen Ihrer HTML-Elemente in der Callback-Auflösung und Ausfüllen mit den empfangenen Daten

Im Folgenden finden Sie ein Beispiel dafür, wie Sie „Place Details“ implementiert haben könnten:

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:

Orts-ID oder Ortsobjekt abrufen
Eine Referenz zum <gmp-place-details-place-request> Element abrufen
Die Orts-ID oder das Ortsobjekt an die Ortseigenschaft des Elements <gmp-place-details-place-request> übergeben

Im Folgenden finden Sie ein Beispiel dafür, wie Sie das Place Details UI Kit in Ihrer JavaScript-Logik implementieren können: Eine Referenz zum „Place Details“-Element abrufen Wenn es vorhanden ist, eine Referenz zum Element „Place Details Place Request“ abrufen und die Ortseigenschaft mit einer Orts-ID festlegen Im obigen Beispiel-HTML-Code ist der Stil des „Place Details“-Elements auf display: none festgelegt. Er 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, das die Ergebnisse einer Ortssuche in einer Liste rendert.

Aktuelle Implementierung

Sie führen eine Textsuche oder eine Suche in der Nähe mit einer HTTP-Anfrage aus 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 von Orten und erstellen manuell HTML-Listenelemente.

Zu „Place Search“-Element migrieren

HTML-Struktur ändern

Suchen 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 vorhandenes HTML 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. Wenn Sie den Suchtyp konfigurieren möchten, fügen Sie eine der folgenden Komponenten mit Slot-Inhalt ein:

<gmp-place-text-search-request> für eine Textsuche
<gmp-place-nearby-search-request> für eine Suche in der Nähe

Um festzulegen, wie Ergebnisse angezeigt werden, können Sie die <gmp-place-all-content> Verknüpfung verwenden oder eine eigene Gruppe einzelner Präsentationskomponenten angeben. Wichtige Attribute 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 Suche in der Nähe

<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 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 zur Suchcontroller-Komponente ab. Je nach Einrichtung ist dies entweder das <gmp-place-text-search-request> oder <gmp-place-nearby-search-request> Element.

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

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 Suche in der Nähe (<gmp-place-nearby-search-request>) müssen Sie den Suchbereich mit einer locationRestriction definieren. Mit includedTypes können Sie dann 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 Komponente <gmp-place-search> startet automatisch eine neue Suche , sobald die erforderlichen Eigenschaften des Controllers festgelegt sind.

Bei einer Textsuche wird die Suche ausgeführt, sobald Sie textQuery einen Wert zuweisen.
Bei einer Suche in der Nähe wird die Suche ausgeführt, nachdem eine gültige locationRestriction angegeben wurde.

Einfaches „Place Autocomplete“-Element implementieren

Für Entwickler, die eine Suche ohne die bereitgestellte UI des „Place Search“-Elements benötigen, ist das einfache „Place Autocomplete “-Element 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. 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 zeigt keine Details an und bietet keine anderen programmatisch zugänglichen Informationen.

Aktuelle Implementierung

Ihre vorhandene Logik umfasst wahrscheinlich Folgendes:

Rendern eines Texteingabefelds auf Ihrer Seite, das „Place Autocomplete“ aufruft, während der Nutzer tippt, und Ergebnisse anzeigt.
Verwenden der Orts-ID des vom Nutzer ausgewählten Orts, um weitere Details abzurufen, z. B. mit der Place Details API.
Anzeigen von Details zum ausgewählten Ort.

Zu „Place Autocomplete“-Element migrieren

HTML-Struktur ändern

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

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

Beispiel für neues HTML, das den Webkomponentenansatz verwendet, 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 ruft eine Referenz zum einfachen „Place Autocomplete“-Element ab 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ü „Autocomplete“ ausgewählt wird, wird das Ereignis gmp-select 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-Elements zu initialisieren, um die Details des ausgewählten Orts anzuzeigen.

Anpassung verarbeiten

„Place Details“-Element anpassen

Ausrichtung

Das „Place Details“-Element 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">

Zu rendernde Felder auswählen

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

Das Hinzufügen oder Entfernen von Feldern aus dem „Place Details“-Element ändert nichts an den 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 Hintergrund des Elements 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 „Place Search“-Element kann sowohl horizontal als auch vertikal 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>

Zu rendernde Felder auswählen

Verwenden Sie Inhaltselemente, um den Inhalt anzugeben, der im „Place Search“-Element gerendert werden soll. Das Element <gmp-place-all-content> kann verwendet werden, um alle Inhalte anzuzeigen. 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>

Einfaches „Place Autocomplete“-Element anpassen

CSS-Stile festlegen

Benutzerdefinierte CSS-Eigenschaften sind verfügbar, um das Erscheinungsbild des Autocomplete-Elements anzupassen. 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 BasicPlaceAutocompleteElement.

Ereignisse und Daten verarbeiten

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

Auf Ereignisse warten

Sie können den Elementen Ereignis-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 „Place Search“-Element wird es ausgelöst, wenn ein Nutzer auf einen Ort in der Ergebnisliste klickt.
- Beim einfachen „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 alle 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 programmatisch aus den Elementen abrufen, nachdem mit ihnen interagiert 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 (Breiten- und Längengrad)
- Darstellungsbereich
Für das einfache „Place Autocomplete“-Element können Sie die folgenden Informationen abrufen:
- Orts-ID

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

Ausführlichere Beispiele finden Sie in der jeweiligen Dokumentation für das „Place Search“-Element, das „Place Details“-Element, und das einfache „Place Autocomplete“-Element.

Nachdem Sie das/die Element(e) des Places UI Kit eingebunden haben, sind Tests entscheidend für einen reibungslosen Übergang und eine positive Nutzererfahrung. Ihre Tests sollten mehrere Schlüsselbereiche abdecken und alle von Ihnen implementierten Elemente berücksichtigen: die Elemente „Place Details“, „Place Search“ und „Basic Place Autocomplete“.

„Place Details“-Element

Beginnen Sie beim „Place Details“-Element damit, zu prüfen, ob die Details für eine Vielzahl von Orten korrekt angezeigt werden. Testen Sie, indem Sie verschiedene Orts-IDs an die .place Eigenschaft des <gmp-place-details-place-request> Elements übergeben. Verwenden Sie IDs, die verschiedene Arten von Unternehmen (Unternehmen mit umfangreichen Daten, Points of Interest, 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 das Verhalten in verschiedenen Suchszenarien.

Für eine Textsuche testen Sie, indem Sie die textQuery Eigenschaft für das <gmp-place-text-search-request> Element mit verschiedenen Eingaben festlegen: allgemeine Suchanfragen, bestimmte Adressen und Suchanfragen mit Standortgewichtungen.
Für eine Suche in der Nähe testen Sie, indem Sie die locationRestriction und includedTypes Eigenschaften 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 ob das Ereignis gmp-select bei der Auswahl korrekt ausgelöst wird.

Einfaches „Place Autocomplete“-Element

Konzentrieren Sie sich beim Testen des einfachen „Place Autocomplete“-Elements auf die Nutzerinteraktion und die Daten, die vom Auswahlereignis übergeben werden. Prüfen Sie, ob das Ereignis gmp-select zuverlässig ausgelöst wird, wenn ein Nutzer auf einen Vorschlag 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 Drop-down-Menü „Autocomplete“ aus und prüfen Sie, ob seine Orts-ID erfolgreich verwendet werden kann, um ein anderes Element zu füllen, z. B. das „Place Details“-Element.

Fehlerbehandlung

Eine strenge 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 Ereignis gmp-requesterror aus, indem Sie Netzwerkprobleme simulieren oder einen ungültigen API-Schlüssel verwenden, um sicherzustellen, dass Ihre Anwendung es ordnungsgemäß verarbeitet. Implementieren Sie nutzerfreundliche Fehlermeldungen und Logging, um eine fehlerhafte oder verwirrende UI 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

Zu „Place Details“-Element migrieren

HTML-Struktur ändern

JavaScript-Logik anpassen

Vorhandene Logik

Neue Logik

„Place Search“-Element implementieren

Aktuelle Implementierung

Zu „Place Search“-Element migrieren

HTML-Struktur ändern

Beispiel für Suche in der Nähe

Beispiel für Textsuche

JavaScript-Logik anpassen

Einfaches „Place Autocomplete“-Element implementieren

Aktuelle Implementierung

Zu „Place Autocomplete“-Element migrieren

HTML-Struktur ändern

JavaScript-Logik anpassen

Anpassung verarbeiten

„Place Details“-Element anpassen

Ausrichtung

Zu rendernde Felder auswählen

CSS-Stile festlegen

„Place Search“-Element anpassen

Ausrichtung

Zu rendernde Felder auswählen

Einfaches „Place Autocomplete“-Element anpassen

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