Eventos

Selecione a plataforma: Android iOS JavaScript

Esta página descreve os eventos da interface do usuário e eventos de erro que você pode detectar e processar de maneira programática.

Eventos da interface do usuário

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

  • Eventos de usuário (como eventos de mouse e cliques) são propagados do DOM para a API Maps JavaScript. Esses eventos são separados e distintos dos eventos DOM padrão.
  • As notificações de mudança de estado do MVC refletem as mudanças nos objetos da API Maps JavaScript e são nomeadas usando uma convenção property_changed.

Cada objeto da API Maps JavaScript exporta vários eventos nomeados. Os programas interessados em determinados eventos registrarão listeners de eventos JavaScript para esses eventos e executarão o código quando esses eventos forem recebidos chamando addListener() para registrar os manipuladores de eventos no objeto.

O exemplo abaixo mostra quais eventos são acionados pela google.maps.Map conforme você interage com o mapa.

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

Eventos de interface de usuário

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

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

Para ver a lista completa, consulte a classe Marker. Esses eventos podem parecer eventos DOM padrão, mas, na verdade, fazem parte da API Maps JavaScript. Como navegadores diferentes implementam modelos de evento DOM distintos, a API Maps JavaScript fornece esses mecanismos para detectar e responder a eventos DOM sem precisar processar as diversas peculiaridades de vários navegadores. Esses eventos também costumam transmitir argumentos dentro do evento observando 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 uma propriedade de um objeto muda, a API Maps JavaScript aciona um evento que a propriedade mudou. Por exemplo, a API disparará um evento zoom_changed em um mapa quando o nível de zoom do mapa mudar. Você também pode interceptar essas mudanças de estado chamando addListener() para registrar manipuladores de eventos no objeto.

Eventos de usuário e alterações de estado do MVC podem parecer semelhantes, mas geralmente é recomendável tratá-los de forma diferente no seu código. Os eventos de MVC, por exemplo, não transmitem argumentos dentro do evento. Para inspecionar a propriedade que mudou em uma mudança de estado do MVC, chame o método getProperty apropriado nesse objeto.

Processar eventos

Para se inscrever para receber notificações de eventos, use o manipulador de eventos addListener(). Esse método usa um evento a ser detectado e uma função a ser chamada quando ocorrer o evento especificado.

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 aumenta o zoom do mapa quando clicado. Também adicionamos um manipulador de eventos ao mapa para fazer alterações na propriedade center e movimentamos o mapa de volta ao marcador três segundos após o recebimento do evento center_changed:

TypeScript

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

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: myLatlng,
    }
  );

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

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.getPosition() as google.maps.LatLng);
    }, 3000);
  });

  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.getPosition() as google.maps.LatLng);
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
  });
  const marker = new google.maps.Marker({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.getPosition());
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

window.initMap = initMap;
Ver exemplo

Testar amostra

Dica: se você estiver tentando detectar uma mudança na janela de visualização, use o evento bounds_changed específico, em vez dos eventos zoom_changed e center_changed constituintes. Como a API Maps JavaScript aciona esses últimos eventos de maneira independente, é possível que o getBounds() não informe resultados úteis até que a janela de visualização seja alterada de maneira autorizada. Se você quiser getBounds() após esse evento, detecte o evento bounds_changed.

Exemplo: eventos para editar e arrastar formas

Quando uma forma é editada ou arrastada, um evento é disparado após a conclusão da ação. Para ver uma lista dos eventos e alguns snippets de código, consulte Formas.

Ver exemplo (rectangle-event.html)

Acessar argumentos em eventos de IU

Os eventos de IU na API Maps JavaScript normalmente transmitem um argumento de evento, que pode ser acessado pelo listener de eventos, observando o estado da IU quando o evento ocorreu. Por exemplo, um evento 'click' da IU normalmente transmite um MouseEvent contendo uma propriedade latLng que indica o local clicado no mapa. Esse comportamento é exclusivo dos eventos da IU. As mudanças de estado do MVC não transmitem argumentos nos eventos.

É possível acessar os argumentos do evento em um listener de eventos da mesma forma que você acessaria as propriedades de um objeto. O exemplo a seguir adiciona um listener de eventos ao mapa e cria um marcador quando o usuário clica no mapa no local clicado.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
    }
  );

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng: google.maps.LatLng, map: google.maps.Map) {
  new google.maps.Marker({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

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

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

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

window.initMap = initMap;
Ver exemplo

Testar amostra

Usar fechamentos em ouvintes de eventos

Ao executar um listener de eventos, é vantajoso ter dados particulares e permanentes anexados a um objeto. O JavaScript não aceita dados de instância "quot;private", mas oferece suporte a bloqueios, que permitem que funções internas acessem variáveis externas. As interdições são úteis em listeners de eventos para acessar variáveis que normalmente não são anexadas aos objetos em que os eventos ocorrem.

O exemplo a seguir usa um fechamento de função no listener de eventos para atribuir uma mensagem secreta a um conjunto de marcadores. Clicar em cada marcador revelará uma parte da mensagem secreta, que não está contida no próprio marcador.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
    }
  );

  const bounds: google.maps.LatLngBoundsLiteral = {
    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.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const 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: google.maps.Marker,
  secretMessage: string
) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.get("map"), marker);
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
  });
  const 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.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const 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) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.get("map"), marker);
  });
}

