Como 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:

• Eventos de usuário (como eventos de mouse e cliques) 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 as mudanças nos objetos da API Maps e são nomeadas usando uma convenção property_changed.

Cada objeto da Maps API exporta vários eventos nomeados. Aplicativos interessados em eventos específicos precisam registrar listeners para esses eventos e executar o código quando esses eventos são recebidos. Esse mecanismo orientado por eventos é o mesmo na API 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 ouvintes 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 na 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 para o método removeListener() (GEvent.removeListener() na v2 ou google.maps.event.removeListener() na v3) para remover o listener de eventos.

Escutar eventos do DOM

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

Usar argumentos passados em eventos

Os eventos de IU 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 em relação aos objetos na API. Consulte a Referência da v3 para mais detalhes.

Não existe nenhum argumento overlay nos listeners de eventos da v3. Se você registrar um evento click em um mapa da v3, o callback só ocorrerá quando o usuário clicar no mapa básico. Você pode registrar callbacks adicionais em sobreposições clicáveis se 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 alterações nos tipos de control foram introduzidas com a API v3.

1. A API v3 é compatível com outros tipos de mapa, incluindo mapas de terreno e a capacidade de adicionar tipos de mapa personalizados.
2. O controle hierárquico da v2, GHierarchicalMapTypeControl, não está mais disponível. Você pode conseguir um efeito semelhante usando o controle google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. O layout horizontal fornecido pela GMapTypeControl na v2 não está disponível na v3.

Adicionar controles ao mapa

Com a API Maps JavaScript v2, você adicionaria 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() recebe 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 com a propriedade position das opções de controle. O posicionamento desses controles não é absoluto. Em vez disso, a API vai definir o layout dos controles de maneira inteligente "quotizando-os" em torno de elementos de mapa existentes dentro de certas restrições (como o tamanho do mapa). Isso garante que os controles padrão sejam compatíveis com seus controles. Consulte Posicionamento de controle na v3 para ver 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

A API Maps JavaScript permite criar controles de navegação personalizados. Para personalizar os controles com a API v2, é necessário criar uma subclasse da classe GControl e definir gerenciadores para os métodos initialize() e getDefaultPosition(). Não há equivalente para a 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 construtor como filho de um Node (por exemplo, um elemento <div>) e adicione listeners de eventos para lidar com qualquer evento DOM. Envie Node para a matriz controls[position] do Maps e adicione uma instância do controle personalizado ao mapa.

Devido a uma implementação da classe HomeControl que segue os requisitos de interface mencionados acima, veja a documentação dos Controles personalizados para mais detalhes. Veja nas amostras de código a seguir 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);

Como adicionar e remover sobreposições

Os tipos de objetos representados por uma sobreposição são os mesmos entre a v2 e a v3. No entanto, eles são tratados 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, atribua um mapa a uma sobreposição usando a propriedade map da classe de opções de sobreposição associada. Você também pode adicionar ou remover uma sobreposição diretamente chamando o método setMap() do objeto de sobreposição e especificando o mapa desejado. Definir a propriedade do mapa como null remove a sobreposição.

Não existe nenhum método clearOverlays() na v3. Caso queira gerenciar um conjunto de sobreposições, crie uma matriz para armazenar as sobreposições. Usando essa matriz, é possível chamar setMap() em cada sobreposição na matriz (transmitindo null se precisar removê-los).

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 de G_DEFAULT_ICON type e modifique-a. Se a imagem for maior ou menor que o ícone padrão, especifique com uma instância GSize. A API v3 simplifica um pouco esse processo. Basta definir a propriedade icon do marcador como o URL da imagem personalizada, e a API dimensionará o ícone automaticamente.

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

Os exemplos a seguir exibem uma bandeira de praia na Bondi Beach, 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, além de uma série de segmentos de linha que conectam esses locais em uma sequência ordenada. Criar e exibir um objeto Polyline na v3 é semelhante a usar um objeto GPolyline na v2. Os exemplos a seguir desenham uma polilinha geodésica de 3 pixels de largura, semitransparente de Zurique até Sydney, até 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á compatibilidade com a v3 para criar objetos Polyline diretamente de polilinhas codificadas. Em vez disso, a Biblioteca de geometria (em inglês) oferece métodos para codificar e decodificar polilinhas. Consulte Bibliotecas na API Maps v3 para ver mais informações sobre como carregar essa biblioteca.

Os exemplos abaixo desenham a mesma polilinha 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 da v3 é muito semelhante à da classe v2 GPolygon, com a exceção notável de que não é mais necessário repetir o vértice inicial no final do caminho para fechar o loop. A API v3 fecha automaticamente todos os polígonos desenhando um traço que conecta a última coordenada à primeira coordenada. Os snippets de código a seguir 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 a seguir são equivalentes:

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

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

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

Janelas de informações

Uma InfoWindow exibe 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 aceita apenas GInfoWindow por mapa, enquanto a API v3 aceita várias InfoWindows simultâneas em cada mapa.
• A InfoWindow da v3 permanecerá aberta quando você clicar no mapa. A GInfoWindow v2 é fechada automaticamente quando você clica no mapa. Para emular o comportamento da v2, adicione um listener click no objeto Map.
• A API v3 não oferece suporte nativo para um 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 o URL de uma imagem e os limites da imagem como parâmetros.

O exemplo a seguir coloca um mapa antigo de Newark, NJ no mapa, 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) exibe a visualização de mapa de vias.
• MapTypeId.SATELLITE (substitui G_SATELLITE_MAP) exibe imagens de satélite do Google Earth.
• MapTypeId.HYBRID (substitui G_HYBRID_MAP) exibe uma combinação de visualizações normais e de satélite.
• MapTypeId.TERRAIN (substitui G_PHYSICAL_MAP) exibe 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 alterações nos tipos de mapa menos comuns:

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

Imagens com zoom máximo

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 adicional "Girar" para alternar pelas rotas compatíveis.

Você pode monitorar as cidades em que imagens de 45° estão disponíveis neste mapa. Quando imagens de 45° estiverem disponíveis, uma opção de submenu será adicionada ao botão "Satélite" da API Maps.