Web Components é um padrão W3C popular que faz o encapsulamento HTML, CSS e JS em elementos HTML reutilizáveis e personalizados. Esses componentes reutilizáveis podem variar de peças atômicas de funcionalidade, como exibir a nota de um lugar, a uma lógica de negócios mais complexa. Este guia descreve os Web Components disponíveis na API Maps JavaScript.
Para saber mais sobre o próprio padrão, confira Web Components.
Público-alvo
Esse documento foi elaborado para permitir que você comece rapidamente a explorar e desenvolver aplicativos com o Web Components. Você precisa conhecer os conceitos de programação HTML e CSS.
Exibir um mapa
A maneira mais fácil de começar a conhecer o Web Components é com um exemplo. O exemplo a seguir mostra um mapa da á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>
Testar amostra
Algumas considerações sobre esse exemplo:
- A API Maps JavaScript é chamada de forma assíncrona. A função de callback é usada para descobrir quando a API foi carregada.
- A apresentação do mapa foi definida com o elemento personalizado
<gmp-map>
. - As propriedades do mapa são definidas especificando os atributos no elemento personalizado
<gmp-map>
. - O estilo pode ser aplicado inline nos elementos personalizados ou declarados em um arquivo CSS separado.
Estilo do mapa base
Um ID do mapa é um identificador associado a um estilo de mapa ou recurso específico. Para aproveitar os recursos de configuração da nuvem opcionais, substitua a estilização de mapas baseada na nuvem DEMO_MAP_ID
pelo seu próprio ID do mapa.
Para saber como criar um ID do mapa e configurar um estilo personalizado, acesse Estilização de mapas baseada na nuvem.
Adicionar marcadores ao mapa
Assim como é possível aninhar tags HTML incorporadas para criar hierarquias de conteúdo complexas, também é possível aninhar <gmp-advanced-marker>
dentro de um elemento para exibir um ou mais marcadores do 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>
Testar amostra
Aqui, adicionamos dois elementos <gmp-advanced-marker>
dentro do elemento personalizado <gmp-map>
. O texto para title
fornece um texto de passagem de cursor adicional e rótulo de acessibilidade para o elemento especificado.
Eventos JavaScript
Um grande benefício do Web Components é a facilidade de uso. Com apenas algumas linhas de código, é possível exibir um mapa com conhecimento limitado de JavaScript ou programação avançada. Depois de implementado, o código segue os padrões já conhecidos de outros elementos HTML. Por exemplo, é possível usar o sistema de evento do navegador nativo para reagir a ações do mapa ou de Marcadores Avançados, como um clique do 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>
Testar amostra
Neste exemplo, initMap
representa a função de callback necessária assim que a API Maps JavaScript é totalmente carregada. O código estabelece os listeners de cada marcador e apresenta uma janela de informações quando cada marcador é clicado.
A seguir
- Sugira recursos e informe bugs no Issue Tracker da API Maps JavaScript.
- Confira a biblioteca de componentes estendida para encontrar componentes da Web de níveis superiores, como uma visão geral de lugares.