Fazer upgrade do aplicativo da API Maps JavaScript da v2 para a v3

Novo evento para compatibilidade com MVC

A API v3 adiciona um novo tipo de evento para refletir as mudanças de estado de MVC. Agora há dois tipos de eventos:

• Os eventos do usuário (como eventos de clique do mouse) são propagados do DOM para a API Maps JavaScript. Esses eventos são separados e diferentes dos eventos DOM padrão.
• As notificações de mudança de estado do MVC refletem mudanças nos objetos da API Maps e são nomeadas usando a convenção property_changed.

Cada objeto da Maps API exporta vários eventos nomeados. Os aplicativos interessados em eventos específicos precisam registrar listeners de eventos para esses eventos e executar o código quando esses eventos forem recebidos. Esse mecanismo orientado a eventos é o mesmo nas APIs Maps JavaScript v2 e v3, exceto que o namespace mudou de GEvent para 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.');
});

Remover listeners de eventos

Por motivos de desempenho, é melhor remover um listener de eventos quando ele não for mais necessário. A remoção de um listener de eventos funciona da mesma forma na v2 e v3:

1. Quando você cria um listener de eventos, um objeto opaco (GEventListener na v2, MapsEventListener na v3) é retornado.
2. Quando você quiser remover o listener de eventos, transmita esse objeto ao método removeListener() (GEvent.removeListener() na v2 ou google.maps.event.removeListener() na v3) para remover o listener de eventos.

Ouvir eventos do DOM

Se você quiser capturar e responder a eventos do DOM (modelo de objeto de documento), a v3 oferece o método estático google.maps.event.addDomListener(), equivalente ao método GEvent.addDomListener() na v2.

Usar argumentos transmitidos em eventos

Os eventos da interface geralmente transmitem um argumento de evento que pode ser acessado pelo listener de eventos. A maioria dos argumentos de evento na v3 foi simplificada para ser mais consistente com os objetos na API. Consulte a referência da v3 para mais detalhes.

Não há argumento overlay em listeners de eventos da v3. Se você registrar um evento click em um mapa da v3, o callback só vai ocorrer quando o usuário clicar no mapa base. É possível registrar outros callbacks em sobreposições clicáveis se você precisar reagir a esses cliques.

// 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
  });
});

Alterações em tipos de controle

Algumas mudanças nos tipos control foram introduzidas com a API v3.

1. A API v3 oferece suporte a outros tipos de mapa, incluindo mapas de terreno e a capacidade de adicionar tipos de mapa personalizados.
2. O controle hierárquico v2, GHierarchicalMapTypeControl, não está mais disponível. É possível conseguir um efeito semelhante usando o controle google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. O layout horizontal fornecido por GMapTypeControl na v2 não está disponível na v3.

Adicionar controles ao mapa

Com a API Maps JavaScript v2, você adiciona controles ao seu mapa usando o método addControl() do objeto de mapa. Na v3, em vez de acessar ou modificar controles diretamente, você modifica o objeto MapOptions associado. O exemplo abaixo mostra como personalizar o mapa para adicionar os seguintes controles:

• botões que permitem o usuário alternar entre os tipos de mapas disponíveis
• uma 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 no mapa

O posicionamento de controles mudou bastante na v3. Na v2, o método addControl() aceita um segundo parâmetro opcional que permite especificar a posição do controle em relação aos cantos do mapa.

Na v3, você define a posição de um controle pela propriedade position das opções de controle. O posicionamento desses controles não é absoluto. Em vez disso, a API os exibe de forma inteligente, "fluindo" em torno de elementos do mapa existentes dentro de restrições específicas (como o tamanho do mapa). Esse layout garante que os controles padrão sejam compatíveis com os seus. Consulte Controle de posicionamento na v3 para mais informações.

O código a seguir reposiciona os controles dos exemplos acima:

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

