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 del usuario (como los eventos de "clic" del mouse) se propagan del DOM a la API de Maps JavaScript. Estos eventos son independientes y distintos de los eventos estándar del DOM.
• Las notificaciones de cambio de estado de MVC reflejan cambios en los objetos de la API de Google Maps y se nombran con 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 para esos eventos y ejecutar código cuando se reciben. Este mecanismo controlado por eventos es el mismo en la versión 2 y 3 de la API de Maps JavaScript, 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 quitar objetos de escucha de eventos

Por motivos de rendimiento, es mejor quitar un objeto de escucha de eventos cuando ya no es necesario. La eliminación de un objeto de escucha de eventos funciona de la misma manera en las versiones 2 y 3:

1. Cuando creas un objeto de escucha de eventos, se muestra un objeto opaco (GEventListener en la versión 2 y 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 versión 2 o google.maps.event.removeListener() en la versión 3) para quitar el objeto de escucha de eventos.

Cómo escuchar eventos del DOM

Si deseas capturar eventos de DOM (Modelo de objetos del documento), y responder a ellos, la versión 3 proporciona el método estático google.maps.event.addDomListener() equivalente al método GEvent.addDomListener() en la versión 2.

Usar argumentos pasados en eventos

A menudo, los eventos de la IU pasan un argumento de evento al que el objeto de escucha de eventos puede acceder. La mayoría de los argumentos de eventos en la versión 3 se simplificaron para que tengan una mayor coherencia con respecto a los objetos de la API. (consulta la referencia de la versión 3 para obtener más información).

No existe ningún argumento overlay en los objetos de escucha de eventos de la versión 3. 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 las superposiciones en las que se puede hacer clic si necesitas reaccionar a 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 v3 admite tipos de mapas adicionales, como mapas de terreno y la capacidad de agregar tipos de mapas personalizados.
2. El control jerárquico de la versión 2, 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 a tu mapa mediante el método addControl() de tu objeto de mapa. En la versión 3, en lugar de acceder a los controles o modificarlos directamente, se 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 versión 2, el método addControl() incluye un segundo parámetro opcional que te permite especificar la posición del control en relación con las esquinas del mapa.

En la versión 3, se establece la posición de un control a través de la propiedad position de las opciones del control. El posicionamiento de estos controles no es absoluto; en cambio, la API diseñará los controles de manera inteligente haciendo que "fluyan" alrededor de los elementos del mapa existentes dentro de determinadas restricciones (como el tamaño del mapa). Esto asegura que los controles predeterminados sean compatibles con los tuyos. Consulta Posicionamiento de controles en la versión 3 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 subclasificar la clase GControl y definir controladores para los métodos initialize() y getDefaultPosition(). No hay un equivalente para la clase GControl en la versión 3. En cambio, los controles están representados como elementos del DOM. Si deseas 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 Node al array controls[position] de los mapas para agregar una instancia del control personalizado a tu mapa.

Dada una implementación de clase HomeControl que cumple con los requisitos de interfaz mencionados anteriormente (consulta la documentación sobre controles personalizados para obtener más detalles), en las siguientes muestras de código, se indica 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 que representa una superposición son los mismos en la v2 y la v3, sin embargo, se controlan de manera diferente.

En la API v2, se agregaron al mapa y se quitaron las superposiciones mediante los métodos addOverlay() y removeOverlay() del objeto GMap2. En la versión 3, se asigna un mapa a una superposición mediante la propiedad map de la clase asociada de opciones de superposición. 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 se establece la propiedad del mapa en null, se quitará la superposición.

No existe un método clearOverlays() en la versión 3. Si deseas administrar un conjunto de superposiciones, debes crear un array que las contenga. Con este array, puedes llamar a setMap() en cada superposición del array (y pasar null si necesitas quitarlos).

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 la versión 2, puedes crear una instancia de GIcon desde 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 GSize. La API v3 ofrece una ligera simplificación de este proceso. Simplemente configura la propiedad icon del marcador con la URL de tu imagen personalizada, y la API ajustará el tamaño del ícono automáticamente.

La API de Maps JavaScript también proporciona compatibilidad con íconos complejos. Un ícono complejo puede incluir varios mosaicos y formas complejas, o bien especificar el "orden de pila" con el que se deben mostrar las imágenes en relación con otras superposiciones. Para agregar una forma a un marcador en la versión 2, debes especificar la propiedad adicional en cada instancia de GIcon y pasarla como opción a un constructor GMarker. En la versión 3, los íconos especificados de esta manera deben establecer sus propiedades 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. 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 array de elementos LatLng y una serie de segmentos de líneas que conectan esas ubicaciones en una secuencia ordenada. Crear y mostrar un objeto Polyline en la versión 3 es similar a usar un objeto GPolyline en la versión 2. En los siguientes ejemplos, se dibuja una polilínea geodésica semitransparente de 3 píxeles de ancho desde Zúrich hasta Sídney, pasando por 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 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 de la 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. De manera similar al objeto Polyline, los objetos Polygon constan de una serie de puntos en una secuencia ordenada. La clase Polygon de la versión 3 es muy similar a la clase GPolygon de la versión 2, con la excepción notable de que ya no es necesario repetir el vértice inicial al final de la ruta de acceso para cerrar el bucle. La API v3 cerrará automáticamente 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 capacidades de dibujo más avanzadas, consulta la Biblioteca de dibujos en la documentación de la v3.

Ventanas de información

Un objeto 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 solo admite GInfoWindow por mapa, mientras que la API v3 admite varios InfoWindow simultáneos en cada mapa.
• La versión 3 InfoWindow permanecerá abierta cuando hagas clic en el mapa. La versión 2 GInfoWindow se cierra automáticamente cuando haces clic en el mapa. Puedes emular el comportamiento de la versión 2 agregando un objeto de escucha click en el objeto Map.
• La API v3 no proporciona compatibilidad nativa para un InfoWindow con pestañas.

Superposiciones de suelo

Para colocar una imagen en un mapa, debes usar un objeto GroundOverlay. El constructor de una GroundOverlay es, básicamente, el mismo en la v2 y la v3: especifica la 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, Nueva Jersey, 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 de 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 versión 3 de la API de Maps JavaScript también realizó algunos cambios en los tipos de mapas menos comunes:

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

Imágenes con zoom máximo

Las imágenes satelitales no están disponibles a niveles de zoom elevados. Si deseas conocer el nivel de zoom más alto disponible antes de establecer el nivel de zoom, 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 habilitas las imágenes aéreas en la versión 3, los controles son similares al control GLargeZoomControl3D de la versión 2, e incluyen un control intersticial adicional. El control de rotación permite rotar en las direcciones admitidas.

Puedes hacer un seguimiento de las ciudades donde hay imágenes a 45° disponibles actualmente 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.