Ziel
Hier erfahren Sie, wie Sie die PlaceSearchElement in Google Maps einbinden, damit Nutzer Orte über die Nearby Search oder die Text Search finden und so leichter interessante Orte entdecken können. Mit dem kompakten Element „Place Details“ können Sie weitere Details zu den Orten angeben, die in Ihrer Anwendung angezeigt werden.
Was ist der PlaceSearchElement?
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 eine Nearby Search oder eine Text Search gefunden wurden, und bietet 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 mithilfe eines Infofensters und des Place Details-Elements.
Ortsuche visualisieren
Die folgende Abbildung zeigt ein Beispiel für die PlaceSearchElement in Aktion. Auf der linken Seite wird eine Liste mit Restaurants (PlaceSearchElement) angezeigt. Wenn ein Restaurant ausgewählt wird, werden die Details in einem Infofenster auf der Karte angezeigt und die Karte wird auf den Standort des Restaurants 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 Gegend suchen.
- Immobilien:Potenzielle Käufer oder Mieter können Schulen, Supermärkte oder öffentliche Verkehrsmittel in der Nähe finden.
- Logistik und Dienstleistungen:Fahrer bei der Suche nach Ladestationen für Elektrofahrzeuge, Tankstellen oder bestimmten Servicecentern unterstützen.
Lösungsworkflow: Place Discovery implementieren
In diesem Abschnitt wird beschrieben, wie Sie das PlaceSearchElement einbinden, um Orte auf einer Karte zu finden. Außerdem finden Sie hier Code-Snippets für die Interaktion mit dem Places UI Kit. Hier erfahren Sie, wie Sie die Karte initialisieren und sowohl Nearby Search als auch Text Search implementieren. Mit dem Element „Place Details“ können Sie weitere Details zu einem Ort anzeigen, wenn ein Nutzer auf die entsprechende Markierung auf der Karte klickt.
Vorbereitung
Es wird empfohlen, sich mit der folgenden Dokumentation vertraut zu machen:
PlaceSearchElement– Wird verwendet, um Orte mit Nearby Search oder Text Search anzuzeigen.- Place Details-Element: 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. In diesem Dokument wird auch davon ausgegangen, dass Sie mit der Webentwicklung vertraut sind, einschließlich HTML, CSS und JavaScript.
Karte zur Seite hinzufügen
Als Erstes fügen Sie Ihrer Seite eine Karte hinzu. Diese Karte wird verwendet, um PlaceSearchElement-Ergebnisse als auswählbare Markierungen anzuzeigen.
Es gibt zwei Möglichkeiten, einer Seite eine Karte hinzuzufügen:
- Verwendung einer HTML-Webkomponente vom Typ
gmp-map. - JavaScript verwenden.
Die Code-Snippets auf dieser Seite wurden mit einer JavaScript-Map 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. In diesem Dokument verwenden wir einen festen Standort, um die Suche zu verankern.
Wenn Sie Orte in der Nähe eines festen Standorts wie eines Hotels visualisieren, platzieren Sie eine Markierung auf der Karte, um diesen Ort darzustellen. Beispiel:
Die Karte ist auf San Francisco zentriert. Eine blaue Markierung zeigt den Ort an, in dessen Nähe wir suchen. Die Farbe der Markierung wurde mit PinElement angepasst.
Die Steuerung für den Kartentyp wurde auf der Benutzeroberfläche ausgeblendet.
PlaceSearchElement einrichten
Richten Sie jetzt den HTML- und CSS-Code ein, um die PlaceSearchElement anzuzeigen. In diesem Beispiel wird das Element links auf der Karte eingeblendet. Sie können aber auch andere Layouts ausprobieren, die zu Ihrer Anwendung passen.
PlaceSearchElement verwendet einen deklarativen Ansatz. Anstatt die Suche 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 der Hauptkomponente <gmp-place-search> verschachteln.
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>-Element 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, verwenden wir JavaScript, um einen Verweis auf das verschachtelte Anfrageelement zu erhalten und seine Eigenschaften festzulegen. Initialisieren Sie einen Kreis, der als locationRestriction verwendet werden soll. Verwenden Sie dabei die Markierungsposition 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'];
So könnte die Anwendung in dieser Phase aussehen:
Nutzer die Suche erlauben
Der PlaceSearchElement bietet zwei Suchoptionen:
<gmp-place-nearby-search-request>: Suchergebnisse aus einer Nearby Search mit Ortstypen rendern.<gmp-place-text-search-request>: Suchergebnisse aus einer Places Text Search werden mit einer Freitexteingabe wie „Sushi in San Francisco“ gerendert.
Dies sind verschachtelte Elemente in <gmp-place-search>. Anschließend lösen Sie Suchvorgänge aus, indem Sie mit JavaScript Attribute für dieses verschachtelte Anfrageelement festlegen.
In diesem Abschnitt wird die Implementierung beider Methoden beschrieben.
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 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önnen Sie Folgendes auswählen: bakery, coffee_shop, museum, restaurant und tourist_attraction.
Ihr HTML-Code sollte das Element <gmp-place-search> mit einem verschachtelten <gmp-place-nearby-search-request> 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 Ortsauswahl. 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 aus dem Einrichtungsschritt verwendet. Die Eigenschaft includedPrimaryTypes wird auf den Wert der Auswahl des Nutzers festgelegt. Ein optionales maxResultCount wird ebenfalls festgelegt, um die Anzahl der Ergebnisse zu begrenzen.
Text Search
Wenn Sie die Textsuche aktivieren möchten, müssen Sie Ihre HTML-Konfiguration ändern. Anstelle der Nearby Search-Anfrage 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 ein Texteingabefeld und eine Suchschaltfläche hinzu. Erstellen Sie einen JavaScript-Listener für das click-Ereignis der Schaltfläche. Der Event-Handler nimmt die Eingabe des Nutzers entgegen und aktualisiert die Attribute 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 Property textQuery mit der Eingabe des Nutzers fest. Außerdem stellen wir einen locationBias-Wert bereit, der die aktuellen Kartengrenzen verwendet. Dadurch wird die API angewiesen, Ergebnisse innerhalb dieses Bereichs zu bevorzugen, ohne sie strikt 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 füllen. Im nächsten Schritt erweitern wir die Funktionalität:
- Anzeigen von Markierungen auf der Karte für jeden Ort, der in der
PlaceSearchElementangegeben ist. - Nutzer können auf eine Markierung oder den Ort in der
PlaceSearchElementklicken, um weitere Details zu diesem Ort aufzurufen.
Das Prinzip dieses Schritts ist dasselbe, unabhängig davon, ob die Anwendung eine Nearby Search oder eine Text Search verwendet.
Fügen Sie zuerst Ihrem JavaScript-Code eine globale Variable hinzu, um die Ortsmarkierungen zu speichern. So kannst du 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 aufgerufen, wenn neue Suchergebnisse geladen werden. Das bedeutet:
- Entfernen Sie alle vorhandenen Ortsmarkierungen von der Karte.
- Gehen Sie die Ergebnisse des
PlaceSearchElementdurch und fügen Sie für jedes Ergebnis eine Markierung hinzu. - Passen Sie die Grenzen der Karte an, damit alle neuen Markierungen sichtbar sind.
Wenn Sie wissen möchten, wann 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 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);
}
}
Nachdem dieser Schritt abgeschlossen ist, sieht die Anwendung so aus und kann Markierungen für jeden Ort anzeigen, der von der PlaceSearchElement zurückgegeben wird:
Nachdem wir Markierungen auf der Karte haben, müssen wir im letzten Schritt Click-Events für Markierungen und Elemente 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 den HTML-Code für das kompakte Element „Place Details“ in Ihren Code ein, 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>
style ist auf display: none festgelegt und wird erst angezeigt, wenn es erforderlich ist.
gmp-place-all-content wird übergeben, um den gesamten Elementinhalt zu rendern. Informationen zur Auswahl der zu rendernden Inhalte finden Sie in der Dokumentation zum kompakten Place Details Element.
Erstellen Sie in JavaScript eine globale Variable, die einen Verweis auf das kompakte Element für Ortsdetails enthält, 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 jeder Markierung einen gmp-click-Event-Listener hinzu und konfigurieren Sie das kompakte Element für Place Details so, dass die Place Details angezeigt werden, indem Sie die Orts-ID der aktuellen Markierung übergeben.
Anschließend wird ein Infofenster geöffnet, in dem das kompakte Element für Place Details angezeigt wird, das an der Markierung verankert ist.
Schließlich wird die Karte auf den Darstellungsbereich des ausgewählten Ortes 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 });
});
});
...
});
}
}
Wenn Sie dem Nutzer die Möglichkeit geben möchten, auf einen Ort im Element „Place List“ zu klicken, um das Element „Place Details Compact“ 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();
}
});
Nachdem dieser Schritt abgeschlossen ist, kann die Anwendung entweder die Nearby Search oder die Text Search verwenden, um das Element „Place List“ zu fü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 Element „Place Details Compact“ bereitgestellt werden.
Die Anwendung sieht so aus:
Fazit
Die PlaceSearchElement bietet in Kombination mit dem kompakten Element „Place Details“ eine optimierte Möglichkeit, Ihren Google Maps Platform-Anwendungen umfangreiche Funktionen zur Ortssuche hinzuzufügen.
Mit dem Places UI Kit können Nutzer Orte über die Suche nach Orten in der Nähe und die Textsuche finden und erkunden. Außerdem lassen sich umfangreiche Ortsdetails anzeigen, was die Interaktion mit Ihren Anwendungsfällen für die Ortssuche verbessert.
Beitragende
Henrik Valve | DevX Engineer