Objectif
Ce document explique les étapes clés à suivre pour développer une application de recherche de magasin interactive à l'aide de Google Maps Platform, en particulier l'API JavaScript Maps et le kit d'UI Places: élément "Détails du lieu". Vous allez apprendre à créer une carte qui affiche les emplacements des magasins, à mettre à jour de manière dynamique une liste de magasins visibles et à afficher des informations détaillées sur chaque magasin.
Prérequis
Il est recommandé de connaître les éléments suivants:
- API Maps JavaScript : permet d'afficher une carte sur votre page et d'importer l'UI Kit Places.
- Repères avancés : permet d'afficher des repères sur la carte.
- Kit UI pour Places : permet d'afficher des informations sur vos magasins dans l'UI.
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 pour les repères avancés et le kit d'UI Places. Ce document suppose également que vous avez des connaissances pratiques en développement Web, y compris en HTML, CSS et JavaScript.
Configuration initiale
La première étape consiste à ajouter une carte à la page. Cette carte affichera des repères correspondant à vos magasins.
Vous pouvez ajouter une carte à une page de deux manières:
- Utiliser un composant Web HTML gmp-map
- À l'aide de JavaScript
Choisissez la méthode la plus adaptée à votre cas d'utilisation. Les deux méthodes d'implémentation de la carte fonctionnent avec ce guide.
Démo
Cette démonstration montre un exemple de recherche de magasin en action, affichant les bureaux Google dans la région de la baie de San Francisco. L'élément "Place Details" (Détails du lieu) s'affiche pour chaque établissement, avec quelques exemples d'attributs.
Charger et afficher les magasins
Dans cette section, nous allons charger et afficher vos données de magasin sur la carte. Ce guide suppose que vous disposez d'un référentiel d'informations sur vos magasins existants. Vos données de magasin peuvent provenir de différentes sources, comme votre base de données.
Pour cet exemple, nous supposons un fichier JSON local (stores.json) avec un tableau d'objets de magasin, chacun représentant un emplacement de magasin. Chaque objet doit contenir au moins un name, un location (avec lat et lng) et un place_id.
Il existe plusieurs façons de récupérer les ID de lieu de vos magasins si vous ne les avez pas déjà. Pour en savoir plus, consultez la documentation sur les ID de lieu.
Voici un exemple d'entrée de détails de magasin dans votre fichier stores.json :
Les champs "Nom", "Emplacement (lat/lng)" et "ID de lieu" sont disponibles. Un objet est utilisé pour stocker les horaires d'ouverture du magasin (tronqués). Deux valeurs booléennes sont également fournies pour décrire les caractéristiques personnalisées de l'emplacement du magasin.
{
"name": "Example Store Alpha",
"location": { "lat": 51.51, "lng": -0.12 },
"place_id": "YOUR_STORE_PLACE_ID",
"opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
"new_store_design": true,
"indoor_seating": false
}
Dans votre code JavaScript, récupérez les données de vos magasins et affichez un repère sur la carte pour chacun d'eux.
Voici un exemple de la procédure à suivre. Cette fonction reçoit un objet contenant les informations sur les magasins et crée un repère en fonction de l'emplacement de chacun d'eux.
function displayInitialMarkers(storeLocations) {
if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
storeLocations.forEach(store => {
if (store.location) {
const marker = new AdvancedMarkerElement({
position: new LatLng(store.location.lat, store.location.lng),
title: store.name
});
mapElement.appendChild(marker);
}
});
}
Une fois que vous avez chargé vos magasins et que des repères représentant leur emplacement s'affichent sur la carte, créez une barre latérale à l'aide de HTML et de CSS pour afficher des informations sur vos magasins individuels.
Voici un exemple de ce à quoi pourrait ressembler votre outil de localisation de magasins à ce stade:
Écouter les modifications de la fenêtre d'affichage de la carte
Pour optimiser les performances et l'expérience utilisateur, mettez à jour votre application afin qu'elle n'affiche les repères et les détails dans la barre latérale que lorsque leurs emplacements correspondants se trouvent dans la zone de la carte visible (fenêtre d'affichage). Pour ce faire, vous devez écouter les changements de vue de la carte, déboguer ces événements, puis ne redessiner que les repères nécessaires.
Associez un écouteur d'événements à l'événement d'inactivité de la carte. Cet événement se déclenche une fois les opérations de panoramique ou de zoom terminées, ce qui fournit un viewport stable pour vos calculs.
map.addListener('idle', debounce(updateMarkersInView, 300));
L'extrait de code ci-dessus écoute l'événement idle et appelle une fonction debounce. L'utilisation d'une fonction de debounce garantit que votre logique de mise à jour des repères ne s'exécute que lorsque l'utilisateur a cessé d'interagir avec la carte pendant une courte période, ce qui améliore les performances.
function debounce(func, delay) {
let timeoutId;
return function(...args) {
const context = this;
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
func.apply(context, args);
}, delay);
};
}
Le code ci-dessus est un exemple de fonction de debounce. Il prend une fonction et un argument de délai, qui peuvent être transmis dans l'écouteur inactif. Un délai de 300 ms suffit à attendre que la carte cesse de bouger, sans ajouter de délai notable à l'interface utilisateur.
Une fois ce délai expiré, la fonction transmise est appelée, dans ce cas, updateMarkersInView.
La fonction updateMarkersInView doit effectuer les actions suivantes:
Supprimer tous les repères existants de la carte
Vérifiez si l'emplacement du magasin se trouve dans les limites actuelles de la carte, par exemple:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
Dans l'instruction if ci-dessus, écrivez du code pour afficher les repères et les informations sur le magasin dans la barre latérale, si l'emplacement du magasin se trouve dans le champ de vision de la carte.
Afficher des informations détaillées sur un lieu à l'aide de l'élément "Place Details" (Détails du lieu)
À ce stade, l'application affiche tous les magasins, et les utilisateurs peuvent les filtrer en fonction du champ de vision de la carte. Pour améliorer cela, des informations détaillées sur chaque magasin, telles que des photos, des avis et des informations sur l'accessibilité, sont ajoutées à l'aide de l'élément Place Details. Cet exemple utilise spécifiquement l'élément compact Place Details.
Chaque magasin de votre source de données doit avoir un ID de lieu correspondant. Cet ID identifie de façon unique l'emplacement sur Google Maps et est essentiel pour récupérer ses informations. Vous devez généralement acquérir ces ID de lieu à l'avance et les stocker pour chacun de vos enregistrements de magasin.
Intégrer l'élément Place Details Compact dans l'application
Lorsqu'un magasin se trouve dans le viewport actuel de la carte et qu'il est affiché dans la barre latérale, vous pouvez créer et insérer dynamiquement un élément compact "Détails du lieu" pour lui.
Pour le magasin en cours de traitement, récupérez l'ID de lieu dans vos données. L'ID de lieu permet de contrôler le lieu qui s'affichera dans l'élément.
En JavaScript, créez dynamiquement une instance de PlaceDetailsCompactElement. Un nouvel élément PlaceDetailsPlaceRequestElement est également créé, l'ID de lieu lui est transmis et est ajouté à PlaceDetailsCompactElement. Enfin, utilisez PlaceContentConfigElement pour configurer le contenu que l'élément affichera.
La fonction suivante suppose que les bibliothèques Place UI Kit nécessaires sont importées et disponibles dans le champ d'application où cette fonction est appelée, et que storeData transmis à la fonction contient place_id.
Cette fonction renverra l'élément, et le code appelant sera chargé de l'ajouter au DOM.
function createPlaceDetailsCompactElement(storeData) {
// Create the main details component
const detailsCompact = new PlaceDetailsCompactElement();
detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'
// Specify the Place ID
const placeRequest = new PlaceDetailsPlaceRequestElement();
placeRequest.place = storeData.place_id;
detailsCompact.appendChild(placeRequest);
// Configure which content elements to display
const contentConfig = new PlaceContentConfigElement();
// For this example, we'll render media, rating, accessibility, and attribution:
contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
contentConfig.appendChild(new PlaceRatingElement());
contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
// Configure attribution
const placeAttribution = new PlaceAttributionElement();
placeAttribution.setAttribute('light-scheme-color', 'gray');
placeAttribution.setAttribute('dark-scheme-color', 'gray');
contentConfig.appendChild(placeAttribution);
detailsCompact.appendChild(contentConfig);
// Return the element
return detailsCompact;
}
Dans l'exemple de code ci-dessus, l'élément est configuré pour afficher les photos du lieu, la note des avis et les informations d'accessibilité. Vous pouvez personnaliser cette fonctionnalité en ajoutant ou en supprimant d'autres éléments de contenu disponibles. Consultez la documentation PlaceContentConfigElement pour découvrir toutes les options disponibles.
L'élément Place Details Compact est compatible avec le style via des propriétés personnalisées CSS. Cela vous permet d'adapter son apparence (couleurs, polices, etc.) à la conception de votre application. Appliquez ces propriétés personnalisées dans votre fichier CSS. Pour connaître les propriétés CSS compatibles, consultez la documentation de référence de PlaceDetailsCompactElement.
Voici un exemple de ce à quoi pourrait ressembler votre application à ce stade:
Améliorer l'outil de recherche de magasins
Vous avez créé une base solide pour votre application de recherche de magasin. Maintenant, réfléchissez à plusieurs façons d'étendre ses fonctionnalités et de créer une expérience encore plus riche et plus centrée sur l'utilisateur.
Ajouter la saisie semi-automatique
Améliorez la façon dont les utilisateurs trouvent des zones pour rechercher des magasins en intégrant une zone de saisie de recherche avec Place Autocomplete. Lorsque les utilisateurs saisissent une adresse, un quartier ou un point d'intérêt et sélectionnent une suggestion, programmez la carte pour qu'elle soit automatiquement centrée sur cet emplacement, ce qui déclenche une mise à jour des magasins à proximité. Pour ce faire, ajoutez un champ de saisie et associez-y la fonctionnalité Place Autocomplete. Lorsque vous sélectionnez une suggestion, la carte peut être centrée sur ce point. N'oubliez pas de le configurer pour biaiser ou restreindre les résultats à votre zone d'opération.
Détecter la position
Proposez une pertinence immédiate, en particulier pour les utilisateurs mobiles, en implémentant une fonctionnalité permettant de détecter leur position géographique actuelle. Après avoir obtenu l'autorisation du navigateur de détecter sa position, centrez automatiquement la carte sur sa position et affichez les magasins les plus proches. Les utilisateurs apprécient beaucoup cette fonctionnalité À proximité lorsqu'ils recherchent des options immédiates. Ajoutez un bouton ou une invite initiale pour demander l'accès à la position.
Afficher la distance et l'itinéraire
Une fois qu'un utilisateur a identifié un magasin qui l'intéresse, améliorez considérablement son parcours en intégrant l'API Routes. Pour chaque magasin que vous listez, calculez et affichez la distance par rapport à la position actuelle de l'utilisateur ou à l'emplacement recherché. Fournissez également un bouton ou un lien qui utilise l'API Routes pour générer un itinéraire entre l'emplacement de l'utilisateur et le magasin sélectionné. Vous pouvez ensuite afficher cet itinéraire sur votre carte ou créer un lien vers Google Maps pour la navigation, ce qui permet de passer facilement de la recherche d'un magasin à l'accès à celui-ci.
En implémentant ces extensions, vous pouvez utiliser davantage de fonctionnalités de la plate-forme Google Maps pour créer un outil de recherche de magasins plus complet et plus pratique qui répond directement aux besoins courants des utilisateurs.
Conclusion
Ce guide vous a présenté les étapes principales pour créer un outil de recherche de magasin interactif. Vous avez appris à afficher les emplacements de vos magasins sur une carte à l'aide de l'API Maps JavaScript, à mettre à jour dynamiquement les magasins visibles en fonction des modifications apportées au viewport et, surtout, à afficher vos propres données de magasin conformément au kit d'UI Places. En utilisant vos informations existantes sur les magasins, y compris les ID de lieu, avec l'élément Place Details, vous pouvez présenter des informations riches et standardisées pour chacun de vos établissements, ce qui constitue une base solide pour un outil de recherche de magasin convivial.
Essayez l'API Maps JavaScript et le kit d'UI Places pour proposer des outils puissants, basés sur des composants, qui vous permettront de développer rapidement des applications sophistiquées basées sur la localisation. En combinant ces fonctionnalités, vous pouvez créer des expériences attrayantes et informatives pour vos utilisateurs.
Contributeurs
Henrik Valve | Ingénieur DevX