Les composants Web font l'objet d'une norme W3C populaire qui encapsule HTML, CSS et JavaScript dans des éléments HTML personnalisés et réutilisables. Ces éléments réutilisables vont de toutes petites fonctionnalités (comme afficher la note d'un lieu) à des logiques métier plus complexes. Ce guide décrit les composants Web disponibles dans l'API Maps JavaScript.
Pour en savoir plus sur la norme proprement dite, consultez Web Components (composants web).
Audience
Cette documentation est conçue pour vous permettre de découvrir et de développer rapidement des applications avec les composants Web. Vous devez connaître les concepts de programmation HTML et CSS.
Afficher une carte
Le moyen le plus simple de vous familiariser avec les composants Web est de consulter un exemple. L'exemple suivant affiche une carte de la région de San José.
TypeScript
// This example adds a map using web components. function initMap(): void { console.log('Maps JavaScript API loaded.'); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a map using web components. function initMap() { console.log("Maps JavaScript API loaded."); } window.initMap = initMap;
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } gmp-map { height: 400px; }
HTML
<html> <head> <title>Add a Map Web Component</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <gmp-map center="37.4220656,-122.0840897" zoom="10" map-id="DEMO_MAP_ID" ></gmp-map> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=beta" defer ></script> </body> </html>
Essayer avec un exemple
Voici quelques points à noter dans cet exemple :
- L'API Maps JavaScript est appelée de façon asynchrone. La fonction de rappel est utilisée pour déterminer quand l'API a été chargée.
- La présentation de la carte est définie avec l'élément personnalisé
<gmp-map>
. - Les propriétés de la carte sont définies en spécifiant les attributs dans l'élément personnalisé
<gmp-map>
. - Le style peut être appliqué aux éléments personnalisés de façon intégrée ou déclaré dans un fichier CSS distinct.
Appliquer un style à la carte de base
Un ID de carte est un identifiant associé à un style de carte ou un élément cartographique spécifique. Pour profiter des fonctionnalités de configuration cloud facultatives, remplacez le DEMO_MAP_ID
des styles de cartes basés dans le cloud par votre propre ID de carte.
Pour savoir comment créer un ID de carte et configurer un style personnalisé, consultez Styles de cartes basés dans le cloud.
Ajouter des repères à la carte
Tout comme il est possible d'imbriquer des balises HTML intégrées pour créer des hiérarchies de contenus complexes, vous pouvez aussi imbriquer <gmp-advanced-marker>
dans un élément pour afficher un ou plusieurs repères sur la carte.
TypeScript
// This example adds a map with markers, using web components. function initMap(): void { console.log('Maps JavaScript API loaded.'); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a map with markers, using web components. function initMap() { console.log("Maps JavaScript API loaded."); } window.initMap = initMap;
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } gmp-map { height: 400px; }
HTML
<html> <head> <title>Add a Map with Markers using Web Components</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <gmp-map center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID"> <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA" ></gmp-advanced-marker> <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA" ></gmp-advanced-marker> </gmp-map> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta" defer ></script> </body> </html>
Essayer avec un exemple
Ici, nous avons ajouté deux éléments <gmp-advanced-marker>
dans l'élément personnalisé <gmp-map>
. Le texte de title
fournit un texte d'info-bulle et un libellé d'accessibilité supplémentaires pour l'élément spécifié.
Événements JavaScript
L'un des principaux avantages des composants Web est qu'ils sont faciles à utiliser. Vous pouvez afficher une carte en ajoutant quelques lignes de code, même si vos connaissances en JavaScript ou en programmation avancée sont limitées. Une fois implémenté, le code suit les modèles habituels des autres éléments HTML. Par exemple, vous pouvez utiliser le système de gestion d'événements du navigateur natif pour réagir aux actions "Carte" ou "Repères avancés" (clic sur un repère, par exemple).
TypeScript
// This example adds a map using web components. function initMap(): void { console.log('Maps JavaScript API loaded.'); const advancedMarkers = document.querySelectorAll("#marker-click-event-example gmp-advanced-marker"); for (const advancedMarker of advancedMarkers) { customElements.whenDefined(advancedMarker.localName).then(async () => { advancedMarker.addEventListener('gmp-click', async () => { const infoWindow = new google.maps.InfoWindow({ //@ts-ignore content: advancedMarker.title, }); infoWindow.open({ //@ts-ignore anchor: advancedMarker }); }); }); } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a map using web components. function initMap() { console.log("Maps JavaScript API loaded."); const advancedMarkers = document.querySelectorAll( "#marker-click-event-example gmp-advanced-marker", ); for (const advancedMarker of advancedMarkers) { customElements.whenDefined(advancedMarker.localName).then(async () => { advancedMarker.addEventListener("gmp-click", async () => { const infoWindow = new google.maps.InfoWindow({ //@ts-ignore content: advancedMarker.title, }); infoWindow.open({ //@ts-ignore anchor: advancedMarker, }); }); }); } } window.initMap = initMap;
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } gmp-map { height: 400px; }
HTML
<html> <head> <title>Add a Map Web Component with Events</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <gmp-map id="marker-click-event-example" center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID" > <gmp-advanced-marker position="37.4220656,-122.0840897" title="Mountain View, CA" ></gmp-advanced-marker> <gmp-advanced-marker position="47.648994,-122.3503845" title="Seattle, WA" ></gmp-advanced-marker> </gmp-map> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta" defer ></script> </body> </html>
Essayer avec un exemple
Dans cet exemple, initMap
représente la fonction de rappel requise une fois l'API Maps JavaScript entièrement chargée. Le code établit des écouteurs pour chaque repère et présente une fenêtre d'informations lorsqu'un clic est effectué sur chaque repère.
Étapes suivantes
- Demandez des fonctionnalités et signalez des bugs dans l'outil Issue Tracker de l'API Maps JavaScript.
- Explorez la bibliothèque de composants étendus pour trouver des composants Web de niveau supérieur (présentation d'un lieu, par exemple).