Ziel
Hier erfahren Sie, wie Sie das Place Search-Element in Google Maps einbinden, damit Nutzer Orte über die Nearby Search oder die Text Search finden und so interessante Orte leichter erkunden können. Mit dem Place Details Compact-Element können Sie weitere Details zu den Orten bereitstellen, die in Ihrer Anwendung angezeigt werden.
Was ist das Place Search-Element?
Das Place Search-Element ist Teil des Places UI Kits in der Maps JavaScript API. Es ist ein HTML-Element, mit dem die Ergebnisse einer Ortssuche direkt in einem Listenformat in Ihrer Anwendung gerendert werden. 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 Suche nach Orten. 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 Place Details-Element.
Suche nach Orten visualisieren
Die folgende Abbildung zeigt ein Beispiel für das Place Search-Element in Aktion. Links wird eine Liste von Restaurants angezeigt (das Place Search-Element). 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 Suche nach Orten
Durch die Einbindung des Place Search-Elements können verschiedene Anwendungen in unterschiedlichen Branchen verbessert werden:
- 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 nach Ladestationen für Elektrofahrzeuge, Tankstellen oder bestimmten Servicecentern suchen.
Solution Workflow: Suche nach Orten implementieren
In diesem Abschnitt werden die Schritte zur Einbindung des Place Search-Elements für die Suche nach Orten auf einer Karte beschrieben. Außerdem finden Sie Code-Snippets für die Interaktion mit dem Places UI Kit. Wir behandeln die Initialisierung der Karte und die Implementierung der Nearby Search- und Text Search-Funktionen. Schließlich verwenden wir das Place Details-Element, um weitere Details zu einem bestimmten Ort anzuzeigen, wenn auf die 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 entweder über die Nearby Search oder die Text Search zu finden
- 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 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
Im ersten Schritt fügen Sie Ihrer Seite eine Karte hinzu. 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-mapHTML-Web komponente. - 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 für den Kartentyp wurde auf der Benutzeroberfläche ausgeblendet.
Place Search-Element einrichten
Jetzt können wir das HTML und CSS einrichten, um das Place Search-Element anzuzeigen. In diesem Beispiel wird das Element links neben der Karte platziert. Es wird jedoch empfohlen, verschiedene Layouts auszuprobieren, die zu Ihrer Anwendung passen.
Das Place Search-Element 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 im 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'];
So könnte die Anwendung in dieser Phase aussehen:
Nutzern die Suche ermöglichen
Das Place Search-Element 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 Orte Text Search mit einer Freitext Eingabe wie „Sushi in San Francisco“ rendern.
Dies 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 die Implementierung beider Methoden beschrieben.
Nearby Search
Damit Nutzer eine Nearby Search durchführen können, benötigen Sie zuerst ein UI-Element, mit dem 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> 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 Ereignis change für die Auswahl des Ortstyps. 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 wie im 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 Ereignis click der Schaltfläche. Der Ereignishandler ü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 dem 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 auf der Karte anzeigen, der im Place Search-Element enthalten ist.
- Nutzern die Möglichkeit geben, entweder auf eine Markierung oder auf den Ort im Place Search-Element 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 aufgerufen, wenn neue Suchergebnisse geladen werden. Sie führt folgende Schritte aus:
- Entfernt alle vorhandenen Ortsmarkierungen von der Karte.
- Durchläuft die Ergebnisse des Place Search-Elements 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 Place Search-Element zurückgegeben wird:
Nachdem wir Markierungen auf der Karte haben, müssen wir im letzten Schritt Klickereignisse 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 Place Details Compact Element.
Fügen Sie Ihrem Code das HTML für das Place Details Compact-Element 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 Place Details Compact
Element.
Erstellen Sie in JavaScript eine globale Variable, um einen Verweis auf das Place Details Compact-Element 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 Place Details Compact-Element 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 Place Details Compact-Element 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 Place List-Element klicken können, um das Place Details Compact-Element 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 Abschluss dieses Schritts kann die Anwendung entweder eine Nearby Search oder eine Text Search verwenden, um das Place List-Element auszufüllen. Die Ergebnisse werden als Markierungen auf der Karte angezeigt. Wenn Sie auf eine Markierung oder einen Ort im Place List-Element klicken, wird ein Infofenster mit Ortsdetails angezeigt, die vom Place Details Compact-Element 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 umfassende Funktionen zur Suche nach Orten hinzuzufügen.
Testen Sie das Places UI Kit noch heute damit Ihre Nutzer Orte sowohl über die Nearby Search als auch über die Text Search finden und erkunden können. Außerdem können Sie umfassende Ortsdetails anzeigen und so die Interaktion mit Ihren Anwendungsfällen zur Suche nach Orten verbessern.
Beitragende
Henrik Valve | DevX Engineer