Objectif
Ce document décrit les étapes clés pour développer une application interactive de localisation de magasins à l'aide de Google Maps Platform, en particulier l'API Maps JavaScript et le Kit UI Places : élément Détails du lieu. Vous apprendrez à créer une carte qui affiche les magasins, à mettre à jour de manière dynamique la liste des magasins visibles et à afficher des informations détaillées sur chaque magasin.
Prérequis
Il est recommandé de maîtriser les éléments suivants :
- API Maps JavaScript : permet d'afficher une carte sur votre page et d'importer le kit d'interface utilisateur Places.
- Advanced Markers : 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 pour 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'interface utilisateur Places. Ce document suppose également que vous maîtrisez le développement Web, y compris HTML, CSS et JavaScript.
Configuration initiale
La première étape consiste à ajouter une carte à la page. Cette carte servira à afficher des repères correspondant à l'emplacement de vos magasins.
Il existe deux façons d'ajouter une carte à une page :
- Utiliser un composant Web HTML gmp-map
- Utiliser JavaScript
Choisissez la méthode qui convient le mieux à votre cas d'utilisation. Les deux méthodes d'implémentation de la carte fonctionnent avec ce guide.
Démo
Cette démo montre un exemple de localisateur de magasin en action, affichant les bureaux Google dans la baie de San Francisco. L'élément "Détails du lieu" est affiché pour chaque établissement, avec quelques exemples d'attributs.
Charger et afficher les emplacements des magasins
Dans cette section, nous allons charger et afficher les données de votre magasin sur la carte. Ce guide suppose que vous disposez d'un dépôt d'informations sur vos magasins existants à partir duquel vous pouvez extraire des données. Vos données de magasin peuvent provenir de différentes sources, comme votre base de données.
Pour cet exemple, nous partons du principe qu'il existe 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 du magasin dans votre fichier stores.json.
Les champs "Nom", "Emplacement (lat/lng)" et "ID du lieu" sont disponibles. Il existe un objet permettant de stocker les horaires d'ouverture du magasin (tronqué). Deux valeurs booléennes permettent également de décrire les caractéristiques spécifiques 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 marche à suivre. Cette fonction prend un objet contenant les détails des 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 sont affichés sur la carte, créez une barre latérale en HTML et CSS pour afficher des informations sur chacun de vos magasins.
Voici un exemple de ce à quoi pourrait ressembler votre outil de localisation de magasins à ce stade :
Écouter les modifications apportées à la fenêtre d'affichage de la carte
Pour optimiser les performances et l'expérience utilisateur, mettez à jour votre application afin d'afficher les repères et les détails dans la barre latérale uniquement lorsque leurs emplacements correspondants se trouvent dans la zone visible de la carte (fenêtre d'affichage). Cela implique d'écouter les changements de fenêtre d'affichage de la carte, de supprimer les événements en double, puis de redessiner uniquement les repères nécessaires.
Associez un écouteur d'événements à l'événement inactif de la carte. Cet événement se déclenche une fois que toutes les opérations de déplacement ou de zoom ont été effectuées, ce qui fournit une fenêtre d'affichage 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 permet de s'assurer que la logique de mise à jour des repères ne s'exécute qu'une fois que 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 à l'écouteur d'inactivité. Un délai de 300 ms est suffisant pour attendre que la carte cesse de bouger, sans ajouter de délai notable à l'UI.
Une fois ce délai expiré, la fonction transmise est appelée. Dans le cas présent, il s'agit de updateMarkersInView.
La fonction updateMarkersInView doit effectuer les actions suivantes :
Effacer 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 la fenêtre d'affichage de la carte.
Afficher des informations détaillées sur les lieux à l'aide de l'élément Place Details
À ce stade, l'application affiche tous les magasins et les utilisateurs peuvent les filtrer en fonction de la fenêtre d'affichage de la carte. Pour améliorer cette expérience, des informations détaillées sur chaque magasin (photos, avis, informations sur l'accessibilité, etc.) sont ajoutées à l'aide de l'élément Place Details. Cet exemple utilise plus précisément l'élément compact Détails du lieu.
Chaque magasin de votre source de données doit avoir un ID de lieu correspondant. Cet ID identifie de façon unique le lieu sur Google Maps et est essentiel pour récupérer ses informations. Vous devez généralement obtenir ces ID de lieu à l'avance et les stocker pour chacun de vos enregistrements de magasin.
Intégrer l'élément compact Place Details dans l'application
Lorsqu'un magasin est considéré comme se trouvant dans la fenêtre d'affichage actuelle 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 celui-ci.
Pour le magasin en cours de traitement, récupérez l'ID de lieu à partir de vos données. L'ID de lieu permet de contrôler le lieu où l'élément s'affichera.
En JavaScript, créez dynamiquement une instance de PlaceDetailsCompactElement. Un nouveau PlaceDetailsPlaceRequestElement est également créé, l'ID de lieu lui est transmis et il 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 renvoie l'élément, et le code appelant est responsable de son ajout 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 et les informations sur l'accessibilité. Vous pouvez personnaliser ce paramètre en ajoutant ou en supprimant d'autres éléments de contenu disponibles. Pour connaître toutes les options disponibles, consultez la documentation PlaceContentConfigElement.
L'élément compact Détails du lieu est compatible avec la personnalisation via les propriétés 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 l'apparence de votre application à ce stade :
Améliorer le localisateur de magasins
Vous avez créé une base solide pour votre application de localisation de magasins. Maintenant, réfléchissez à plusieurs façons d'étendre ses fonctionnalités et de créer une expérience encore plus riche et axé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 un champ de recherche à Place Autocomplete. Lorsque les utilisateurs saisissent une adresse, un quartier ou un point d'intérêt, puis sélectionnent une suggestion, programmez la carte pour qu'elle se centre automatiquement 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 orienter ou limiter les résultats à votre zone opérationnelle.
Détecter la position
Offrez une pertinence immédiate, en particulier aux utilisateurs mobiles, en implémentant une fonctionnalité permettant de détecter leur position géographique actuelle. Après avoir obtenu l'autorisation du navigateur pour détecter leur position, centrez automatiquement la carte sur leur position et affichez les magasins les plus proches. Les utilisateurs apprécient beaucoup la 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 à la position recherchée. Fournissez également un bouton ou un lien qui utilise l'API Routes pour générer un itinéraire depuis la position de l'utilisateur jusqu'au 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'itinéraire pour s'y rendre.
En implémentant ces extensions, vous pouvez utiliser davantage de fonctionnalités de Google Maps Platform pour créer un localisateur de magasins plus complet et pratique qui répond directement aux besoins courants des utilisateurs.
Conclusion
Ce guide a présenté les étapes de base pour créer un outil interactif de localisation des magasins. Vous avez appris à afficher vos propres magasins sur une carte à l'aide de l'API Maps JavaScript, à mettre à jour de manière dynamique les magasins visibles en fonction des modifications de la fenêtre d'affichage et, surtout, à afficher vos propres données de magasin conformément au kit d'interface utilisateur Places. En utilisant les informations existantes sur vos 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. Vous créez ainsi une base solide pour un outil de localisation de magasin convivial.
Essayez l'API Maps JavaScript et le kit d'interface utilisateur Places pour proposer des outils puissants basés sur des composants permettant 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