Objectif
Découvrez comment intégrer l'élément de recherche de lieu à Google Maps pour aider les utilisateurs à trouver des lieux à l'aide de la recherche à proximité ou de la recherche par texte, ce qui leur permet d'explorer plus facilement les points d'intérêt. Utilisez l'élément Place Details Compact pour fournir plus d'informations sur les lieux affichés dans votre application.
Qu'est-ce que l'élément de recherche de lieu ?
L'élément de recherche de lieu fait partie du kit d'UI Places de l'API Maps JavaScript. Il s'agit d'un élément HTML qui affiche les résultats d'une recherche de lieu directement au format liste dans votre application. Cet élément simplifie le processus d'affichage des lieux trouvés à l'aide d'une recherche à proximité ou d'une recherche par texte, offrant une expérience utilisateur fluide pour la découverte de lieux. Lorsqu'un utilisateur sélectionne un lieu dans la liste, vous pouvez afficher ses détails sur la carte, souvent à l'aide d'une fenêtre d'informations et de l'élément "Détails du lieu".
Visualiser la découverte de lieux
L'image suivante montre un exemple de l'élément de recherche de lieu en action. À gauche, une liste de restaurants s'affiche (élément de recherche de lieu). Lorsqu'un restaurant est sélectionné, ses informations s'affichent dans une fenêtre d'informations sur la carte, et la carte se centre sur son emplacement.
Cas d'utilisation de la découverte de lieux
L'intégration de l'élément de recherche de lieux peut améliorer diverses applications dans différents secteurs:
- Voyages et tourisme:permet aux touristes de rechercher des attractions, des hôtels ou des types de cuisine spécifiques dans une région.
- Immobilier:permettez aux acheteurs ou locataires potentiels de trouver des écoles, des supermarchés ou des options de transports en commun à proximité.
- Logistique et services:aidez les conducteurs à trouver des bornes de recharge de VE, des stations-service ou des centres de service spécifiques.
Workflow de la solution: implémenter la découverte de lieux
Cette section vous explique comment intégrer l'élément de recherche de lieu pour découvrir des lieux sur une carte, y compris des extraits de code permettant d'interagir avec le kit d'UI Places. Nous allons voir comment initialiser la carte et implémenter les fonctionnalités de recherche dans les environs et de recherche par texte. Enfin, nous utiliserons l'élément "PlaceDetails" pour afficher plus d'informations sur un lieu particulier lorsque vous cliquez sur son épingle sur la carte.
Prérequis
Il est recommandé de connaître la documentation suivante:
- Élément de recherche de lieu : permet d'afficher des lieux à l'aide de Nearby Search ou de Text Search.
- Élément Place Details : permet d'afficher les détails d'un lieu spécifique.
- API Maps JavaScript : permet d'afficher une carte sur votre page et d'importer l'UI Kit Places
Activez l'API Maps JavaScript et le kit d'UI Places dans votre projet.
Avant de commencer, vérifiez que vous avez chargé l'API Maps JavaScript et importé les bibliothèques requises. Ce document suppose également que vous avez des connaissances pratiques en développement Web, y compris en HTML, CSS et JavaScript.
Ajouter une carte à la page
La première étape consiste à ajouter une carte à votre page. Cette carte sera utilisée pour afficher les résultats de l'élément de recherche de lieu sous la forme d'épingles sélectionnables.
Vous pouvez ajouter une carte à une page de deux manières:
- À l'aide d'un composant Web HTML
gmp-map. - à l'aide de JavaScript ;
Les extraits de code de cette page ont été générés à l'aide d'une carte JavaScript.
La carte peut être centrée sur un lieu que vous souhaitez que l'utilisateur recherche à proximité, comme un hôtel, ou être initialisée pour demander à l'utilisateur sa position actuelle afin de centrer la carte. Pour les besoins de ce document, nous allons utiliser un emplacement fixe pour ancrer la recherche.
Si vous visualisez des lieux à proximité d'un lieu fixe, comme un hôtel, placez un repère sur la carte pour représenter ce lieu. Exemple :
La carte est centrée sur San Francisco, avec un repère bleu représentant le lieu que nous recherchons à proximité. La couleur de la punaise a été personnalisée à l'aide de PinElement.
La commande de type de carte a été masquée de l'UI.
Configurer l'élément Place Search
Nous pouvons maintenant configurer le code HTML et CSS pour afficher l'élément de recherche de lieu. Pour cet exemple, nous allons faire flotter l'élément sur le côté gauche de la carte, mais nous vous recommandons d'essayer différentes mises en page en fonction de votre application.
Dans votre code HTML, créez un div qui contiendra l'élément de recherche de lieu.
Dans ce cas, initialisez un gmp-place-list vide.
Utilisez l'attribut selectable avec gmp-place-list to pour activer les événements de clic sur l'élément.
<gmp-place-list selectable></gmp-place-list>
À ce stade, utilisez configureFromSearchNearbyRequest pour rechercher un type d'établissement afin de vérifier que les résultats sont correctement affichés.
Utilisez JavaScript pour configurer l'élément de recherche de lieu afin d'afficher les résultats d'une recherche de lieu. Initialisez un cercle à utiliser comme locationRestriction, à l'aide d'un point central et d'un rayon approprié. Pour cet exemple, l'élément est configuré pour rechercher un type d'établissement restaurant, et la position du repère définie à l'étape précédente est utilisée comme point central du cercle.
L'extrait de code correspondant est le suivant:
const placeListElement = document.querySelector("gmp-place-list");
const circleRestriction = new Circle({
center: marker.position,
radius: 500
});
placeListElement.configureFromSearchNearbyRequest({
locationRestriction: circleRestriction,
includedPrimaryTypes: ['restaurant'],
});
Voici un exemple de ce à quoi pourrait ressembler l'application à ce stade:
Autoriser l'utilisateur à effectuer une recherche
L'élément de recherche de lieu propose deux options de recherche:
configureFromSearchNearbyRequest: affichez les résultats de recherche à partir d'une recherche Places à proximité à l'aide de types d'établissements.configureFromSearchByTextRequest: affichez les résultats de recherche d'une recherche textuelle dans Places à l'aide d'une saisie de texte libre, par exemple "Sushi à San Francisco".
Cette section décrit l'implémentation des deux méthodes.
Recherche à proximité
Implémentez un élément d'interface utilisateur pour permettre à l'utilisateur de choisir le type de lieu que l'élément de recherche de lieu affichera. Nous vous recommandons de choisir un sous-ensemble de ces types, en fonction de votre cas d'utilisation. Par exemple, si vous développez une application pour montrer aux touristes ce qui se trouve à proximité d'un hôtel, vous pouvez choisir: bakery, coffee_shop, museum, restaurant et tourist_attraction. Choisissez la méthode de sélection la plus adaptée à votre application, par exemple une liste déroulante contenant une sélection de types de lieux.
Créez un écouteur JavaScript pour gérer l'événement de modification dans l'UI de sélection du type de lieu. Configurez l'écouteur pour qu'il appelle une fonction permettant de mettre à jour l'élément de recherche de lieu en fonction du type de lieu sélectionné, à l'aide de configureFromSearchNearbyRequest.
Voici un exemple de mise à jour de l'élément de recherche de lieu à l'aide d'une fonction:
// Function to update the place search
function updatePlaceList() {
const selectedType = placeTypeSelect.value;
if (!selectedType) {
console.warn("No place type selected.");
// Clear results or handle as needed
placeListElement.requestedResultTypes = [];
return;
}
placeListElement.configureFromSearchNearbyRequest({
locationRestriction: searchCircle,
maxResultCount: 8,
includedPrimaryTypes: [selectedType],
});
}
Le même cercle locationRestriction configuré à l'étape précédente est utilisé. Le paramètre includedPrimaryTypes est défini en fonction de la valeur sélectionnée dans l'UI.
Un maxResultCount facultatif a également été défini pour limiter le nombre de résultats renvoyés et affichés dans l'élément de recherche de lieu.
Text Search
Ajoutez une zone de saisie de texte avec un bouton permettant à vos utilisateurs de saisir leur recherche textuelle. Créez un écouteur JavaScript pour gérer l'événement click sur le bouton, puis configurez l'élément de recherche de lieu pour qu'il recherche à l'aide de la chaîne de recherche saisie, à l'aide de configureFromSearchByTextRequest.
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;
}
placeListElement.configureFromSearchByTextRequest({
textQuery: query,
locationRestriction: map.getBounds(),
maxResultCount: 8,
});
}
Pour cet exemple, un locationRestriction facultatif est défini à l'aide des limites actuelles de la carte. La requête de recherche est transmise à l'aide du paramètre textQuery.
Un maxResultCount facultatif a également été défini pour limiter le nombre de résultats renvoyés et affichés dans l'élément de recherche de lieu.
Afficher les repères et les détails des lieux
L'application peut désormais effectuer une recherche de lieu et renseigner l'élément. À l'étape suivante, nous allons améliorer ses fonctionnalités en:
- Affichage de repères sur la carte pour chaque lieu renseigné dans l'élément de recherche de lieu.
- Permettre à un utilisateur de cliquer sur une épingle ou sur le lieu dans l'élément de recherche de lieu pour afficher plus d'informations sur ce lieu particulier.
Le principe de cette étape est le même, que l'application utilise configureFromSearchNearbyRequest ou configureFromSearchByTextRequest. Pour cet exemple, nous allons utiliser configureFromSearchNearbyRequest.
Ajoutez une variable globale à votre code JavaScript pour stocker les repères géographiques. Vous pourrez ainsi les supprimer lorsque la recherche change et gérer les événements de clic pour afficher les détails du lieu.
let markers = {};
Ajoutez une fonction à:
- Supprimez les repères géographiques existants.
- Parcourez les résultats de l'élément de recherche de lieu et ajoutez un repère pour chacun d'eux.
- Définissez les limites de la carte afin que tous les repères soient visibles.
async function addMarkers() {
const { LatLngBounds } = await google.maps.importLibrary("core");
const bounds = new LatLngBounds();
if (placeListElement.places.length > 0) {
// Remove existing markers
for (m in markers) {
markers[m].map = null;
}
markers = {};
// Loop through each place in the Place Search Element
// Add a marker for each place
placeListElement.places.forEach((place) => {
let marker = new AdvancedMarkerElement({
map: map,
position: place.location,
});
markers[place.id] = marker;
bounds.extend(place.location);
marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
// Position the map to display all markers with the bounds
map.setCenter(bounds.getCenter());
map.fitBounds(bounds);
});
}
}
Enfin, une fois la promesse configureFromSearchNearbyRequest résolue, appelez la nouvelle fonction addMarkers(), comme suit:
placeListElement.configureFromSearchNearbyRequest({
locationRestriction: searchCircle,
maxResultCount: 8,
includedPrimaryTypes: [selectedType],
}).then(addMarkers);
Une fois cette étape terminée, l'application ressemblera à celle ci-dessous, avec la possibilité d'afficher des repères pour chaque lieu renvoyé par l'élément de recherche de lieu:
Maintenant que nous avons des repères sur la carte, la dernière étape consiste à gérer les événements de clic sur les repères et les éléments pour afficher une fenêtre d'informations avec des informations sur le lieu, fournies par l'élément Place Details. Pour cet exemple, nous utiliserons l'élément compact "Place Details".
Ajoutez le code HTML de l'élément compact "Détails du lieu" à votre code, par exemple:
<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 est défini sur display: none. Il ne sera pas visible tant qu'il n'est pas requis.
gmp-place-all-content est transmis pour afficher tout le contenu de l'élément. Pour choisir le contenu à afficher, consultez la documentation sur l'élément Place Details Compact.
Créez une variable globale en JavaScript pour contenir une référence à l'élément compact "Place Details" (Détails du lieu), puis renseignez-la dans votre code d'initialisation, par exemple:
let placeDetailsElement;
…
placeDetailsElement = document.querySelector('gmp-place-details-compact');
Dans la fonction addMarkers, ajoutez un écouteur d'événement gmp-click à chaque repère et configurez l'élément compact "Place Details" (Détails du lieu) pour afficher les détails du lieu en transmettant l'ID du lieu du repère actuel.
Une fois cette opération effectuée, une fenêtre d'informations s'ouvre pour afficher l'élément compact "Détails du lieu", ancré au repère.
Enfin, la carte est positionnée dans la fenêtre d'affichage du lieu sélectionné, ce qui le rend visible.
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 });
});
});
...
});
}
}
Pour permettre à l'utilisateur de cliquer sur un lieu dans l'élément de liste des lieux afin d'afficher l'élément compact "Place Details", ajoutez le code JavaScript suivant après l'appel à configureFromSearchNearbyRequest.
placeListElement.addEventListener("gmp-placeselect", ({ place }) => {
markers[place.id].click();
});
Une fois cette étape terminée, l'application pourra utiliser une recherche à proximité ou une recherche par texte pour renseigner l'élément de liste de lieux. Les résultats s'affichent sous forme d'épingles sur la carte. Si vous cliquez sur une épingle ou un lieu dans l'élément "Liste de lieux", une fenêtre d'informations s'affiche avec les détails du lieu, fournis par l'élément "Détails du lieu compact".
L'application se présente comme suit:
Conclusion
L'élément de recherche de lieu associé à l'élément compact d'informations sur le lieu permet d'ajouter facilement des fonctionnalités de découverte de lieux enrichies à vos applications Google Maps Platform.
Essayez le kit UI pour Places dès aujourd'hui pour permettre à vos utilisateurs de trouver et d'explorer des lieux à l'aide de recherches à proximité et de recherches par texte, et d'afficher des informations détaillées sur les lieux, ce qui améliorera leur interaction avec vos cas d'utilisation de découverte de lieux.
Contributeurs
Henrik Valve | Ingénieur DevX