Use a API Maps JavaScript para criar controles de navegação personalizados. Para personalizar controles com a API v2, você precisa criar uma subclasse da classe GControl e definir processadores para os métodos initialize() e getDefaultPosition(). Não há um equivalente à classe GControl na v3. Em vez disso, os controles são representados como elementos DOM. Para adicionar um controle personalizado com a API v3, crie uma estrutura DOM para o controle em um contrutor como filho de um Node (por exemplo, um elemento <div>) e adicione listeners de eventos para processar qualquer evento DOM. Envie Node para a matriz controls[position] dos mapas para adicionar uma instância do controle personalizado ao mapa.

Considerando uma implementação de classe HomeControl que adere aos requisitos de interface mencionados acima (consulte a documentação de controles personalizados para mais detalhes), os exemplos de código a seguir mostram como adicionar um controle personalizado a um 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);

Adicionar e remover sobreposições

Os tipos de objetos representados por uma sobreposição são os mesmos entre a v2 e a v3, mas são processados de maneira diferente.

As sobreposições na API v2 foram adicionadas e removidas do mapa usando os métodos addOverlay() e removeOverlay() do objeto GMap2. Na v3, você atribui um mapa a uma sobreposição usando a propriedade map da classe de opções de sobreposição associada. Também é possível adicionar ou remover uma sobreposição diretamente chamando o método setMap() do objeto de sobreposição e especificando o mapa que você quer. Defina a propriedade do mapa como null para remover a sobreposição.

Não há método clearOverlays() na v3. Se você quiser gerenciar um conjunto de sobreposições, crie uma matriz para armazená-las. Usando essa matriz, você pode chamar setMap() em cada sobreposição na matriz (transmitindo null se precisar removê-las).

Marcadores arrastáveis

Por padrão, os marcadores são clicáveis, mas não arrastáveis. Os dois exemplos a seguir adicionam um marcador arrastável:

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
});

Ícones

Você pode definir um ícone personalizado para exibi-lo em vez do marcador padrão. Para usar uma imagem personalizada na v2, crie uma instância GIcon a partir da G_DEFAULT_ICON type e modifique-a. Se a imagem for maior ou menor que o ícone padrão, ela precisa ser especificada com uma instância GSize. A API v3 simplifica um pouco esse processo. Basta definir a propriedade icon do marcador como o URL da sua imagem personalizada, e a API vai dimensionar o ícone automaticamente.

A API Maps JavaScript também oferece suporte a ícones complexos. Um ícone complexo pode incluir vários blocos, formas complexas ou especificar a "ordem de pilha" de como as imagens devem aparecer em relação a outras sobreposições. Para adicionar uma forma a um marcador na v2, é necessário especificar a propriedade adicional em cada instância GIcon e transmiti-la como uma opção para um construtor GMarker. Na v3, os ícones especificados dessa forma precisam definir as propriedades icon como um objeto do tipo Icon. A v3 não permite sombra de marcadores.

Os exemplos a seguir mostram uma bandeira de praia na Praia de Bondi, na Austrália, com a parte transparente do ícone não clicável:

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
});

Polilinhas

Uma polilinha consiste em uma matriz de LatLngs e uma série de segmentos de linha que conectam esses locais em uma sequência ordenada. Criar e mostrar um objeto Polyline na v3 é semelhante a usar um objeto GPolyline na v2. Os exemplos a seguir desenham uma polilinha geodésica semitransparente de 3 pixels de largura de Zurique a Sydney passando por Singapura:

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);

Polilinhas codificadas

Não há suporte na v3 para a criação de objetos Polyline diretamente de polígonos codificados. Em vez disso, a biblioteca de geometria fornece métodos para codificar e decodificar polilinhas. Consulte Bibliotecas na API Maps v3 para mais informações sobre como carregar essa biblioteca.

Os exemplos abaixo desenham a mesma poligonal codificada. O código da v3 usa o método decodePath() do namespace 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

