Cómo actualizar tu aplicación de la API de Maps JavaScript de la versión 2 a la 3

Evento nuevo para la asistencia MVC

La API v3 agrega un nuevo tipo de evento para reflejar los cambios de estado de MVC. Ahora hay dos tipos de eventos:

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

Cada objeto de la Google Maps API exporta un número de eventos con nombre. Las aplicaciones interesadas en eventos específicos deben registrar objetos de escucha de eventos de esos eventos y ejecutar código cuando se reciben. Este mecanismo controlado por eventos es el mismo en las API de Maps JavaScript v2 y v3, excepto que el espacio de nombres cambió de GEvent a google.maps.event:

GEvent.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

google.maps.event.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

Cómo eliminar receptores de eventos

Por razones de rendimiento, es mejor quitar un objeto de escucha de eventos cuando ya no es necesario. Quitar un objeto de escucha de eventos funciona de la misma manera en la v2 y la v3:

1. Cuando creas un objeto de escucha de eventos, se muestra un objeto opaco (GEventListener en la versión 2, MapsEventListener en la versión 3).
2. Cuando desees quitar el objeto de escucha de eventos, pasa este objeto al método removeListener() (GEvent.removeListener() en la v2 o google.maps.event.removeListener() en la v3) para quitar el objeto de escucha de eventos.

Cómo escuchar eventos de DOM

Si deseas capturar y responder a eventos de DOM (Modelo de objeto del documento), v3 proporciona el método estático google.maps.event.addDomListener(), que equivale al método GEvent.addDomListener() en v2.

Usar argumentos pasados en eventos

A menudo, los eventos de la IU pasan un argumento de evento al que luego puede acceder el objeto de escucha de eventos. La mayoría de los argumentos de eventos en la v3 se simplificaron para ser más coherentes con los objetos de la API. (Consulta la referencia de la versión 3 para obtener más detalles).

No hay ningún argumento overlay en los objetos de escucha de eventos v3. Si registras un evento click en un mapa de la versión 3, la devolución de llamada solo se producirá cuando el usuario haga clic en el mapa base. Puedes registrar devoluciones de llamada adicionales en superposiciones en las que se puede hacer clic si necesitas reaccionar ante esos clics.

// Passes an overlay argument when clicking on a map

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

GEvent.addListener(map,'click', function(overlay, latlng) {
  if (latlng) {
    var marker = new GMarker(latlng);
    map.addOverlay(marker);
  }
});

// Passes only an event argument

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

google.maps.event.addListener(map, 'click', function(event) {
  var marker = new google.maps.Marker({
      position: event.latLng,
      map: map
  });
});

Cambios en los tipos de control

Se introdujeron algunos cambios en los tipos de control con la API v3.

1. La API de v3 admite tipos de mapas adicionales, incluidos los mapas de relieve y la capacidad de agregar tipos de mapas personalizados.
2. El control jerárquico de la v2, GHierarchicalMapTypeControl, ya no está disponible. Puedes lograr un efecto similar con el control google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. El diseño horizontal que proporciona GMapTypeControl en la v2 no está disponible en la v3.

Cómo agregar controles al mapa

Con la versión 2 de la API de Maps JavaScript, puedes agregar controles al mapa a través del método addControl() del objeto de mapa. En la versión 3, en lugar de acceder a los controles o modificarlos directamente, modifica el objeto MapOptions asociado. En el siguiente ejemplo, se muestra cómo personalizar el mapa para agregar los siguientes controles:

• botones que permiten al usuario activar o desactivar los tipos de mapas disponibles;
• una escala de mapa.

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP,

    // Add controls
    mapTypeControl: true,
    scaleControl: true
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Posicionar controles en el mapa

El posicionamiento de controles ha cambiado mucho en la v3. En la v2, el método addControl() toma un segundo parámetro opcional que te permite especificar la posición del control en relación con las esquinas del mapa.

En la v3, se establece la posición de un control a través de la propiedad position de las opciones de control. El posicionamiento de estos controles no es absoluto; en su lugar, la API los diseñará de manera inteligente mediante el flujo y los elementos alrededor del mapa existentes dentro de ciertas restricciones (como el tamaño del mapa). Esto asegura que los controles predeterminados sean compatibles con los tuyos. Consulta Control de posicionamiento en v3 para obtener más información.

