Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps JavaScript API

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

Eventos

Esta página descreve os eventos da interface do usuário e eventos de erro que você pode detectar e tratar programaticamente.

Eventos da interface do usuário

O JavaScript no navegador é baseado em eventos, o que significa que o JavaScript responde a interações gerando eventos e espera que um programa ouça os eventos interessantes. Há dois tipos de eventos:

  • Os eventos do usuário, como eventos de “clique” do mouse, propagados do DOM para a Google Maps JavaScript API. Esses eventos são separados e distintos dos eventos padrão do DOM.
  • As notificações de mudança de estado de MVC refletem mudanças em objetos Maps JavaScript API e são nomeadas usando a convenção property_changed.

Cada objeto Maps JavaScript API exporta diversos eventos nomeados. Os programas interessados em determinados eventos registram detectores de evento JavaScript para esses eventos e executam código quando esses eventos são recebidos chamando addListener() para registrar gerenciadores de evento no objeto.

O exemplo abaixo mostra quais eventos são acionados por google.maps.Map à medida que você interage com o mapa.

Para ver uma lista completa de eventos, consulte o Guia da Google Maps JavaScript API. Os eventos são listados em uma seção separada de cada objeto que contém eventos.

Eventos de IU

Alguns objetos da Google Maps JavaScript API foram projetados para responder a eventos do usuário, como eventos do mouse ou teclado. Por exemplo, veja a seguir alguns eventos de usuário que um objeto google.maps.Marker pode escutar:

  • 'click'
  • 'dblclick'
  • 'mouseup'
  • 'mousedown'
  • 'mouseover'
  • 'mouseout'

Para obter a lista completa, consulte a classe Marker. Esses eventos podem parecer eventos DOM padrão, mas, na verdade, são parte da Maps JavaScript API. Como cada navegador implementa um modelo de evento DOM, a Maps JavaScript API oferece esses mecanismos para detectar e responder a eventos DOM sem precisar lidar com as várias particularidades de cada navegador. Normalmente, esses eventos também passam argumentos no evento anotando algum estado da IU (como a posição do mouse).

Alterações de estado de MVC

Normalmente, os objetos MVC contêm estado. Sempre que a propriedade de um objeto mudar, a Google Maps JavaScript API disparará um evento informando a alteração da propriedade. Por exemplo, a API aciona um evento zoom_changed em um mapa quando o nível de zoom do mapa é alterado. Você pode interceptar essas mudanças de estado chamando addListener() para registrar gerenciadores de evento também no objeto.

Eventos de usuário e alterações de estado de MVC podem parecer semelhantes, mas normalmente são tratados de forma diferente no código. Eventos de MVC, por exemplo, não passam argumentos no evento. Inspecione a propriedade alterada em uma alteração de estado de MVC chamando o método getProperty apropriado naquele objeto.

Processamento de eventos

Para se registrar para receber notificações de eventos, use o manipulador de eventos addListener(). Esse método assume um evento para detectar e uma função para chamar quando o evento especificado ocorre.

Exemplo: eventos de mapa e marcador

O código a seguir mistura eventos de usuário e de alteração de estado. Anexamos um manipulador de eventos a um marcador que altera o zoom do mapa quando clicado. Adicionamos também um manipulador de eventos ao mapa para monitorar a propriedade center e deslocar o mapa de volta ao marcador três segundos depois de receber o evento center_changed:

function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

Ver o exemplo (event-simple.html).

Dica: para tentar detectar uma mudança na porta de visualização, não deixe de usar o evento bounds_changed específico em vez dos eventos envolvidos zoom_changed e center_changed. Como a Maps JavaScript API dispara esses eventos que mencionamos agora de forma independente, getBounds() pode não relatar resultados úteis até que a janela de visualização seja alterada com a devida autoridade. Para usar getBounds() depois desse evento, em vez disso, não deixe de escutar o evento bounds_changed.

Exemplo: eventos de editar e arrastar uma forma

Quando uma forma é editada ou arrastada, um evento é acionado na conclusão da ação. Para obter uma lista de eventos e alguns fragmentos de código, consulte Formas.

Ver o exemplo (rectangle-event.html)

Acesso a argumentos em eventos de IU

Eventos de IU dentro da Google Maps JavaScript API normalmente passam um argumento de evento, que pode ser acessado pelo detector de eventos, observando o estado da IU quando o evento ocorreu. Por exemplo, um evento de IU 'click' normalmente passa um MouseEvent contendo uma propriedade latLng que indica a localização clicada no mapa. Observe que esse comportamento é exclusivo de eventos de IU. As alterações de estado de MVC não passam argumentos em seus eventos.

Acesse os argumentos do evento em um ouvinte de eventos da mesma forma que acessa as propriedades de um objeto. O exemplo a seguir adiciona um ouvinte de eventos ao mapa e, quando o mapa é clicado pelo usuário, cria um marcador na posição clicada.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}

Ver o exemplo (event-arguments.html).

Uso de fechamentos em ouvintes de eventos

Na execução de um ouvinte de eventos, muitas vezes é vantajoso ter dados privados e persistentes anexados a um objeto. O JavaScript não permite dados de instância "privados", mas permite fechamentos, que possibilitam que funções internas acessem variáveis externas. Os fechamentos são úteis em ouvintes de eventos para acessar variáveis que normalmente não são anexadas aos objetos onde ocorrem os eventos.

