Eventos

En esta página, se describen los eventos de interfaz de usuario y de error que puedes escuchar y gestionar de forma programática.

Eventos de interfaz de usuario

En el navegador, JavaScript se controla mediante eventos, lo que significa que responde a interacciones mediante la generación de eventos y espera que un programa escuche los eventos interesantes. Existen dos tipos de eventos:

• Los eventos de usuario (como los eventos de "clic" del mouse) se propagan del DOM a la API de Maps JavaScript. Estos eventos son independientes y diferentes de los eventos estándares del DOM.
• Las notificaciones de cambio de estado de MVC reflejan cambios en los objetos de la API de Maps JavaScript y se nombran mediante una convención property_changed.

Cada objeto de la API de Maps JavaScript exporta una cantidad determinada de eventos con nombre. Los programas interesados en ciertos eventos registran objetos de escucha de eventos de JavaScript para esos eventos y ejecutan código cuando dichos eventos se reciben mediante llamadas a addListener() para registrar controladores de eventos en el objeto.

En el siguiente ejemplo, se muestran los eventos que activa google.maps.Map a medida que interactúas con el mapa.

Para obtener una lista completa de eventos, consulta la referencia de la API de Maps JavaScript. Los eventos se incluyen en una sección separada para cada objeto que contiene eventos.

Eventos de la IU

Algunos objetos de la API de Maps JavaScript están diseñados para responder a los eventos de los usuarios, como los eventos de mouse o de teclado. Por ejemplo, estos son algunos de los eventos de usuario que un objeto google.maps.Marker puede escuchar:

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

Para ver la lista completa, consulta la clase Marker. Estos eventos pueden parecer eventos de DOM estándares, pero en realidad forman parte de la API de Maps JavaScript. Dado que los distintos navegadores implementan diferentes modelos de eventos de DOM, la API de Maps JavaScript proporciona estos mecanismos para escuchar los eventos de DOM y responder a ellos sin necesidad de administrar las diversas peculiaridades de los distintos navegadores. Por lo general, estos eventos, también pasan argumentos dentro del evento en los que se menciona algún estado de IU (como la posición del mouse).

Cambios de estado de MVC

Los objetos de MVC normalmente contienen estados. Cuando cambia la propiedad de un objeto, la API de Maps JavaScript activa un evento que indica que la propiedad cambió. Por ejemplo, la API activará un evento zoom_changed en un mapa cuando cambie el nivel de zoom correspondiente. Puedes interceptar estos cambios de estado llamando a addListener() para registrar también los controladores de eventos en el objeto.

Los eventos de usuario y los cambios de estado de MVC pueden parecerse, pero, por lo general, es conveniente darles un tratamiento diferente en el código. Los eventos de MVC, por ejemplo, no pasan argumentos dentro de su evento. Te recomendamos inspeccionar la propiedad que se modificó a causa de un cambio de estado de MVC llamando al método getProperty apropiado en ese objeto.

Cómo administrar eventos

Si deseas registrarte para recibir notificaciones de eventos, usa el controlador de eventos addListener(). Este método establece un evento que debe escucharse y una función a la que se debe llamar cuando ocurre el evento especificado.

Ejemplo: eventos de mapas y marcadores

En el siguiente código, se combinan eventos de usuario y eventos de cambio de estado. Para ello, se adjunta un controlador de eventos a un marcador que aplica zoom al mapa cuando se hace clic sobre él. A su vez, se agrega un controlador de eventos al mapa para realizar cambios en la propiedad center y desplazar el mapa nuevamente al marcador después de 3 segundos de recibir el evento center_changed:

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;
index.ts

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;
index.js

Sugerencia: Si intentas detectar un cambio en el viewport, asegúrate de usar el evento bounds_changed específico, en lugar de los eventos constitutivos zoom_changed y center_changed. Dado que la API de Maps JavaScript activa estos últimos eventos de forma independiente, es posible que getBounds() no informe resultados útiles hasta después de que el viewport cambie de manera autoritaria. Si deseas usar getBounds() después de un evento de este tipo, asegúrate de escuchar el evento bounds_changed.

Ejemplo: eventos de edición y arrastre de formas

Cuando se edita o se arrastra una forma, se activa un evento al completarse la acción. Para obtener una lista de los eventos y algunos fragmentos de código, consulta Formas.

Ver ejemplo (rectangle-event.html)

Cómo acceder a argumentos de eventos de la IU

Por lo general, los eventos de IU de la API de Maps JavaScript pasan un argumento de evento, al que puede acceder el objeto de escucha de eventos y detectar el estado de la IU cuando ocurrió el evento. Por ejemplo, un evento 'click' de IU suele pasar un MouseEvent que contiene una propiedad latLng que denota la ubicación en la que se hizo clic en el mapa. Ten en cuenta que este comportamiento es exclusivo de los eventos de la IU. Los cambios de estado de MVC no pasan argumentos en sus eventos.

