Componentes da Web na API Maps JavaScript (pré-lançamento)

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é.

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:

  1. A API Maps JavaScript é chamada de forma assíncrona. A função de callback é usada para descobrir quando a API foi carregada.
  2. A apresentação do mapa foi definida com o elemento personalizado <gmp-map>.
  3. As propriedades do mapa são definidas especificando os atributos no elemento personalizado <gmp-map>.
  4. 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.

mapa com marcadores

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.

evento de 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