El siguiente código cambia el posicionamiento de los controles de los ejemplos anteriores:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
    G_ANCHOR_TOP_LEFT, new GSize(10, 10)));

// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
    G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));

var myOptions = {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP,

  // Add map type control
  mapTypeControl: true,
  mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_LEFT
  },

  // Add scale
  scaleControl: true,
  scaleControlOptions: {
      position: google.maps.ControlPosition.BOTTOM_RIGHT
  }
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Controles personalizados

La API de Maps JavaScript te permite crear controles de navegación personalizados. Para personalizar los controles con la API v2, debes crear una subclase de la clase GControl y definir los controladores para los métodos initialize() y getDefaultPosition(). No hay equivalente a la clase GControl en la v3. En su lugar, los controles se representan como elementos del DOM. A fin de agregar un control personalizado con la API v3, crea una estructura de DOM para el control en un constructor como elemento secundario de un Node (p.ej., un elemento <div>) y agrega objetos de escucha de eventos para controlar cualquier evento de DOM. Envía el elemento Node al arreglo controls[position] de mapas para agregar una instancia del control personalizado a tu mapa.

Dada una implementación de la clase HomeControl que cumple con los requisitos de la interfaz mencionados anteriormente (consulta la documentación de Controles personalizados para obtener más detalles), en las siguientes muestras de código, se muestra cómo agregar un control personalizado a un mapa.

map.addControl(new HomeControl(),
    GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));

var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);

map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
    homeControlDiv);

Cómo agregar y quitar superposiciones

Los tipos de objetos representados por una superposición son los mismos entre la v2 y la v3, pero se manejan de manera diferente.

Las superposiciones en la API v2 se agregaron al mapa y se quitaron del mapa usando los métodos addOverlay() y removeOverlay() del objeto GMap2. En la versión 3, se asigna un mapa a una superposición a través de la propiedad map de la clase de opciones de superposición asociada. También puedes agregar o quitar una superposición directamente llamando al método setMap() del objeto de superposición y especificando el mapa deseado. Si estableces la propiedad del mapa en null, se quitará la superposición.

No existe el método clearOverlays() en la v3. Si deseas administrar un conjunto de superposiciones, debes crear un arreglo para contener las superposiciones. Con este arreglo, puedes llamar a setMap() en cada superposición del arreglo (y pasar null si necesitas quitarlas).

Marcadores arrastrables

De forma predeterminada, los marcadores son seleccionables, pero no arrastrables. En los siguientes dos ejemplos, se agrega un marcador arrastrable:

var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);

var marker = new GMarker(latLng, {
  draggable: true
});
map.addOverlay(marker);

var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
  document.getElementById('map'), {
  center: myLatLng,
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var marker = new google.maps.Marker({
    position: myLatLng,
    draggable: true,
    map: map
});

Íconos

Puedes definir un ícono personalizado que se mostrará en lugar del marcador predeterminado. Para usar una imagen personalizada en v2, puedes crear una instancia de GIcon a partir de G_DEFAULT_ICON type y modificarla. Si tu imagen es más grande o más pequeña que el ícono predeterminado, debes especificarla con una instancia de GSize. La API v3 ofrece una ligera simplificación de este proceso. Solo debes establecer la propiedad icon del marcador en la URL de tu imagen personalizada, y la API ajustará el tamaño del ícono automáticamente.

La Maps JavaScript API también proporciona compatibilidad con íconos complejos. Un ícono complejo puede incluir varios mosaicos y formas complejas, o especificar el orden de presentación de las imágenes respecto de otras superposiciones. Para agregar una forma a un marcador en la v2, debes especificar la propiedad adicional en cada instancia de GIcon y pasarla como una opción a un constructor GMarker. En la v3, los íconos especificados de esta manera deberían establecer sus propiedades de icon en un objeto de tipo Icon. Las sombras de marcadores no se admiten en la v3.

En los siguientes ejemplos, se muestra una bandera de playa en Bondi Beach, Australia, y no se puede hacer clic en la parte transparente del ícono:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);

