Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar la Google Maps JavaScript API

Para que puedas comenzar, te proporcionaremos orientación en la Google Developers Console a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar la Google Maps JavaScript API y servicios relacionados
  3. Crear claves correspondientes
Continuar

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

Dentro del navegador, JavaScript es controlado por eventos. Esto significa que responde a interacciones generando eventos y espera que un programa escuche eventos que resulten interesantes. Existen dos tipos de eventos:

  • Los eventos de usuario (como eventos “clic” del mouse) se propagan del modelo de objeto de documento (DOM) a la Google Maps JavaScript API. Estos eventos son independientes y diferentes de los eventos estándares de DOM.
  • Las notificaciones de cambio de estado de MVC reflejan cambios en objetos de la Maps JavaScript API y sus nombres se establecen con una convención property_changed.

Cada objeto de la Maps JavaScript API exporta varios eventos con nombre. Los programas que buscan determinados tipos de eventos registrarán receptores de eventos JavaScript para dichos eventos y ejecutarán código cuando estos se reciban llamando a addListener() para registrar controladores de eventos en el objeto.

En el ejemplo siguiente, se muestran los eventos que se activan a través de google.maps.Map cuando interactúas con el mapa.

Para conocer la lista completa de eventos, consulta la referencia de la Google Maps JavaScript API. Los eventos se mencionan en una sección separada para cada objeto que contenga eventos.

Eventos de la IU

Algunos objetos de la Google Maps JavaScript API están diseñados para responder a eventos de usuario (por ejemplo, eventos del mouse o del teclado). A continuación, por ejemplo, se ofrecen algunos de los eventos de usuario que puede escuchar un objeto google.maps.Marker:

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

Para conocer la lista completa, consulta la clase Marker. Es posible que estos eventos sean parecidos a eventos de DOM estándares pero, en realidad, son parte de la Maps JavaScript API. Dado que distintos navegadores implementan distintos modelos de eventos de DOM, la Maps JavaScript API proporciona estos mecanismos para detectar eventos de DOM y responder a ellos sin necesidad de lidiar con los diferentes aspectos de los distintos navegadores. Estos eventos, normalmente, 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 se modifique la propiedad de un objeto, la Google Maps JavaScript API activará los eventos que la propiedad haya cambiado. Por ejemplo, la API activará un evento zoom_changed en un mapa cuando se modifique el nivel de zoom de dicho mapa. Puedes interceptar estos cambios de estado llamando a addListener() para registrar también controladores de eventos en el objeto.

Los eventos de usuario y los cambios de estado de MVC pueden parecerse, pero generalmente te convendrá darles un tratamiento diferente en tu código. Los eventos de MVC, por ejemplo, no pasan argumentos dentro de su evento. Te convendrá inspeccionar la propiedad que se modificó al cambiar el estado de un MVC llamando al método getProperty correspondiente de dicho objeto.

Cómo administrar eventos

Si deseas generar un registro de notificaciones de eventos, usa el controlador de eventos addListener(). Ese método recibe un evento que debe detectarse y una función que se debe que llamar cuando tiene lugar el evento especificado.

Ejemplo: Eventos de mapas y marcadores

En el código siguiente se combinan eventos de usuario y eventos de cambio de estado. Se adjunta un controlador de eventos a un marcador que aplica zoom al mapa cuando se hace clic sobre él. También se agrega al mapa un controlador de eventos para cambios en la propiedad center, y para que el mapa vuelva a desplazarse hacia el marcador 3 segundos después de la recepción del 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 el ejemplo (event-simple.html).

Sugerencia: Si intentas detectar un cambio en el viewport, asegúrate de usar el evento bounds_changed en lugar de los eventos zoom_changed y center_changed. Debido a que la Maps JavaScript API activa estos últimos eventos de manera independiente, es posible que getBounds() no brinde resultados útiles hasta que la ventana de visualización haya cambiado de manera autoritaria. Si deseas aplicar getBounds() después de un evento como este, asegúrate de escuchar el evento bounds_changed en su lugar.

Ejemplo: eventos de edición y arrastre de formas

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

Ver el ejemplo (rectangle-event.html)

Cómo acceder a argumentos de eventos de la IU

Por lo general, los eventos de IU de la Google Maps JavaScript API pasan un argumento de evento, al cual tiene acceso el receptor de eventos, y registran el estado de la IU cuando se produce el evento. Por ejemplo, un evento de IU 'click' normalmente pasa un MouseEvent que contiene una propiedad latLng, la cual denota la ubicación seleccionada 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 receptor de eventos de la misma manera en que accederías a las propiedades un objeto. En el ejemplo siguiente se agrega un receptor de eventos para el mapa y se crea un marcador cuando el usuario hace clic en la ubicación seleccionada del mapa.

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 el ejemplo (event-arguments.html).

