Ziel
Hier erfahren Sie, wie Sie das Place Search-Element in Google Maps einbinden, damit Nutzer mithilfe der Suche in der Nähe oder der Textsuche Orte finden und so interessante Orte besser erkunden können. Mit dem kompakten Place Details-Element können Sie weitere Details zu den in Ihrer Anwendung angezeigten Orten bereitstellen.
durch.Was ist das „Place Search“-Element?
Das Place Search Element ist Teil des Places UI Kit in der Maps JavaScript API. Es handelt sich um ein HTML-Element, mit dem die Ergebnisse einer Ortssuche direkt in einem Listenformat in Ihrer Anwendung gerendert werden. Dieses Element vereinfacht die Darstellung von Orten, die mit einer Nearby Search oder einer Text Search gefunden wurden, und bietet so eine nahtlose Nutzererfahrung bei der Suche nach Orten. Wenn ein Nutzer einen Ort aus der Liste auswählt, können Sie die Details auf der Karte anzeigen, in der Regel mit einem Infofenster und dem Place Details-Element.
Orte visualisieren
Das folgende Bild zeigt ein Beispiel für das Place Search-Element in Aktion. Links wird eine Liste mit Restaurants angezeigt (das Place Search-Element). Wenn ein Restaurant ausgewählt wird, werden seine Details in einem Infofenster auf der Karte angezeigt und die Karte wird auf den Standort des Restaurants zentriert.
Anwendungsfälle für die Ortsermittlung
Die Einbindung des Place Search-Elements kann verschiedene Anwendungen in unterschiedlichen Branchen verbessern:
- Reisen und Tourismus:Touristen können nach Attraktionen, Hotels oder bestimmten Arten von Küche in einer Region suchen.
- Immobilien:Potenzielle Käufer oder Mieter können so Schulen, Supermärkte oder öffentliche Verkehrsmittel in der Nähe finden.
- Logistik und Dienste:Fahrern helfen, Ladestationen für Elektrofahrzeuge, Tankstellen oder bestimmte Servicecenter zu finden.
Lösungsworkflow: Place Discovery implementieren
In diesem Abschnitt erfahren Sie, wie Sie das Place Search-Element einbinden, um Orte auf einer Karte zu finden. Außerdem finden Sie Code-Snippets für die Interaktion mit dem Places UI Kit. Wir werden die Initialisierung der Karte und die Implementierung der Funktionen „Suche in der Nähe“ und „Textsuche“ behandeln. Schließlich verwenden wir das Element „PlaceDetails“, um weitere Details zu einem bestimmten Ort anzuzeigen, wenn auf die entsprechende Markierung auf der Karte geklickt wird.
Vorbereitung
Es wird empfohlen, sich mit der folgenden Dokumentation vertraut zu machen:
- Place Search Element: Wird verwendet, um Orte mithilfe von „Nearby Search“ oder „Text Search“ zu präsentieren.
- 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 die Maps JavaScript API und das Places UI Kit für Ihr Projekt.
Prüfen Sie, ob Sie die Maps JavaScript API geladen und die erforderlichen Bibliotheken importiert haben, bevor Sie beginnen. Außerdem wird in diesem Dokument davon ausgegangen, dass Sie mit der Webentwicklung vertraut sind, einschließlich HTML, CSS und JavaScript.
Karte auf der Seite einfügen
Als Erstes müssen Sie Ihrer Seite eine Karte hinzufügen. Auf dieser Karte werden die Ergebnisse des Place Search-Elements als auswählbare Markierungen angezeigt.
Es gibt zwei Möglichkeiten, einer Seite eine Karte hinzuzufügen:
- Mit einer
gmp-map-HTML-Webkomponente. - JavaScript verwenden.
Die Code-Snippets auf dieser Seite wurden mit einer JavaScript-Karte generiert.
Die Karte kann entweder auf einen Ort zentriert werden, an dem 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. In diesem Dokument verwenden wir einen festen Ort, um die Suche zu verankern.
Wenn Sie Orte in der Nähe eines festen Standorts, z. B. eines Hotels, visualisieren, fügen Sie einen Marker auf der Karte ein, um diesen Ort darzustellen. Beispiel:
Die Karte ist auf San Francisco zentriert. Ein blauer Pin kennzeichnet den Ort, in dessen Nähe wir suchen. Die Farbe der Markierung wurde mit PinElement angepasst.
Die Steuerung für den Kartentyp wurde aus der Benutzeroberfläche ausgeblendet.
„Place Search“-Element einrichten
Jetzt können wir das HTML und CSS für die Anzeige des Elements für die Ortssuche einrichten. In diesem Beispiel wird das Element links auf der Karte platziert. Wir empfehlen jedoch, verschiedene Layouts auszuprobieren, um das beste für Ihre Anwendung zu finden.
Das Place Search Element verwendet einen deklarativen Ansatz. Anstatt die Konfiguration vollständig in JavaScript vorzunehmen, 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> einbetten.
Initialisieren Sie in Ihrem HTML-Code ein <gmp-place-search>-Element. Verwenden Sie das Attribut selectable, um Click-Events für die Ergebnisse zu aktivieren. Fügen Sie darin ein <gmp-place-nearby-search-request> ein, um anzugeben, dass dieses Element für die Suche in der Nähe verwendet wird.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
Für die erste Suche und die Anzeige der Ergebnisse verwenden wir JavaScript, um eine Referenz zum verschachtelten Anfrageelement abzurufen und seine Eigenschaften festzulegen. Initialisieren Sie einen Kreis, der als locationRestriction verwendet werden soll, und verwenden Sie die Markerposition aus dem vorherigen Schritt als Mittelpunkt. Legen Sie dann die Attribute 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:
Nutzern die Suche erlauben
Das Place Search-Element bietet zwei Suchoptionen:
<gmp-place-nearby-search-request>– Suchergebnisse aus einer Places Nearby Search (Suche in der Nähe) mit Place Types (Ortsarten) rendern.<gmp-place-text-search-request>– Suchergebnisse aus einer Places Text Search mit einer Freitext-Eingabe wie „Sushi in San Francisco“ rendern.
Dies sind verschachtelte Elemente innerhalb von <gmp-place-search>. Anschließend lösen Sie Suchvorgänge aus, indem Sie mit JavaScript Eigenschaften für dieses verschachtelte Anfrageelement festlegen.
In diesem Abschnitt wird beschrieben, wie Sie beide Methoden implementieren.
Suche in der Nähe
Damit Nutzer eine Suche in der Nähe 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 für Ihre Anwendung am besten geeignet ist, 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, die Touristen zeigt, was sich in der Nähe eines Hotels befindet, könnten Sie bakery, coffee_shop, museum, restaurant und tourist_attraction auswählen.
Ihr HTML-Code sollte das <gmp-place-search>-Element mit einem darin verschachtelten <gmp-place-nearby-search-request>-Element enthalten.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
Als Nächstes erstellen Sie einen JavaScript-Listener für das change-Ereignis in der Auswahl für den Ortstyp. 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 dieselbe searchCircle wie im Einrichtungsschritt verwendet. Die Eigenschaft includedPrimaryTypes wird auf den Wert aus der Auswahl des Nutzers festgelegt. Außerdem wird optional ein maxResultCount festgelegt, um die Anzahl der Ergebnisse zu begrenzen.
Text Search
Damit die Textsuche aktiviert werden kann, muss Ihre HTML-Konfiguration geändert werden. Anstelle der Anfrage für die Suche in der Nähe verschachteln Sie ein <gmp-place-text-search-request>-Element.
<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 Schaltfläche für die Suche hinzu. Erstellen Sie einen JavaScript-Listener für das click-Ereignis der Schaltfläche. Der Ereignishandler nimmt die Eingabe des Nutzers entgegen und aktualisiert die Eigenschaften des <gmp-place-text-search-request>-Elements, um die Suche auszufü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 stellen wir einen locationBias mit den aktuellen Kartenbegrenzungen bereit. Damit wird die API angewiesen, Ergebnisse in diesem Bereich zu bevorzugen, ohne sie 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 damit füllen. Im nächsten Schritt werden wir die Funktionalität verbessern, indem wir:
- Für jeden Ort, der im Element „Place Search“ angegeben ist, werden Markierungen auf der Karte angezeigt.
- Wenn ein Nutzer auf eine Markierung oder den Ort im Place Search-Element klickt, werden weitere Details zu diesem Ort angezeigt.
Das Prinzip dieses Schritts ist dasselbe, unabhängig davon, ob die Anwendung eine Suche in der Nähe oder eine Textsuche verwendet.
Fügen Sie zuerst eine globale Variable in Ihren JavaScript-Code ein, 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 zum Hinzufügen von Markierungen zur Karte. Diese Funktion wird immer dann aufgerufen, wenn neue Suchergebnisse geladen werden. Das hat folgende Auswirkungen:
- Entfernen Sie alle vorhandenen Ortsmarkierungen von der Karte.
- Die Ergebnisse des Place Search-Elements durchlaufen und für jedes Ergebnis eine Markierung hinzufügen.
- Passen Sie die Grenzen der Karte an, damit alle neuen Markierungen sichtbar sind.
Wenn Sie darauf warten möchten, dass Suchergebnisse verfügbar sind, fügen Sie dem <gmp-place-search>-Element einen gmp-load-Event-Listener hinzu. Dieses Ereignis wird ausgelöst, nachdem eine Suche abgeschlossen und die Ergebnisse gerendert wurden.
Wir fügen den Listener in unsere Suchfunktion ein (z.B. updatePlaceList) und verwenden Sie die Option { once: true }, damit sie 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 addMarkers-Funktion 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. Sie kann Markierungen für jeden Ort anzeigen, der vom Place Search Element zurückgegeben wird:
Nachdem wir Markierungen auf der Karte haben, müssen wir im letzten Schritt Markierungs- und Element-Click-Events verarbeiten, um ein Infofenster mit Ortsdetails anzuzeigen, die vom Place Details-Element bereitgestellt werden. In diesem Beispiel verwenden wir das kompakte Element „Place Details“.
Fügen Sie Ihrem Code das HTML-Element „Place Details Compact“ 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>
Die style ist auf display: none festgelegt und wird erst angezeigt, wenn sie 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 „Ortsdetails“.
Erstellen Sie in JavaScript eine globale Variable, die eine Referenz auf das kompakte Element „Ortsdetails“ enthält, und füllen Sie diese in Ihrem Initialisierungscode aus, z. B.:
let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');
Fügen Sie in der Funktion addMarkers jeder Markierung einen gmp-click-Event-Listener hinzu und konfigurieren Sie das kompakte Element „Ortsdetails“ so, dass die Ortsdetails durch Übergabe der Orts-ID der aktuellen Markierung angezeigt werden.
Anschließend wird ein Infofenster geöffnet, in dem das kompakte Element mit den Ortsdetails angezeigt wird. Es ist an der Markierung verankert.
Schließlich wird die Karte so positioniert, dass der Darstellungsbereich des ausgewählten Orts 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 der Nutzer auf einen Ort im Element „Ortsliste“ klicken kann, um das kompakte Element „Ortsdetails“ aufzurufen, 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 Abschluss dieses Schritts kann die Anwendung entweder eine Nearby Search oder eine Text Search verwenden, um das Place List Element zu füllen. Die Ergebnisse werden auf der Karte mit Markierungen angezeigt. Wenn Sie auf eine Markierung oder einen Ort im Element „Ortsliste“ klicken, wird ein Infofenster mit Ortsdetails eingeblendet, die vom Element „Kompakte Ortsdetails“ bereitgestellt werden.
Die Anwendung sieht so aus:
Fazit
Das Place Search-Element in Kombination mit dem Place Details Compact-Element bietet eine optimierte Möglichkeit, Ihren Google Maps Platform-Anwendungen umfangreiche Funktionen zur Ortsermittlung hinzuzufügen.
Mit dem Places UI Kit können Sie Nutzern die Möglichkeit geben, Orte über Nearby Search und Text Search zu finden und zu erkunden. Außerdem können Sie umfangreiche Ortsdetails anzeigen, um die Interaktion mit Ihren Anwendungsfällen für die Ortssuche zu verbessern.
Beitragende
Henrik Valve | DevX Engineer