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:
- 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.
- La presentación del mapa se define con el elemento personalizado
<gmp-map>
. - Para definir las propiedades del mapa, se deben especificar atributos en el elemento personalizado
<gmp-map>
. - 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
- Informa errores y solicita funciones en la Herramienta de seguimiento de errores de la API de Maps JavaScript.
- Explora la Biblioteca de componentes extendidos para acceder a componentes web de nivel superior, como la descripción general de un lugar.