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 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 :

  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.

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