Componentes web en la API de Maps JavaScript (versión preliminar)

Los componentes web son un estándar de W3C popular que encapsula elementos HTML, CSS y JS en componentes HTML personalizados y reutilizables. Estos elementos reutilizables pueden comprender desde fragmentos de funcionalidad atómicos, como mostrar la calificación por estrellas de un lugar, hasta una lógica empresarial más compleja. En esta guía, se describen los componentes web disponibles en la API de Maps JavaScript.

Para obtener más información sobre este estándar, consulta Componentes web.

Público

Esta documentación está diseñada para ayudarte a comenzar rápidamente a explorar y desarrollar aplicaciones con componentes web. Debes tener conocimientos sobre los conceptos de programación con HTML y CSS.

Muestra un mapa

La manera más fácil de comenzar a aprender sobre componentes web es con ejemplos. En el siguiente ejemplo, se muestra un mapa del área 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>

Prueba la muestra

En este ejemplo, hay algunos aspectos para tener en cuenta:

  1. Las llamadas a la API de Maps JavaScript se realizan de manera asíncrona. La función de devolución de llamada se utiliza para saber cuándo se completa la carga de la API.
  2. La presentación del mapa se define con el elemento personalizado <gmp-map>.
  3. Para definir las propiedades del mapa, se deben especificar atributos en el elemento personalizado <gmp-map>.
  4. El diseño se puede aplicar de forma intercalada en elementos personalizados o se puede declarar en un archivo CSS separado.

Aplica diseño al mapa base

Un ID de mapa es un identificador asociado con un diseño o un componente específico del mapa. Para aprovechar las características opcionales de configuración de la nube, reemplaza el diseño de mapas basado en Cloud DEMO_MAP_ID por tu propio ID de mapa. Para obtener información sobre cómo crear un ID de mapa y configurar un diseño personalizado, visita Diseño de mapas basado en Cloud.

Agrega marcadores al mapa

Así como es posible anidar etiquetas HTML integradas para crear jerarquías de contenido complejas, también se puede anidar <gmp-advanced-marker> en un elemento para mostrar uno o más marcadores de mapa.

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>

Prueba la muestra

Aquí agregamos dos elementos <gmp-advanced-marker> en el elemento <gmp-map> personalizado. El texto de title proporciona texto flotante adicional y una etiqueta de accesibilidad para el elemento especificado.

Eventos de JavaScript

Uno de los principales beneficios de los componentes web es su facilidad de uso. Con pocas líneas de código, puedes mostrar un mapa sin importar si tienes conocimientos limitados de JavaScript o eres un programador experto. Tras su implementación, el código sigue los mismos patrones de los demás elementos HTML. Por ejemplo, puedes utilizar el sistema de eventos nativo del navegador para reaccionar a las acciones del mapa o de Marcadores avanzados, como un clic en un marcador.

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>

Prueba la muestra

En este ejemplo, initMap representa la función de devolución de llamada que se requiere cuando la API de Maps JavaScript se carga completamente. El código establece objetos de escucha para cada marcador y presenta una ventana de información cuando se hace clic en cada marcador.

Próximos pasos