Objectif
Ce document décrit les principales étapes à suivre pour développer une application interactive de recherche de magasins à l'aide de Google Maps Platform, en particulier l'API Maps JavaScript et l'élément Place Details du Kit UI pour Places. Vous apprendrez à créer une carte qui affiche l'emplacement des magasins, à mettre à jour de manière dynamique une liste des 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 le kit UI pour Places.
- Repères avancés : utilisés pour 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 UI pour Places. Ce document suppose également que vous possédez 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 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.
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 extraire des données. Les données de votre magasin peuvent provenir de différentes sources, comme votre base de données.
Pour cet exemple, nous partons du principe qu'un fichier JSON local (stores.json) contient 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.
Si vous ne disposez pas encore des ID de lieu de vos magasins, vous pouvez les récupérer de différentes manières. 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.
Il existe des champs pour le nom, l'emplacement (latitude/longitude) et l'ID de lieu. Un objet contient les horaires d'ouverture du magasin (tronqués). Il existe également deux valeurs booléennes qui permettent de 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 procédure. 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 s'affichent sur la carte, créez une barre latérale à l'aide de code 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 de la fenêtre d'affichage de la carte
Pour optimiser les performances et l'expérience utilisateur, mettez à jour votre application pour n'afficher les repères et les détails dans la barre latérale que lorsque les lieux correspondants se trouvent dans la zone visible de la carte (fenêtre d'affichage). Pour cela, il faut écouter les modifications de la fenêtre d'affichage de la carte, éliminer les rebonds de ces événements, puis 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 panoramique ou de zoom sont terminé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 garantit que votre 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. Elle accepte un argument de fonction et de délai, qui peut être transmis dans l'écouteur d'inactivité. Un délai de 300 ms suffit pour attendre que la carte s'arrête de bouger, sans ajouter de délai notable à l'UI.
Une fois ce délai expiré, la fonction transmise est appelée, dans ce cas, updateMarkersInView.
La fonction updateMarkersInView devrait 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 détails du magasin dans la barre latérale, si l'emplacement du magasin se trouve dans la fenêtre d'affichage de la carte.
Afficher des détails enrichis sur un lieu à l'aide de l'élément Place Details
À ce stade, l'application affiche tous les emplacements des magasins, et les utilisateurs peuvent les filtrer en fonction de la fenêtre d'affichage de la carte. Pour améliorer l'expérience, 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 être associé à un ID de lieu. Cet ID identifie de manière unique le lieu sur Google Maps et est essentiel pour récupérer ses détails. En général, vous devez acquérir ces ID de lieu au préalable et les stocker pour chacun de vos magasins.
Intégrer l'élément compact Place Details dans l'application
Lorsqu'un magasin est déterminé 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 Place Details pour ce magasin.
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 affiché par l'élément.
En JavaScript, créez dynamiquement une instance de PlaceDetailsCompactElement. Un nouvel objet PlaceDetailsPlaceRequestElement est également créé, l'ID de lieu lui est transmis, puis il est ajouté à PlaceDetailsCompactElement. Enfin, utilisez PlaceContentConfigElement pour configurer le contenu que l'élément affichera.
La fonction suivante suppose que les bibliothèques du kit UI pour Places 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 d'appel est 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 ce comportement en ajoutant ou en supprimant d'autres éléments de contenu disponibles. Consultez la documentation PlaceContentConfigElement pour connaître toutes les options disponibles.
L'élément compact Place Details accepte l'application de styles via des propriétés CSS personnalisées. Cela vous permet d'adapter son apparence (couleurs, polices, etc.) au design de votre application. Appliquez ces propriétés personnalisées dans votre fichier CSS. Consultez la documentation de référence sur PlaceDetailsCompactElement pour connaître les propriétés CSS compatibles.
Voici un exemple de ce à quoi pourrait ressembler votre application à ce stade :
Améliorer le localisateur de magasins
Vous avez créé une base solide pour votre application de localisation de magasins. Examinons maintenant 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 un champ 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 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-lui 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 privilégier ou limiter les résultats à votre zone d'activité.
Détecter la position
Proposez des résultats immédiatement pertinents, en particulier pour les mobinautes, en implémentant une fonctionnalité permettant de détecter leur emplacement géographique actuel. 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 à l'emplacement recherché. De plus, fournissez un bouton ou un lien qui utilise l'API Routes pour générer un itinéraire entre la position 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'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 outil de localisation de magasins plus complet et plus pratique, qui répond directement aux besoins courants des utilisateurs.
Conclusion
Ce guide vous a présenté les principales étapes à suivre pour créer un outil de recherche de magasins interactif. Vous avez appris à afficher les emplacements de 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 les données de vos propres magasins conformément au kit UI pour 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 détaillées et standardisées pour chacun de vos établissements. Vous créez ainsi une base solide pour un outil de localisation de magasins convivial.
Essayez l'API Maps JavaScript et le kit UI pour Places pour proposer des outils puissants basés sur des composants afin de développer rapidement des applications géolocalisées sophistiquées. En combinant ces fonctionnalités, vous pouvez créer des expériences attrayantes et informatives pour vos utilisateurs.
Contributeurs
Henrik Valve | Ingénieur DevX