Actualiza 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 "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 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 que estén interesadas en eventos específicos deben registrar objetos de escucha de eventos para esos eventos y ejecutar código cuando se reciban. Este mecanismo orientado a eventos es el mismo en la 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 motivos de rendimiento, es mejor quitar un objeto de escucha de eventos cuando ya no sea necesario. Quitar un objeto de escucha de eventos funciona de la misma manera en la versión 2 y la 3:

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 quieras 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 quitarlo.

Cómo escuchar eventos del DOM

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

Usar argumentos pasados en eventos

Los eventos de la IU suelen pasar un argumento de evento al que puede acceder el objeto de escucha de eventos. La mayoría de los argumentos de eventos en la versión 3 se simplificaron para que sean más coherentes con los objetos de la API. (Consulta la referencia de v3 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 v3, la devolución de llamada solo se realizará 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 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 de v3.

1. La API de la versión 3 admite tipos de mapas adicionales, incluidos los mapas de terreno y la capacidad de agregar tipos de mapas personalizados.
2. El control jerárquico 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 versión 2 no está disponible en la versión 3.

Cómo agregar controles al mapa

Con la API de Maps JavaScript v2, agregarías controles a tu mapa a través del método addControl() de tu objeto de mapa. En la versión 3, en lugar de acceder a los controles o modificarlos directamente, debes modificar 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() 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 versión 3, configuras 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 cambio, la API los distribuye de manera inteligente alrededor de los elementos existentes del mapa, o de otros controles, con determinadas limitaciones (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 de v2, crearías una subclase de la clase GControl y definirías controladores para los métodos initialize() y getDefaultPosition(). No hay un equivalente a la clase GControl en la versión 3. En su lugar, los controles se representan como elementos DOM. Para agregar un control personalizado con la API de la versión 3, 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 cumpla con los requisitos de interfaz mencionados anteriormente (consulta la documentación de Controles personalizados para obtener más información), en los siguientes ejemplos 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);

Agregar y quitar superposiciones

Los tipos de objetos representados por una superposición son los mismos entre la versión 2 y la 3. Sin embargo, se manejan de manera diferente.

Las superposiciones de la API de v2 se agregaron y quitaron del mapa con los métodos addOverlay() y removeOverlay() del objeto GMap2. En la versión 3, asignas 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 configuras 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, luego puedes llamar a setMap() en cada superposición del array (pasa 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 la versión 2, puedes crear una instancia de GIcon a partir de G_DEFAULT_ICON type y modificarla. Si la 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 API de Maps JavaScript también admite íconos complejos. Un ícono complejo puede incluir varias tarjetas, formas complejas o especificar el "orden de pila" de cómo deben mostrarse 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 una 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, en la que 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 consta de un array 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 v3 es similar a usar un objeto GPolyline en 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 a través de 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

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

En los siguientes ejemplos, se dibuja el mismo polilínea codificado. El código de la versión 3 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 de la v3 es muy similar a la clase GPolygon de la v2, con la notable excepción de que ya no tienes que repetir el vértice inicial al final de la ruta para cerrar el bucle. La API de la versión 3 cerrará automáticamente cualquier polígono dibujando un trazo que conecte la última coordenada con la primera. Los siguientes fragmentos de código crean 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 dibujo en la documentación de la versión 3.

Ventanas de información

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

• La API de v2 solo admite GInfoWindow por mapa, mientras que la API de v3 admite varios InfoWindow simultáneos en cada mapa.
• El InfoWindow de v3 permanecerá abierto cuando hagas clic en el mapa. El GInfoWindow de la versión 2 se cierra automáticamente cuando haces clic en el mapa. Para emular el comportamiento de la v2, agrega 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. El constructor de un GroundOverlay es, en esencia, 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 coloca 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 del mapa de ruta.
• MapTypeId.SATELLITE (reemplaza a G_SATELLITE_MAP) muestra 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 API de 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 versión 3 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 de 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 versión 3, los controles son similares al control GLargeZoomControl3D de la versión 2, con un control de rotación intersticial adicional para rotar a través de las direcciones admitidas.

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 de 45° están disponibles, se agrega una opción de submenú al botón Satélite de la API de Maps.