Composants Web dans l'API Maps JavaScript (preview)

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 Jose.

Carte de la région de San Jose

HTML

<html>
  <head>
    <title>Simple Map</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </script>

  </head>
  <body>
    <gmp-map center="37.4220656,-122.0840897" zoom="10" map-id="DEMO_MAP_ID"></gmp-map>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

Voici quelques points à noter dans cet exemple :

  1. 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.
  2. La présentation de la carte est définie avec l'élément personnalisé <gmp-map>.
  3. Les propriétés de la carte sont définies en spécifiant les attributs dans l'élément personnalisé <gmp-map>.
  4. Le style peut être appliqué aux éléments personnalisés de façon intégrée ou déclaré dans un fichier CSS distinct.

Styliser la carte de base

Un ID de carte est un identifiant associé à un style de carte ou un élément géographique spécifique. Pour profiter des fonctionnalités de configuration cloud facultatives, remplacez le DEMO_MAP_ID de la personnalisation de cartes dans Google Cloud par votre propre ID de carte. Pour savoir comment créer un ID de carte et configurer un style personnalisé, consultez Personnalisation de cartes dans Google 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.

Carte avec repères

HTML

<html>
  <head>
    <title>Simple Map with Markers</title>
    <link rel="stylesheet" type="text/css" href="style.css" />

    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
    </script>

    <script>
      function initMap() {
        console.log('Maps JavaScript API loaded.');
      }
    </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>
  </body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

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).

Événement de clic sur un repère

HTML

<html>
<head>
  <title>Google Maps - Marker Click Example</title>
  <link rel="stylesheet" href="style.css" type="text/css">

  <script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE&callback=initMap&libraries=maps,marker&v=beta">
  </script>

  <script>
    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} = await google.maps.importLibrary("maps");
            const infoWindow = new InfoWindow({
              content: advancedMarker.title
            });
            infoWindow.open({
              anchor: advancedMarker
            });
          });
        });
      }
    }
  </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>

</body>
</html>

CSS

    gmp-map {
      height: 500px;
    }

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