map.addOverlay(new GMarker(bbLatLng, {
  icon: flagIcon
}));

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

var shape = {
    coord: [1, 1, 1, 20, 18, 20, 18 , 1],
    type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);

var bbMarker = new google.maps.Marker({
    icon: '/images/beachflag.png'
    shape: shape,
    position: bbLatLng,
    map: map
});

Polilíneas

Una polilínea consiste en un arreglo de LatLng, además de una serie de segmentos de líneas que conectan esas ubicaciones en una secuencia ordenada. Crear y mostrar un objeto Polyline en la v3 es similar a usar un objeto GPolyline en la v2. En los siguientes ejemplos, se dibuja una polilínea geodésica semitransparente de 3 píxeles de ancho desde Zúrich hasta Sídney y Singapur:

var polyline = new GPolyline(
  [
    new GLatLng(47.3690239, 8.5380326),
    new GLatLng(1.352083, 103.819836),
    new GLatLng(-33.867139, 151.207114)
  ],
  '#FF0000', 3, 0.5, {
  geodesic: true
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: [
    new google.maps.LatLng(47.3690239, 8.5380326),
    new google.maps.LatLng(1.352083, 103.819836),
    new google.maps.LatLng(-33.867139, 151.207114)
  ],
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
  geodesic: true
});

polyline.setMap(map);

Polilíneas codificadas

La v3 no admite la creación de objetos Polyline directamente a partir de polilíneas codificadas. En cambio, la biblioteca de geometría proporciona métodos para codificar y decodificar las polilíneas. Consulta Bibliotecas en la versión 3 de la API de Google Maps para obtener más información sobre cómo cargar esta biblioteca.

En los siguientes ejemplos, se dibuja la misma polilínea codificada; el código v3 usa el método decodePath() del espacio de nombres google.maps.geometry.encoding.

var polyline = new GPolyline.fromEncoded({
  points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
  levels: 'PPP',
  zoomFactor: 2,
  numLevels: 18,
  color: '#ff0000',
  opacity: 0.8,
  weight: 3
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: google.maps.geometry.encoding.decodePath(
    'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
});

polyline.setMap(map);

Polígonos

Un polígono define una región dentro de un bucle cerrado. Al igual que el objeto Polyline, los objetos Polygon consisten en una serie de puntos en una secuencia ordenada. La clase Polygon v3 es muy similar a la clase GPolygon v2, con la excepción notable de que ya no tienes que repetir el vértice de inicio al final de la ruta para cerrar el bucle. La API v3 cerrará de manera automática cualquier polígono dibujando un trazo que conecte la última coordenada con la primera. Con los siguientes fragmentos de código, se crea un polígono que representa el triángulo de las Bermudas:

var map = new GMap2(document.getElementById('map'));

map.setCenter(new GLatLng(24.886436, -70.268554), 5);

var bermudaTriangle = new GPolygon(
  [
    new GLatLng(25.774252, -80.190262),
    new GLatLng(18.466465, -66.118292),
    new GLatLng(32.321384, -64.75737),
    new GLatLng(25.774252, -80.190262)
  ],
  '#FF0000', 2, 0.8, '#FF0000', 0.35);

map.addOverlay(bermudaTriangle);

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(24.886436, -70.268554),
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  zoom: 5
});

var bermudaTriangle = new google.maps.Polygon({
  paths: [
    new google.maps.LatLng(25.774252, -80.190262),
    new google.maps.LatLng(18.466465, -66.118292),
    new google.maps.LatLng(32.321384, -64.75737)
  ],
  strokeColor: '#FF0000',
  strokeWeight: 2,
  strokeOpacity: 0.8,
  fillColor: '#FF0000',
  fillOpacity: 0.35
});

bermudaTriangle.setMap(map);

Formas que el usuario puede editar

Es posible hacer que los usuarios puedan editar polilíneas y polígonos. Los siguientes fragmentos de código son equivalentes:

map.addOverlay(polyline);
polyline.enableEditing();

