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é.
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; }
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.
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; }
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.
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; }
Neste exemplo, initMap
representa a função de callback 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.