Cómo usar cierres en receptores de eventos

Al ejecutar un receptor de eventos, a menudo resulta beneficioso adjuntar datos privados y persistentes a un objeto. JavaScript no admite datos de instancias “privados”, pero sí admite cierres, lo cual permite que las funciones internas accedan a variables externas. Los cierres resultan útiles dentro de los receptores de eventos para el acceso a variables que normalmente no se adjuntan a los objetos en los cuales tienen lugar los eventos.

En el siguiente ejemplo se usa un cierre de función en el receptor de eventos para asignar un mensaje secreto a un conjunto de marcadores. Si se hace clic en cada marcador, se revelará una parte del mensaje secreto, que no es parte del marcador.

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 el ejemplo (event-closure.html).

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 Google Maps JavaScript API pasa argumentos cuando se activa el evento. (Los eventos de usuario pasan argumentos que pueden inspeccionarse). Si necesitas inspeccionar una propiedad que se modificó al cambiar el estado de un MVC, debes llamar de manera explícita al método getProperty() correspondiente de dicho objeto. Esta inspección siempre recuperará el estado actual del objeto de MVC, que probablemente no sea el estado cuando el evento se activó por primera vez.

Nota: La configuración explícita de una propiedad dentro de un controlador de eventos que responde a un cambio de estado de dicha propiedad en particular puede producir un comportamiento impredecible y no deseado. La configuración de tal propiedad activará un nuevo evento, por ejemplo, y si siempre configuras una propiedad dentro de este controlador de eventos es posible que finalmente generes un bucle infinito.

En el ejemplo siguiente, 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 en cuestión.

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 el ejemplo (event-properties.html).

Cómo escuchar eventos de DOM

El modelo de eventos de la Google Maps JavaScript API crea y administra sus propios niveles personalizados. Sin embargo, el DOM (Document Object Model) del navegador también crea y despacha sus propios eventos según el modelo de eventos del navegador en uso. Si deseas capturar estos eventos, y responder a ellos, la Maps JavaScript API proporciona el método estático addDomListener() para detectar eventos de DOM y establecer enlaces a ellos.

Este método de conveniencia tiene una firma, como se muestra a continuación:

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

donde instance puede ser cualquier elemento de DOM admitido por el navegador, y se incluye lo siguiente:

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

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

Si has leído la documentación hasta este punto, probablemente ya estés familiarizado con un evento de DOM que hemos administrado dentro de la etiqueta <body>: el evento window.onload. Usamos este evento para activar el código de JavaScript inicial una vez que se carga por completo una página HTML, como se muestra a continuación:

<script>
  function initialize() {

    // Map initialization

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

Aunque este evento se adjunta al elemento <body>, en verdad es un evento window que indica que la jerarquía de DOM debajo del elemento window se creó y representó por completo.

Si bien esto es fácil de comprender, cuando hay un evento onload dentro de una etiqueta <body> se combina contenido y comportamiento. Generalmente, una práctica recomendada consiste en separar el código de contenido (HTML) del código de comportamiento (JavaScript) y ofrecer el código de presentación (CSS) por separado también. Para hacerlo, reemplaza el gestor de eventos onload integrado con un receptor de DOM en tu código de la Maps JavaScript API:

<script>
  function initialize() {

    // Map initialization

  }

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

Ver el ejemplo (event-domListener.html)

Si bien el código anterior es código de la Maps JavaScript API, el método addDomListener() establece un enlace con el objeto window del navegador y permite que la API se comunique con objetos fuera de su ámbito normal.

Cómo eliminar receptores de eventos

Para eliminar un receptor de eventos específico, este debe estar asignado a una variable. Puedes, entonces, llamar a removeListener() y pasar el nombre de variable al cual se asignó el receptor.

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

google.maps.event.removeListener(listener1);

Para eliminar todos los receptores 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 eliminar todos los receptores de un tipo de evento específico de una instancia específica, llama a clearListeners() y pasa los nombres de la instancia y 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');

Para obtener más información, consulta la documentación de referencia del espacio de nombres de google.maps.event.

Detectar errores de autenticación

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

Enviar comentarios sobre...

Google Maps JavaScript API
Google Maps JavaScript API
Si necesitas ayuda, visita nuestra página de asistencia.