polyline.setMap(map);
polyline.setEditable(true);

Para obtener funciones de dibujo más avanzadas, consulta la biblioteca de dibujos en la documentación de la v3.

Ventanas de información

Un elemento InfoWindow muestra contenido en una ventana flotante encima del mapa. Hay algunas diferencias claves entre las ventanas de información de la v2 y la v3:

• La API v2 admite solo GInfoWindow por mapa, mientras que la API v3 admite varias InfoWindow simultáneas en cada mapa.
• La versión 3 de InfoWindow permanecerá abierta cuando hagas clic en el mapa. La GInfoWindow v2 se cierra automáticamente cuando haces clic en el mapa. Puedes emular el comportamiento de la v2 si agregas un objeto de escucha click en el objeto Map.
• La API de v3 no proporciona compatibilidad nativa con un InfoWindow con pestañas.

Superposiciones de suelo

Para colocar una imagen en un mapa, debes usar un objeto GroundOverlay. En esencia, el constructor de un GroundOverlay es el mismo en v2 y v3: especifica una URL de una imagen y los límites de la imagen como parámetros.

En el siguiente ejemplo, se ubica un mapa antiguo de Newark, NJ, en el mapa como una superposición:

var bounds = new GLatLngBounds(
    new GLatLng(40.716216, -74.213393),
    new GLatLng(40.765641, -74.139235));

var overlay = new GGroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

map.addOverlay(overlay);

var bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(40.716216, -74.213393),
    new google.maps.LatLng(40.765641, -74.139235));

var overlay = new google.maps.GroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

overlay.setMap(map);

Tipos de mapa comunes

Los cuatro tipos de mapa básicos se encuentran disponibles en la v2 y la v3:

• MapTypeId.ROADMAP (reemplaza a G_NORMAL_MAP) muestra la vista del mapa de ruta.
• MapTypeId.SATELLITE (reemplaza a G_SATELLITE_MAP) muestra las imágenes satelitales de Google Earth.
• MapTypeId.HYBRID (reemplaza a G_HYBRID_MAP) muestra una combinación de vistas normales y satelitales.
• MapTypeId.TERRAIN (reemplaza a G_PHYSICAL_MAP) muestra un mapa físico basado en la información del terreno.

A continuación, se muestra un ejemplo de la v2 y la v3 en el que se fija el mapa en la vista de terreno:

map.setMapType(G_PHYSICAL_MAP);
    

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    

La Maps JavaScript API v3 también realizó algunos cambios en los tipos de mapa menos comunes:

• Los mosaicos de mapas para cuerpos celestes que no sean de Earth no están disponibles como tipos de mapas en la API v3, pero se puede acceder a ellos como tipos de mapas personalizados, como se muestra en este ejemplo.
• No hay un tipo de mapa especial en la v3 que reemplace el tipo G_SATELLITE_3D_MAP de la v2. En su lugar, puedes integrar el complemento de Google Earth en tus mapas v3 con esta biblioteca.

Imágenes con zoom máximo

Las imágenes satelitales no están disponibles a niveles de zoom elevados. Si quieres conocer el nivel de zoom más alto disponible antes de configurarlo, usa la clase google.maps.MaxZoomService. Esta clase reemplaza el método GMapType.getMaxZoomAtLatLng() de la versión 2.

var point = new GLatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);

map.getCurrentMapType().getMaxZoomAtLatLng(point,
  function(response) {
    if (response.status) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

var myLatlng = new google.maps.LatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
  document.getElementById("map"),{
    zoom: 0,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
  myLatlng,
  function(response) {
    if (response.status == google.maps.MaxZoomStatus.OK) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

Imágenes de perspectiva aérea

Cuando se habilitan las imágenes aéreas en la v3, los controles son similares al control GLargeZoomControl3D de la v2, con un control de rotación intersticial adicional para rotar las instrucciones compatibles.

Puedes hacer un seguimiento de las ciudades en las que las imágenes a 45° están disponibles en este mapa. Cuando las imágenes a 45° están disponibles, se agrega una opción de submenú al botón Satélite de la API de Google Maps.