Puedes acceder a los argumentos del evento dentro de un objeto de escucha de eventos de la misma manera en que accederías a las propiedades un objeto. En el siguiente ejemplo, se agrega un objeto de escucha de eventos para el mapa y se crea un marcador cuando el usuario hace clic en la ubicación seleccionada en el mapa.

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;
index.ts

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;
index.js

Cómo usar cierres en objetos de escucha de eventos

Cuando se ejecuta un objeto de escucha de eventos, a menudo es conveniente adjuntar datos privados y persistentes a un objeto. JavaScript no admite los datos de instancias "privados", pero sí admite cierres, los cuales permiten que las funciones internas accedan a variables externas. Los cierres son útiles en los objetos de escucha de eventos, ya que permiten acceder a variables que normalmente no se adjuntan a los objetos en los que ocurren los eventos.

En el siguiente ejemplo, se usa un cierre de función en el objeto de escucha de eventos para asignar un mensaje secreto a un conjunto de marcadores. Al hacer clic en cada marcador, se muestra una parte del mensaje secreto, que no es parte del marcador.

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;
index.ts

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;
index.js

Cómo obtener y configurar propiedades en controladores de eventos

Ninguno de los eventos de cambio de estado de MVC que corresponden al sistema de eventos de la API de Maps JavaScript pasa argumentos cuando se activa el evento. (Los eventos de usuario sí pasan argumentos que pueden inspeccionarse). Si necesitas inspeccionar una propiedad en un cambio de estado de MVC, debes llamar explícitamente al método getProperty() correcto en ese objeto. Esta inspección siempre recupera el estado actual del objeto MVC, que puede ser diferente del estado vigente cuando se activó el evento por primera vez.

Nota: Configurar explícitamente una propiedad dentro de un controlador de eventos que responde a un cambio de estado de esa propiedad en particular puede generar un comportamiento impredecible o no deseado. La configuración de dicha propiedad activará un nuevo evento, por ejemplo, y si siempre configuras una propiedad dentro de este controlador de eventos, podrías generar un bucle infinito.

En el siguiente ejemplo, se configura un controlador de eventos para responder a eventos de zoom mediante la aparición de una ventana de información en la que se muestra el nivel.

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;
index.ts

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;
index.js

Cómo escuchar eventos del DOM

El modelo de eventos de la API de Maps JavaScript crea y administra sus propios eventos personalizados. Sin embargo, el DOM (Modelo de objetos del documento) del navegador también crea y despacha sus propios eventos según el modelo de eventos del navegador en uso. Si deseas capturar esos eventos y responder a ellos, la API de Maps JavaScript proporciona el método estático addDomListener() para escuchar eventos de DOM y vincularse a ellos.

Este método práctico tiene una firma, como se muestra a continuación:

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

En el ejemplo anterior, instance puede ser cualquier elemento de DOM admitido por el navegador, incluidos los siguientes:

• Miembros jerárquicos del DOM, como window o document.body.myform
• Elementos con nombre, como document.getElementById("foo")

Ten en cuenta que addDomListener() pasa el evento indicado al navegador, el cual lo administra según el modelo de eventos de DOM del navegador. Sin embargo, casi todos los navegadores actualizados admiten al menos el nivel de DOM 2. (Para obtener más información sobre eventos de nivel de DOM, consulta la referencia de Niveles de DOM de Mozilla).

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;
index.ts

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;
index.js

<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.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Si bien el código anterior es el código de la API de Maps JavaScript, el método addDomListener() se vincula al objeto window del navegador y permite que la API se comunique con objetos externos a su dominio normal.

Cómo quitar objetos de escucha de eventos

Para quitar un objeto de escucha de eventos específico, este debe estar asignado a una variable. Luego, puedes llamar a removeListener() y pasar el nombre de la variable a la que se asignó el objeto de escucha.

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

google.maps.event.removeListener(listener1);

Para quitar todos los objetos de escucha de una instancia en particular, llama a clearInstanceListeners() y pasa el nombre de la instancia.

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 quitar todos los objetos de escucha de un tipo de evento específico correspondientes a una instancia específica, llama a clearListeners() y pasa el nombre de la instancia y el nombre del 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');

Si deseas obtener más información, consulta la documentación de referencia sobre el espacio de nombres google.maps.event.

Cómo detectar errores de autenticación

Si deseas detectar una autenticación no exitosa de forma programática (por ejemplo, para enviar una baliza automáticamente), puedes preparar una función de devolución de llamada. Si se define la siguiente función global, se la llamará cuando falle la autenticación. function gm_authFailure() { /* Code */ };