Orte mit PlaceSearchElement finden

Ziel

Hier erfahren Sie, wie Sie das PlaceSearchElement in Google Maps einbinden, damit Nutzer Orte über die Nearby Search oder die Text Search finden und so interessante Orte besser erkunden können. Mit dem kompakten Element „Place Details“ können Sie weitere Details zu den Orten bereitstellen, die in Ihrer Anwendung angezeigt werden.

Was ist das PlaceSearchElement?

Das PlaceSearchElement ist Teil des Places UI Kit in der Maps JavaScript API. Es ist ein HTML-Element, das die Ergebnisse einer Ortssuche direkt in einem Listenformat in Ihrer Anwendung rendert. Dieses Element vereinfacht die Anzeige von Orten, die über die Nearby Search oder die Text Search gefunden wurden, und bietet so eine nahtlose Nutzererfahrung bei der Ortssuche. Wenn ein Nutzer einen Ort aus der Liste auswählt, können Sie die Details auf der Karte anzeigen, oft mit einem Infofenster und dem Element „Place Details“.

Ortssuche visualisieren

Die folgende Abbildung zeigt ein Beispiel für das PlaceSearchElement in Aktion. Links wird eine Liste von Restaurants angezeigt (PlaceSearchElement). Wenn ein Restaurant ausgewählt wird, werden die Details in einem Infofenster auf der Karte angezeigt und die Karte wird auf den Standort zentriert.

Anwendungsfälle für die Ortssuche

Die Einbindung des PlaceSearchElement kann verschiedene Anwendungen in unterschiedlichen Branchen verbessern:

• Reisen und Tourismus:Touristen können nach Sehenswürdigkeiten, Hotels oder bestimmten Arten von Küche in einer Region suchen.
• Immobilien:Potenzielle Käufer oder Mieter können nach Schulen, Supermärkten oder öffentlichen Verkehrsmitteln in der Nähe suchen.
• Logistik und Dienstleistungen:Fahrer können Ladestationen für Elektrofahrzeuge, Tankstellen oder bestimmte Servicecenter finden.

Lösungsworkflow: Ortssuche implementieren

In diesem Abschnitt erfahren Sie, wie Sie das PlaceSearchElement einbinden, um Orte auf einer Karte zu finden. Außerdem finden Sie Code-Snippets für die Interaktion mit dem Places UI Kit. Sie erfahren, wie Sie die Karte initialisieren und sowohl die Nearby Search als auch die Text Search implementieren. Verwenden Sie schließlich das Element „Place Details“, um weitere Details zu einem Ort anzuzeigen, wenn ein Nutzer auf die Markierung auf der Karte klickt.

Vorbereitung

Es wird empfohlen, sich mit der folgenden Dokumentation vertraut zu machen:

• PlaceSearchElement : Wird verwendet, um Orte entweder über die Nearby Search oder die Text Search zu finden.
• Element „Place Details“ : Wird verwendet, um Details zu einem einzelnen Ort anzuzeigen.
• Maps JavaScript API: Wird verwendet, um eine Karte auf Ihrer Seite anzuzeigen und das Places UI Kit zu importieren.

Aktivieren Sie Maps JavaScript API und Places UI Kit in Ihrem Projekt.

Prüfen Sie, ob Sie die Maps JavaScript API geladen und die erforderlichen Bibliotheken importiert haben, bevor Sie beginnen. In diesem Dokument werden außerdem Kenntnisse in der Webentwicklung vorausgesetzt, einschließlich HTML, CSS und JavaScript.

Karte zur Seite hinzufügen

Der erste Schritt besteht darin, Ihrer Seite eine Karte hinzuzufügen. Auf dieser Karte werden die Ergebnisse von PlaceSearchElement als auswählbare Markierungen angezeigt.

Es gibt zwei Möglichkeiten, einer Seite eine Karte hinzuzufügen:

1. Mit einer gmp-map HTML-Web komponente.
2. Mit JavaScript.

Die Code-Snippets auf dieser Seite wurden mit einer JavaScript-Karte generiert.

Die Karte kann entweder auf einen Ort zentriert werden, in dessen Nähe der Nutzer suchen soll, z. B. ein Hotel, oder so initialisiert werden, dass der Nutzer nach seinem aktuellen Standort gefragt wird, um die Karte zu zentrieren. Für die Zwecke dieses Dokuments verwenden wir einen festen Standort, um die Suche zu verankern.

Wenn Sie Orte in der Nähe eines festen Standorts, z. B. eines Hotels, platzieren Sie eine Markierung auf der Karte, um diesen Ort darzustellen. Beispiel:

Die Karte ist auf San Francisco zentriert. Eine blaue Markierung stellt den Ort dar, in dessen Nähe wir suchen. Die Farbe der Markierung wurde mit PinElement angepasst. Das Steuerelement „Kartentyp“ wurde auf der Benutzeroberfläche ausgeblendet.

PlaceSearchElement einrichten