window.initMap = initMap;
Ver exemplo

Testar amostra

Como receber e definir propriedades nos manipuladores de eventos

Nenhum dos eventos de alteração de estado do MVC no sistema de eventos da API Maps JavaScript transmite argumentos quando o evento é acionado. Os eventos do usuário passam argumentos que podem ser inspecionados. Se você precisar inspecionar uma propriedade em uma mudança de estado do MVC, chame explicitamente o método getProperty() apropriado nesse objeto. Essa inspeção sempre recuperará o estado atual do objeto MVC, que pode não ser o estado quando o evento é disparado pela primeira vez.

Observação: a configuração explícita de uma propriedade em um manipulador de eventos que responde a uma mudança de estado dessa propriedade específica pode causar um comportamento imprevisível e/ou indesejado. A definição dessa propriedade acionará um novo evento, por exemplo, e se você sempre definir uma propriedade nesse manipulador de eventos, poderá acabar criando um loop infinito.

No exemplo abaixo, configuramos um manipulador de eventos para responder a eventos de zoom mostrando uma janela de informações com esse nível.

TypeScript

function initMap(): void {
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: originalMapCenter,
    }
  );

  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);

  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom()!);
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: originalMapCenter,
  });
  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);
  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom());
  });
}

window.initMap = initMap;
Ver exemplo

Testar amostra

Escutar eventos do DOM

O modelo de eventos da API Maps JavaScript cria e gerencia os próprios eventos personalizados. No entanto, o DOM (modelo de objeto de documento) no navegador também cria e envia seus próprios eventos, de acordo com o modelo de evento específico do navegador em uso. Se você quiser capturar e responder a esses eventos, a API Maps JavaScript fornecerá o método estático addDomListener() para detectar e se vincular a eventos DOM.

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

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

em que instance pode ser qualquer elemento DOM suportado pelo navegador, incluindo:

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

Observe que addDomListener() transmite o evento indicado para o navegador, que o processa de acordo com o modelo de evento DOM do navegador. No entanto, quase todos os navegadores modernos têm suporte para o DOM nível 2. Para mais informações sobre eventos de nível do DOM, consulte a referência Níveis do DOM do Mozilla.

TypeScript

function initMap(): void {
  const mapDiv = document.getElementById("map") as HTMLElement;
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const mapDiv = document.getElementById("map");
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

window.initMap = initMap;

HTML

<html>
  <head>
    <title>Listening to DOM 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>
    <div id="map"></div>

    <!-- 
     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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
Ver exemplo

Testar amostra

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

Remover ouvintes de eventos

Para remover um listener de evento específico, ele precisa ter sido atribuído a uma variável. Em seguida, você pode chamar removeListener(), transmitindo o nome da variável a que o listener foi atribuído.

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

google.maps.event.removeListener(listener1);

Para remover todos os listeners de uma instância específica, chame clearInstanceListeners(), transmitindo 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 listeners de um tipo de evento específico de 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 mais informações, consulte a documentação de referência do namespace google.maps.event.

Detectar erros de autenticação

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