Visualização em KML

Visão geral

Neste tutorial, mostramos como mostrar informações de um arquivo KML em um mapa e uma barra lateral do Google. Para mais informações sobre o uso de arquivos KML em mapas, leia o guia para camadas KML. Clique em um marcador no mapa abaixo para ver os dados na barra lateral.

A seção abaixo mostra todo o código necessário para criar o mapa e a barra lateral.

var map;
var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });

  var kmlLayer = new google.maps.KmlLayer(src, {
    suppressInfoWindows: true,
    preserveViewport: false,
    map: map
  });
  kmlLayer.addListener('click', function(event) {
    var content = event.featureData.infoWindowHtml;
    var testimonial = document.getElementById('capture');
    testimonial.innerHTML = content;
  });
}
<div id="map"></div>
<div id="capture"></div>
html, body {
  height: 370px;
  padding: 0;
  margin: 0;
  }
#map {
 height: 360px;
 width: 300px;
 overflow: hidden;
 float: left;
 border: thin solid #333;
 }
#capture {
 height: 360px;
 width: 480px;
 overflow: hidden;
 float: left;
 background-color: #ECECFB;
 border: thin solid #333;
 border-left: none;
 }
<!-- Replace the value of the key parameter with your own API key. -->
<script async
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>

Sua vez de tentar

Você pode testar esse código no JSFiddle clicando no ícone <> no canto de cima direito da janela de código.

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no">
    <meta charset="utf-8">
    <title>KML Click Capture Sample</title>
    <style>
      html, body {
        height: 370px;
        padding: 0;
        margin: 0;
        }
      #map {
       height: 360px;
       width: 300px;
       overflow: hidden;
       float: left;
       border: thin solid #333;
       }
      #capture {
       height: 360px;
       width: 480px;
       overflow: hidden;
       float: left;
       background-color: #ECECFB;
       border: thin solid #333;
       border-left: none;
       }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <div id="capture"></div>
    <script>
      var map;
      var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';

      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: new google.maps.LatLng(-19.257753, 146.823688),
          zoom: 2,
          mapTypeId: 'terrain'
        });

        var kmlLayer = new google.maps.KmlLayer(src, {
          suppressInfoWindows: true,
          preserveViewport: false,
          map: map
        });
        kmlLayer.addListener('click', function(event) {
          var content = event.featureData.infoWindowHtml;
          var testimonial = document.getElementById('capture');
          testimonial.innerHTML = content;
        });
      }
    </script>
    <script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

Vamos começar

Estas são as etapas para criar o mapa e a barra lateral deste tutorial:

  1. Configurar o arquivo KML
  2. Exibir a KMLlayer
  3. Exibir dados na barra lateral

Configuração do arquivo KML para importação

O arquivo KML precisa estar em compliance com o padrão KML. Para saber mais sobre esse padrão, consulte o site do Open Geospace Consortium. A documentação de KML do Google também descreve a linguagem e oferece uma documentação de desenvolvedor conceitual e de referência.

Se estiver aprendendo e não tiver um arquivo KML, é possível:

  • usar o seguinte arquivo KML para este tutorial:

    https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml

  • encontrar um arquivo KML na Web. Você pode usar o operador de pesquisa filetype do Google.

    Substitua qualquer termo de pesquisa por velodromes ou omita completamente o termo para encontrar todos os arquivos KML.

Se estiver criando um arquivo próprio, o código neste exemplo presume que:

  • você hospedou publicamente o arquivo na internet. Esse é um requisito de todos os aplicativos que carregam KML em um KMLLayer, para que os servidores do Google possam encontrar e recuperar o conteúdo para mostrá-lo no mapa.
  • o arquivo não está em uma página protegida por senha;
  • seus recursos têm conteúdo na janela de informações. Você pode incluir esse conteúdo em um elemento description ou incluí-lo usando um elemento ExtendedData e a substituição de entidade (leia abaixo para mais informações). Ambas são acessíveis como a propriedade infoWindowHtml do recurso.

Elementos ExtendedData

O arquivo KML deste tutorial inclui informações de recursos em um elemento ExtendedData. Para inserir essas informações na descrição do recurso, use a substituição de entidade, que é essencialmente uma variável na tag BalloonStyle.

A tabela abaixo explica o código desta seção.

Código e descrição 

<Style id="west_campus_style">
  <IconStyle>
    <Icon>
      <href>https://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png
      </href>
    </Icon>
  </IconStyle>
  <BalloonStyle>
    <text>$[video]</text>
  </BalloonStyle>
</Style>