Um polígono define uma região em um loop fechado. Assim como o objeto Polyline, os objetos Polygon consistem em uma série de pontos em uma sequência ordenada. A classe Polygon do v3 é muito semelhante à classe GPolygon do v2, com a exceção de que você não precisa mais repetir o vértice inicial no final do caminho para fechar o loop. A API v3 vai fechar automaticamente todos os polígonos, desenhando um traço que conecta a última coordenada à primeira. Os snippets de código abaixo criam um polígono que representa o Triângulo das 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 editáveis pelos usuários

As polilinhas e os polígonos podem ser editáveis pelos usuários. Os snippets de código abaixo são equivalentes:

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

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

Para recursos de desenho mais avançados, consulte a Biblioteca de desenhos na documentação da v3.

Janelas de informações

Um InfoWindow mostra conteúdo em uma janela flutuante acima do mapa. Há algumas diferenças importantes entre as janelas de informações na v2 e na v3:

• A API v2 oferece suporte apenas a GInfoWindow por mapa, enquanto a API v3 oferece suporte a várias InfoWindows simultâneas em cada mapa.
• O InfoWindow da v3 vai permanecer aberto quando você clicar no mapa. O GInfoWindow da v2 é fechado automaticamente quando você clica no mapa. É possível emular o comportamento da v2 adicionando um listener click no objeto Map.
• A API v3 não oferece suporte integrado para uma InfoWindow com guias.

Sobreposições de solo

Para colocar uma imagem em um mapa, use um objeto GroundOverlay. O construtor de um GroundOverlay é essencialmente o mesmo na v2 e na v3: ele especifica um URL de uma imagem e os limites da imagem como parâmetros.

O exemplo a seguir coloca um mapa antigo de Newark, NJ, como uma sobreposição:

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 comuns

Os quatro tipos de mapa básicos estão disponíveis na v2 e na v3:

• MapTypeId.ROADMAP (substitui G_NORMAL_MAP) mostra a visualização de mapa de vias.
• MapTypeId.SATELLITE (substitui G_SATELLITE_MAP) mostra imagens de satélite do Google Earth.
• O MapTypeId.HYBRID (substitui G_HYBRID_MAP) mostra uma combinação de visualizações normal e de satélite.
• MapTypeId.TERRAIN (substitui G_PHYSICAL_MAP) mostra um mapa físico com base nas informações do terreno.

Veja a seguir um exemplo de definição do mapa para visualização de terreno na v2 e na v3:

map.setMapType(G_PHYSICAL_MAP);
    

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

A API Maps JavaScript v3 também fez algumas mudanças nos tipos de mapa menos comuns:

• Os blocos de mapa para corpos celestes diferentes da Terra não estão disponíveis como tipos de mapa na API v3, mas podem ser acessados como tipos de mapa personalizados. Confira um exemplo em Tipos de mapa personalizados.
• Não há um tipo de mapa especial na v3 que substitua o tipo G_SATELLITE_3D_MAP da v2. Em vez disso, você pode integrar o plug-in do Google Earth nos mapas v3 usando esta biblioteca.

Maximum Zoom Imagery

As imagens de satélite nem sempre estão disponíveis em níveis altos de zoom. Se você quiser saber o nível de zoom mais alto disponível antes de definir o nível de zoom, use a classe google.maps.MaxZoomService. Essa classe substitui o método GMapType.getMaxZoomAtLatLng() da v2.

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.");
    }
});

Imagens de perspectivas aéreas

Ao ativar as imagens aéreas na v3, os controles são semelhantes ao controle GLargeZoomControl3D da v2, com um controle de rotação intersticial adicional para girar nas direções compatíveis.

É possível acompanhar as cidades em que as imagens em 45° estão disponíveis no mapa de cidades com suporte. Quando as imagens de 45° estão disponíveis, uma opção de submenu é adicionada ao botão "Satélite" da API Maps.