O exemplo a seguir usa um fechamento de função no ouvinte de eventos para atribuir uma mensagem secreta a um conjunto de marcadores. Ao clicar em um marcador, uma parte da mensagem secreta, que não está propriamente dentro do marcador, é revelada.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random()
      },
      map: map
    });
    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random()
      },
      map: map
    });
    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}

Ver o exemplo (event-closure.html).

Obter e definir propriedades em manipuladores de eventos

Nenhum dos eventos de mudança de estado de MVC do sistema de eventos da Google Maps JavaScript API passa argumentos quando o evento é acionado. (Eventos de usuário passam argumentos, que podem ser examinados.) Se você precisa examinar uma propriedade em uma alteração de estado de MVC, chame explicitamente o método getProperty() adequado naquele objeto. Esse exame sempre recupera o estado atual do objeto MVC, que pode não ser o estado do momento em que o evento foi acionado pela primeira vez.

Observação: a definição explícita de uma propriedade em um manipulador de eventos que responde a uma alteração de estado naquela propriedade específica pode gerar comportamento imprevisível e/ou indesejado. Por exemplo, a definição dessa propriedade aciona um novo evento. Se você sempre define uma propriedade no manipulador de eventos, pode criar um loop infinito.

No exemplo a seguir, configuramos um manipulador de eventos para responder a eventos de zoom exibindo uma janela de informações naquele nível.

function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}

Ver o exemplo (event-properties.html).

Escutar eventos do DOM

O modelo de eventos da Google Maps JavaScript API cria e administra os próprios eventos personalizados. No entanto, o DOM (Document Object Model) no navegador também cria e despacha os próprios eventos, conforme o modelo de eventos específico do navegador usado. Para capturar e responder a esses eventos, a Maps JavaScript API oferece o método estático addDomListener() para detectar e vincular a eventos DOM.

Esse método de conveniência tem uma assinatura, como mostrado abaixo:

addDomListener(instance:Object, eventName:string, handler:Function)

onde instance pode ser qualquer elemento do DOM permitido pelo navegador, incluindo:

  • Membros hierárquicos do DOM, como window ou document.body.myform
  • Elementos nomeados como document.getElementById("foo")

Observe que addDomListener() simplesmente passa o evento indicado para o navegador, que o processa de acordo com o modelo de eventos DOM do navegador. No entanto, praticamente todos os navegadores modernos oferecem suporte ao DOM nível 2, no mínimo. (Para obter mais informações sobre os eventos do nível de DOM, consulte a referência Mozilla DOM Levels.)

Se você leu a documentação até aqui, provavelmente já conhece um evento do DOM: o evento window.onload, que processamos na tag <body>. Usamos esse evento para acionar código JavaScript adicional quando uma página HTML é carregada totalmente, como mostrado abaixo:

<script>
  function initialize() {

    // Map initialization

  }
</script>
<body onload="initialize()">
  <div id="map"></div>
</body>

Embora esse evento esteja anexado ao elemento <body> aqui, ele é realmente um evento window, indicando que a hierarquia do DOM abaixo do elemento window foi totalmente criada e renderizada.

Ainda que fácil de entender, um evento onload em uma tag <body> mistura conteúdo e comportamento. Normalmente, é uma prática recomendada separar o código de conteúdo (HTML) do código de comportamento (JavaScript), bem como fornecer separadamente o código de apresentação (CSS). É possível fazer isso substituindo o gerenciador de eventos onload em linha com um detector de DOM dentro do código da Maps JavaScript API, como mostrado abaixo:

<script>
  function initialize() {

    // Map initialization

  }

  google.maps.event.addDomListener(window, 'load', initialize);
</script>
<body>
  <div id="map"></div>
</body>

Ver o exemplo (event-domListener.html)

Embora o código acima seja código da Maps JavaScript API, o método addDomListener() é associado ao objeto window do navegador e permite que a API se comunique com objetos de fora do domínio normal da API.

Remover ouvintes de eventos

Para remover um ouvinte de eventos específico, ele deve estar atribuído a uma variável. Em seguida, chame removeListener() passando o nome da variável à qual o ouvinte foi atribuído.

var listener1 = marker.addListener('click', aFunction);

google.maps.event.removeListener(listener1);

Para remover todos os ouvintes de uma determinada instância, chame clearInstanceListeners() passando o nome da instância.

var listener1 = marker.addListener('click', aFunction);
var listener2 = marker.addListener('mouseover', bFunction);

// Remove listener1 and listener2 from marker instance.
google.maps.event.clearInstanceListeners(marker);

Para remover todos os ouvintes de um determinado tipo de evento para uma instância específica, chame clearListeners() passando o nome da instância e o nome do evento.

marker.addListener('click', aFunction);
marker.addListener('click', bFunction);
marker.addListener('click', cFunction);

// Remove all click listeners from marker instance.
google.maps.event.clearListeners(marker, 'click');

Para obter mais informações, consulte a documentação de referência para o espaço de nome google.maps.event.

Detecção de erros de autenticação

Se quiser detectar uma falha de autenticação programaticamente (por exemplo, enviar um sensor automaticamente), você pode preparar uma função de retorno de chamada. Se a função global a seguir for definida, ela será chamada quando houver uma falha de autenticação. function gm_authFailure() { /* Code */ };

Enviar comentários sobre…

Google Maps JavaScript API
Google Maps JavaScript API
Precisa de ajuda? Acesse nossa página de suporte.