O arquivo KML tem um único elemento Style que é aplicado a todos os marcadores de local.
Esse elemento Style atribui um valor de #[video] ao elemento de texto de BalloonStyle.
O formato $[x] diz ao analisador KML para procurar um elemento Data chamado video e usá-lo como o texto do balão.		 

<Placemark>
    <name>Google West Campus 1</name>
    <styleUrl>#west_campus_style</styleUrl>
    <ExtendedData>
      <Data name="video">
        <value><![CDATA[<iframe width="640" height="360"
          src="https://www.youtube.com/embed/ZE8ODPL2VPI" frameborder="0"
          allowfullscreen></iframe><br><br>]]></value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-122.0914977709329,37.42390182131783,0</coordinates>
    </Point>
</Placemark>

Cada Placemark contém um elemento ExtendedData, que contém o elemento Data. Cada Placemark tem um único elemento Data com um atributo de nome video.
O arquivo deste tutorial usa o vídeo incorporado do YouTube como valor do texto do balão de cada marcador de local.

Saiba mais sobre a substituição de entidades no capítulo Adicionar dados personalizados da documentação do KML.

Exibição da KMLLayer

Inicializar o mapa

Esta tabela explica o código desta seção.

Código e descrição 

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(-19.257753, 146.823688),
    zoom: 2,
    mapTypeId: 'terrain'
  });
}

Para mostrar o KML em um mapa, primeiro é necessário criar o mapa.
Esse código cria um novo objeto do Google Maps, informa onde centralizar e aplicar zoom e anexa o mapa ao div.
Para saber mais sobre os conceitos básicos da criação de um mapa no Google Maps, leia o tutorial Adicionar um mapa do Google ao seu site.

Criar a KMLLayer

Esta tabela explica o código que cria uma KMLLayer.

Código e descrição 

var kmlLayer = new google.maps.KmlLayer();

Cria um novo objeto KMLLayer para mostrar o KML.		 

var src = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml';
var kmlLayer = new google.maps.KmlLayer(src, {
  suppressInfoWindows: true,
  preserveViewport: false,
  map: map
});

O construtor da KMLLayer define o URL do seu arquivo KML. Ela também define as propriedades do objeto KMLLayer que fazem o seguinte:
  • Instrui a camada a não deve mostrar uma janela de informações quando clicada.
  • Instrui o mapa a centralizar e aplicar zoom à caixa delimitadora do conteúdo da camada.
  • Define o mapa para o objeto Map criado anteriormente.
O guia de referência da API Maps JavaScript lista todas as opções disponíveis para essa camada.
Carregue o arquivo HTML para mostrar o conteúdo do arquivo KML como uma camada sobre o mapa básico. No entanto, clicar em qualquer recurso não ainda resulta em uma ação.

Exibir dados na barra lateral

Nesta seção, explicamos as configurações que mostram o conteúdo da janela de informações na barra lateral quando você clica em um recurso no mapa. Confira como fazer isso:

  • Detecte um evento de clique em qualquer um dos recursos da KMLLayer.
  • Obtenha os dados do recurso clicado.
  • Grave esses dados na barra lateral.

Adicionar um listener de eventos

O Google Maps tem uma função para detectar e responder a eventos do usuário no mapa, como cliques ou pressionamento de teclas. Ele adiciona um listener a esses eventos do click.

A tabela abaixo explica o código desta seção.

Código e descrição 

kmlLayer.addListener('click', function(event) {});

O listener de eventos kmlLayer.addListener se concentra no seguinte:
  • O tipo de evento a ser detectado. Neste tutorial, é o evento click.
  • Uma função a ser chamada quando ocorrer o evento.
Saiba mais sobre os eventos no Guia para desenvolvedores.

Gravar os dados do recurso KML na barra lateral

Nesta etapa do tutorial, você capturou eventos de clique nos recursos da camada. Agora é possível configurar o aplicativo para gravar o conteúdo de dados e a janela de informações do recurso na barra lateral.

A tabela abaixo explica o código desta seção.

Código e descrição 

var content = event.featureData.infoWindowHtml;

Grava o conteúdo da janela de informações em uma variável. 

var testimonial = document.getElementById('capture');
testimonial.innerHTML = content;

Identifica o div para gravar e substitui o HTML nele pelo conteúdo do recurso. 

kmlLayer.addListener('click', function(event) {
  var content = event.featureData.infoWindowHtml;
  var testimonial = document.getElementById('capture');
  testimonial.innerHTML = content;
});

Essas linhas de código se tornam a função dentro do construtor addListener.

Agora, sempre que você clicar em um recurso KML no mapa, a barra lateral será atualizada para mostrar o conteúdo da janela de informações.

Mais informações

Leia mais sobre o uso de arquivos KML.