Richten Sie nun das HTML und CSS ein, um das PlaceSearchElement anzuzeigen. In diesem Beispiel wird das Element links neben der Karte platziert. Sie können aber auch andere Layouts ausprobieren, die für Ihre Anwendung geeignet sind.

Das PlaceSearchElement verwendet einen deklarativen Ansatz. Anstatt es vollständig in JavaScript zu konfigurieren, definieren Sie den Suchtyp direkt in Ihrem HTML-Code, indem Sie ein Anfrageelement wie <gmp-place-nearby-search-request> in die Hauptkomponente <gmp-place-search> einfügen.

Initialisieren Sie in Ihrem HTML-Code ein <gmp-place-search>-Element. Verwenden Sie das Attribut selectable, um Klickereignisse für die Ergebnisse zu aktivieren. Fügen Sie darin ein <gmp-place-nearby-search-request> hinzu, um anzugeben, dass dieses Element für die Nearby Search verwendet wird.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Um eine erste Suche durchzuführen und Ergebnisse anzuzeigen, rufen wir mit JavaScript einen Verweis auf das verschachtelte Anfrageelement ab und legen seine Eigenschaften fest. Initialisieren Sie einen Kreis, der als locationRestriction verwendet werden soll, und verwenden Sie die Markierungsposition aus dem vorherigen Schritt als Mittelpunkt. Legen Sie dann die Eigenschaften locationRestriction und includedPrimaryTypes für das Anfrageelement fest, um die Suche auszulösen.

Das Code-Snippet dafür sieht so aus:

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

Ein Beispiel dafür, wie die Anwendung in dieser Phase aussehen könnte, ist Folgendes:

Nutzern die Suche ermöglichen

Das PlaceSearchElement bietet zwei Suchoptionen:

• <gmp-place-nearby-search-request> : Suchergebnisse aus einer Places Nearby Search mit Place Types rendern.
• <gmp-place-text-search-request> : Suchergebnisse aus einer Places Text Search mit einer Freitext Eingabe wie „Sushi in San Francisco“ rendern.

Das sind verschachtelte Elemente in <gmp-place-search>. Sie lösen dann Suchen aus, indem Sie mit JavaScript Eigenschaften für dieses verschachtelte Anfrageelement festlegen.

In diesem Abschnitt wird beschrieben, wie Sie beide Methoden implementieren.

Nearby Search

Damit Nutzer eine Nearby Search durchführen können, benötigen Sie zuerst ein UI-Element, über das sie einen Ortstyp auswählen können. Wählen Sie die Auswahlmethode aus, die am besten zu Ihrer Anwendung passt, z. B. eine Drop-down-Liste mit einer Auswahl von Ortstypen.

Es wird empfohlen, eine Teilmenge von Typen auszuwählen, die für Ihren Anwendungsfall relevant sind. Wenn Sie beispielsweise eine Anwendung entwickeln, um Touristen zu zeigen, was sich in der Nähe eines Hotels befindet, können Sie Folgendes auswählen: bakery, coffee_shop, museum, restaurant und tourist_attraction.

Ihr HTML-Code sollte das <gmp-place-search> Element mit einem <gmp-place-nearby-search-request> darin verschachtelten Element enthalten.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Erstellen Sie als Nächstes einen JavaScript-Listener für das change-Ereignis in der Ortstypauswahl. Dieser Listener ruft eine Funktion auf, die die Eigenschaften des <gmp-place-nearby-search-request> Elements aktualisiert. Dadurch wird automatisch eine neue Suche ausgelöst und die Liste aktualisiert.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

Für die locationRestriction wird derselbe searchCircle aus dem Einrichtungsschritt verwendet. Die Eigenschaft includedPrimaryTypes wird auf den Wert der Auswahl des Nutzers festgelegt. Optional kann auch maxResultCount festgelegt werden, um die Anzahl der Ergebnisse zu begrenzen.

Text Search

Um die Text Search zu aktivieren, muss Ihre HTML-Konfiguration geändert werden. Anstelle der Nearby Search-Anfrage fügen Sie ein <gmp-place-text-search-request> Element ein.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

Fügen Sie Ihrer Benutzeroberfläche eine Texteingabe und eine Suchschaltfläche hinzu. Erstellen Sie einen JavaScript-Listener für das click-Ereignis der Schaltfläche. Der Event-Handler übernimmt die Eingabe des Nutzers und aktualisiert die Eigenschaften des <gmp-place-text-search-request> Elements, um die Suche durchzuführen.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

Hier legen wir die Eigenschaft textQuery mit der Eingabe des Nutzers fest. Außerdem geben wir mit den aktuellen Kartenbegrenzungen eine locationBias an, mit der die API Ergebnisse in diesem Bereich bevorzugt, ohne sie jedoch streng darauf zu beschränken. Mit einem optionalen maxResultCount wird die Anzahl der zurückgegebenen Ergebnisse begrenzt.

Ortsmarkierungen und -details anzeigen

Jetzt kann die Anwendung eine Ortssuche durchführen und das Element ausfüllen. Im nächsten Schritt erweitern wir die Funktionalität durch Folgendes:

• Markierungen für jeden Ort, der im PlaceSearchElement angezeigt wird, auf der Karte anzeigen.
• Nutzern die Möglichkeit geben, entweder auf eine Markierung oder auf den Ort im PlaceSearchElement zu klicken, um weitere Details zu diesem Ort anzuzeigen.

Das Prinzip dieses Schritts ist dasselbe, unabhängig davon, ob die Anwendung eine Nearby Search oder eine Text Search verwendet.

Fügen Sie zuerst eine globale Variable zu Ihrem JavaScript-Code hinzu, um die Ortsmarkierungen zu speichern. So können Sie sie entfernen, wenn sich die Suche ändert, und Klickereignisse verarbeiten.

let markers = {};

Erstellen Sie eine Funktion, um der Karte Markierungen hinzuzufügen. Diese Funktion wird immer aufgerufen, wenn neue Suchergebnisse geladen werden. Sie führt folgende Schritte aus:

• Entfernt alle vorhandenen Ortsmarkierungen von der Karte.
• Durchläuft die Ergebnisse aus dem PlaceSearchElement und fügt für jedes Ergebnis eine Markierung hinzu.
• Passt die Begrenzungen der Karte so an, dass alle neuen Markierungen sichtbar sind.

Um zu erkennen, wann Suchergebnisse verfügbar sind, fügen Sie dem <gmp-place-search> Element einen gmp-load Ereignis-Listener hinzu. Dieses Ereignis wird ausgelöst, nachdem eine Suche abgeschlossen ist und die Ergebnisse gerendert wurden.

Wir fügen den Listener in unsere Suchfunktion ein (z.B. updatePlaceList) und verwenden die Option { once: true }, damit er nur für die Ergebnisse der aktuellen Suche ausgelöst wird.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

Die Funktion addMarkers sieht so aus:

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

Nach Abschluss dieses Schritts sieht die Anwendung so aus. Es können Markierungen für jeden Ort angezeigt werden, der vom PlaceSearchElement zurückgegeben wird:

Nachdem wir Markierungen auf der Karte haben, besteht der letzte Schritt darin, Klickereignisse für Markierungen und Elemente zu verarbeiten, um ein Infofenster mit Ortsdetails anzuzeigen, die vom Element „Place Details“ bereitgestellt werden. In diesem Beispiel verwenden wir das kompakte Element „Place Details“.

Fügen Sie Ihrem Code das HTML für das kompakte Element „Place Details“ hinzu, z. B.:

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

Der style ist auf display: none gesetzt. Er ist erst sichtbar, wenn er benötigt wird. gmp-place-all-content wird übergeben, um alle Elementinhalte zu rendern. Informationen dazu, welche Inhalte gerendert werden sollen, finden Sie in der Dokumentation zum kompakten Element „Place Details“.

Erstellen Sie in JavaScript eine globale Variable, um einen Verweis auf das kompakte Element „Place Details“ zu speichern, und füllen Sie sie in Ihrem Initialisierungscode aus, z. B.:

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

Fügen Sie in der Funktion addMarkers jedem Marker einen gmp-click-Ereignis-Listener hinzu und konfigurieren Sie das kompakte Element „Place Details“ so, dass die Ortsdetails angezeigt werden, indem Sie die Orts-ID des aktuellen Markers übergeben.

Anschließend wird ein Infofenster geöffnet, in dem das kompakte Element „Place Details“ angezeigt wird. Es ist am Marker verankert.

Schließlich wird die Karte auf den Darstellungsbereich des ausgewählten Orts positioniert, sodass er sichtbar ist.

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

Damit Nutzer auf einen Ort im Element „Place List“ klicken können, um das kompakte Element „Place Details“ anzuzeigen, fügen Sie dem JavaScript-Code nach dem Aufruf von configureFromSearchNearbyRequest Folgendes hinzu.

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

Nach diesem Schritt kann die Anwendung entweder die Nearby Search oder die Text Search verwenden, um das Element „Place List“ auszufüllen. Die Ergebnisse werden als Markierungen auf der Karte angezeigt. Wenn Sie auf eine Markierung oder einen Ort im Element „Place List“ klicken, wird ein Infofenster mit Ortsdetails angezeigt, die vom kompakten Element „Place Details“ bereitgestellt werden.

Die Anwendung sieht so aus:

Fazit

Das PlaceSearchElement in Kombination mit dem kompakten Element „Place Details“ bietet eine optimierte Möglichkeit, Ihren Google Maps Platform-Anwendungen umfassende Funktionen zur Ortssuche hinzuzufügen.

Testen Sie das Places UI Kit noch heute damit Ihre Nutzer Orte sowohl über die Nearby Search als auch die Text Search finden und erkunden können. Außerdem können Sie umfassende Ortsdetails anzeigen und so die Interaktion mit Ihren Anwendungsfällen für die Ortssuche verbessern.

Beitragende

Henrik Valve | DevX Engineer