A API Maps JavaScript v2 não está mais disponível desde 26 de maio de 2021. Como resultado, os mapas da v2 do seu site deixarão de funcionar e retornarão erros de JavaScript. Para continuar usando mapas no seu site, migre para a API Maps JavaScript v3. Este guia ajudará você nesse processo.
Visão geral
Todo aplicativo terá um processo de migração um pouco diferente.
No entanto, há algumas etapas comuns a todos os projetos:
- Receba uma nova chave. A API Maps JavaScript agora usa o Console do Google Cloud para gerenciar chaves. Se você ainda estiver usando uma chave v2, consiga a nova chave de API antes de iniciar a migração.
- Atualize o bootstrap da API. A maioria dos aplicativos carrega a API Maps JavaScript v3 com o seguinte código:
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
- Atualize seu código. O número de mudanças necessárias
dependerá muito do seu aplicativo. Estas são algumas das mudanças comuns:
- Sempre faça referência ao namespace google.maps. Na v3, todo o código da API Maps JavaScript é armazenado no namespace
google.maps.*
em vez de no namespace global. A maioria dos objetos também foi renomeada como parte desse
processo. Por exemplo, em vez de GMap2
, você
carregará google.maps.Map
.
- Remova todas as referências a métodos obsoletos. Vários
métodos de utilitários de uso geral foram removidos, como
GDownloadURL
e GLog
.
Substitua essa funcionalidade por bibliotecas de utilitários de terceiros
ou remova essas referências do seu código.
- (Opcional) Adicionar bibliotecas ao código. Muitos
recursos foram externalizados em bibliotecas de utilitários para que cada
app precise carregar apenas as partes da API que serão usadas.
- (Opcional) Configurar seu projeto para usar funções externas da v3.
As instâncias externas da v3 podem ser usadas para ajudar a validar seu código com o
Compiler
de fechamento ou para acionar o preenchimento automático no seu ambiente de desenvolvimento integrado.
Saiba mais sobre
Compilação avançada e recursos externos.
- Teste e itere. Você ainda precisa fazer algumas coisas, mas a boa notícia é que já está no caminho certo para começar a usar seu novo aplicativo de mapas da v3.
Mudanças na V3 da API Maps JavaScript
Antes de planejar sua migração, reserve um tempo para entender as diferenças entre a API Maps JavaScript v2 e a API Maps JavaScript v3. A versão mais recente da API Maps JavaScript foi escrita do zero, com foco em técnicas modernas de programação JavaScript, aumento do uso de bibliotecas e uma API simplificada.
Muitos recursos novos foram adicionados à API, e vários recursos conhecidos foram alterados ou até mesmo removidos. Esta seção destaca
algumas das principais diferenças entre as duas versões.
Algumas das mudanças na API v3 incluem:
- Uma biblioteca principal otimizada. Muitas das funções suplementares foram movidas para bibliotecas, ajudando a reduzir os tempos de carregamento e análise da API Core, o que permite que o mapa seja carregado rapidamente em qualquer dispositivo.
- Melhor desempenho de vários recursos, como renderização de polígonos e colocação de marcadores.
- Uma nova abordagem de
limites de uso
do lado do cliente para acomodar melhor os endereços compartilhados usados por proxies
para dispositivos móveis e firewalls corporativos.
- Adição de compatibilidade com vários navegadores
modernos e navegadores para dispositivos móveis. A compatibilidade com o Internet Explorer 6 foi
removida.
- Remoção de muitas das classes auxiliares de uso geral (
GLog
ou
GDownloadUrl
). Atualmente, existem muitas
bibliotecas JavaScript excelentes que oferecem funcionalidades semelhantes,
como Interdição ou
jQuery.
- Uma implementação do Street View em HTML5 que pode ser carregada em qualquer dispositivo móvel.
- Panoramas personalizados do Street View com suas próprias fotos, permitindo que você compartilhe panoramas de montanhas de esqui, casas à venda ou outros lugares interessantes.
- Personalizações de mapas estilizados que permitem mudar a exibição de elementos no mapa básico para corresponder ao seu estilo visual exclusivo.
- Suporte a vários serviços novos, como
ElevationService
e Distance
Matrix.
- Um serviço de rotas aprimorado fornece rotas alternativas, otimização de rotas (soluções aproximadas para o problema do vendedor de viagens), rotas de bicicleta (com camada de bicicleta), rotas de transporte público e rotas arrastáveis.
- Um formato de geocodificação atualizado que fornece informações de tipo mais precisas que o valor
accuracy
da API Geocoding v2.
- Suporte a várias janelas de informações em um único mapa
Fazer upgrade do aplicativo
Sua nova chave
A API Maps JavaScript v3 usa um novo sistema de chaves da v2. Talvez você já esteja
usando uma chave da v3 com seu aplicativo. Nesse caso, nenhuma mudança é necessária. Para verificar, verifique o URL de onde você carrega a API Maps JavaScript para o parâmetro key
. Se o valor da chave começar com 'ABQIAA' você está
usando uma chave v2. Se você tiver uma chave v2, faça upgrade para uma chave v3 como parte da migração,
que:
- Permite
monitorar o uso da API
no Console do Google Cloud.
- Permite que você compre
mais cota quando necessário.
- Oferece ao Google uma forma de entrar em contato com você sobre seu aplicativo.
A chave é transmitida ao carregar a API Maps JavaScript v3.
Saiba mais sobre como gerar chaves de API.
Se você é um cliente das APIs Google Maps for Work, pode estar usando um ID do cliente com o parâmetro client
em vez de usar o parâmetro key
. Os IDs do cliente ainda são compatíveis com a API Maps JavaScript v3 e não precisam passar pelo processo de upgrade de chave.
Carregando a API
A primeira modificação que você precisa fazer no código envolve a forma como a API é carregada. Na v2, você carrega a API Maps JavaScript por meio de uma solicitação para http://maps.google.com/maps
. Se você estiver carregando a API Maps JavaScript v3, será necessário fazer as seguintes alterações:
- Carregar a API de
//maps.googleapis.com/maps/api/js
- Remova o parâmetro
file
.
- Atualize o parâmetro
key
com a nova chave v3. Os clientes das APIs Google Maps for Work precisam usar um parâmetro client
.
- (Somente no Plano Premium da Plataforma Google Maps) Verifique se o parâmetro
client
é fornecido conforme explicado no Guia do desenvolvedor do Plano Premium da Plataforma Google Maps.
- Remova o parâmetro
v
para solicitar a versão mais recente ou altere o valor de acordo com o esquema de controle de versões v3.
- (Opcional) Substitua o parâmetro
hl
por language
e preserve o valor dele.
- (Opcional) Adicione um parâmetro
libraries
para
carregar bibliotecas
opcionais.
No caso mais simples, o bootstrap da v3 especificará apenas o parâmetro da chave de API:
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
O exemplo abaixo solicita a versão mais recente da API Maps JavaScript v2 em alemão:
<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>
O exemplo abaixo é uma solicitação equivalente para a v3.
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>
Apresentação do namespace google.maps
A mudança mais perceptível na API Maps JavaScript v3 é a introdução do namespace google.maps
. Por padrão, a API v2 coloca todos os objetos no namespace global, o que pode resultar em conflitos de nomenclatura. Na v3, todos os objetos estão localizados no namespace
google.maps
.
Ao migrar o aplicativo para a v3, será necessário alterar o código para
usar o novo namespace. Infelizmente, pesquisar ""G" e
substituir por "google.maps." não funcionará' totalmente funciona. No entanto, é uma boa regra
prática a ser aplicada ao analisar seu código. Veja abaixo alguns exemplos das classes equivalentes na v2 e na v3.
v2 |
v3 |
GMap2 |
google.maps.Map |
GLatLng |
google.maps.LatLng |
GInfoWindow |
google.maps.InfoWindow |
GMapOptions |
google.map.MapOptions |
G_API_VERSION |
google.maps.version |
GPolyStyleOptions |
google.maps.PolygonOptions or
google.maps.PolylineOptions |
Remover código obsoleto
A API Maps JavaScript v3 tem paralelos para a maioria das funcionalidades na v2. No entanto, algumas classes não são mais compatíveis. Como parte da migração, é necessário substituir essas
classes por bibliotecas de utilitários de terceiros ou remover essas
referências do seu código. Há várias bibliotecas JavaScript excelentes que
oferecem funcionalidades semelhantes, como Interdição ou
jQuery.
As seguintes classes não têm paralelo na API Maps JavaScript v3:
GBounds | GLanguage |
GBrowserIsCompatible | GLayer |
GControl | GLog |
GControlAnchor | GMercatorProjection |
GControlImpl | GNavLabelControl |
GControlPosition | GObliqueMercator |
GCopyright | GOverlay |
GCopyrightCollection | GPhotoSpec |
GDownloadUrl | GPolyEditingOptions |
GDraggableObject | GScreenOverlay |
GDraggableObjectOptions | GStreetviewFeatures |
GFactualGeocodeCache | GStreetviewLocation |
GGeoAddressAccuracy | GStreetviewOverlay |
GGeocodeCache | GStreetviewUserPhotosOptions |
GGoogleBar | GTileLayerOptions |
GGoogleBarAdsOptions | GTileLayerOverlayOptions |
GGoogleBarLinkTarget | GTrafficOverlayOptions |
GGoogleBarListingTypes | GUnload |
GGoogleBarOptions | GXml |
GGoogleBarResultList | GXmlHttp |
GInfoWindowTab | GXslt |
GKeyboardHandler |
|
Comparar código
Vamos comparar dois aplicativos, bem simples, que foram escritos com as APIs v2 e v3.
<!DOCTYPE html>
<html>
<head>
<script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
<style>
html, body, #map { height: 100%; margin: 0; }
</style>
<script>
function initialize() {
if (GBrowserIsCompatible()) {
var map = new GMap2(
document.getElementById('map'));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
map.setUIToDefault();
map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));
}
}
</script>
</head>
<body onload="initialize()" onunload="GUnload()">
<div id="map"></div>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
<style>
html, body, #map { height: 100%; margin: 0; }
</style>
<script>
function initialize() {
var map = new google.maps.Map(
document.getElementById('map'), {
center: new google.maps.LatLng(37.4419, -122.1419),
zoom: 13,
mapTypeId: google.maps.MapTypeId.ROADMAP
});
var marker = new google.maps.Marker({
position: new google.maps.LatLng(37.4419, -122.1419),
map: map
});
}
google.maps.event.addDomListener(window, 'load', initialize);
</script>
</head>
<body>
<div id="map"></div>
</body>
</html>
Como você pode ver, existem várias diferenças entre os dois
aplicativos. As principais mudanças incluem:
- O endereço de onde a API é carregada foi alterado.
- Os métodos
GBrowserIsCompatible()
e GUnload()
não são mais necessários na v3 e foram removidos da API.
- O objeto
GMap2
é substituído por google.maps.Map
como o objeto central na API.
- Agora, as propriedades são carregadas por meio das classes Options. No exemplo acima, definimos as três propriedades necessárias para carregar um mapa (
center
, zoom
e mapTypeId
) por meio de um objeto MapOptions
in-line.
- Na v3, a IU padrão é ativada por padrão. É possível desativar isso
definindo a propriedade
disableDefaultUI
como true no
objeto
MapOptions
.
Resumo
Neste ponto, você já conheceu alguns dos principais pontos envolvidos na sua migração da v2 para a v3 da API Maps JavaScript.
Talvez você precise de mais informações, mas isso depende do seu
aplicativo. Nas seções a seguir, incluímos instruções de migração para
casos específicos que você pode encontrar. Além disso, há vários recursos que podem ser úteis durante o processo de upgrade.
Caso tenha algum problema ou dúvida sobre este artigo, use o link ENVIAR FEEDBACK na parte superior desta página.
Esta seção apresenta uma comparação detalhada dos recursos mais usados da v2 e da v3 da API Maps JavaScript. Cada
seção da referência foi projetada para ser lida individualmente. Recomendamos que você não leia toda a referência. Em vez disso, use esse material para ajudar na migração caso a caso.
- Eventos - como registrar e tratar eventos.
- Controles: manipula os controles de navegação que aparecem no mapa.
- Sobreposições: adicionar e editar objetos no mapa.
- Tipos de mapa - os blocos que compõem o mapa de base.
- Camadas: adição e edição de conteúdo como um grupo, como camadas KML ou Tráfego.
- Serviços: trabalhando com geocodificação, rotas ou serviços do Street View do Google.
Eventos
O modelo de eventos da API Maps JavaScript v3 é semelhante ao usado na v2, embora muita coisa tenha mudado internamente.
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:
- Quando você cria um listener de eventos, um objeto opaco (GEventListener na v2, MapsEventListener na v3) é retornado.
- 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
});
});
Controles
A API Maps JavaScript mostra controles de IU que permitem aos usuários interagir com o mapa. Você pode usar a API para personalizar a aparência desses controles.
Alterações em tipos de controle
Algumas alterações nos tipos de control
foram introduzidas
com a API v3.
- A API v3 é compatível com outros tipos de mapa, incluindo mapas de terreno e a capacidade de adicionar tipos de mapa personalizados.
- 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
.
- 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);
Sobreposições
As sobreposições refletem objetos que você adiciona ao mapa para designar pontos, linhas, áreas ou coleções de objetos.
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 LatLng
s, 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 InfoWindow
s 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
Os tipos de mapas disponíveis na v2 e v3 são um pouco diferentes, mas todos os tipos básicos de mapas estão disponíveis nas duas versões da API. Por padrão, a v2 usa blocos de mapa de via padrão "quot;painted" quot; No entanto, a v3 exige que um tipo específico de mapa seja fornecido ao criar um objeto google.maps.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.
da imagem
Camadas são objetos no mapa que consistem em uma ou mais sobreposições. Eles podem ser manipulados como uma única unidade e refletem geralmente coleções de objetos.
Camadas permitidas
A API v3 permite acesso a diversas camadas diferentes. Essas camadas se sobrepõem à classe v2 GLayer
nas seguintes áreas:
-
O objeto
KmlLayer
renderiza elementos KML e GeoRSS em sobreposições de v3, fornecendo o equivalente para a camada GeoXml
da v2.
- O objeto
TrafficLayer
renderiza uma camada que representa as condições de tráfego, semelhante à sobreposição GTrafficOverlay
da v2.
Essas camadas são diferentes da v2. As diferenças estão descritas abaixo. Elas podem ser adicionadas a um mapa chamando setMap()
, transmitindo o objeto Map
em que a camada será exibida.
Veja mais informações sobre as camadas compatíveis na documentação de camadas.
Camadas KML e GeoRSS
A API Maps JavaScript é compatível com os formatos de dados KML e GeoRSS para exibição de informações geográficas. Os arquivos KML ou GeoRSS precisam ser
acessíveis publicamente se você quiser incluí-los em um mapa. Na v3, esses formatos de dados são exibidos usando uma instância de KmlLayer
, que substitui o objeto GGeoXml
da v2.
A API v3 é mais flexível ao renderizar KML, permitindo suprimir janelas de informações e modificar a resposta do clique. Consulte a documentação Camadas KML e GeoRSS para obter mais detalhes.
Ao renderizar um KmlLayer
,
as restrições de tamanho e complexidade se aplicam. Consulte a
documentação da KmlLayer
para ver mais detalhes.
Os exemplos a seguir comparam o carregamento de um arquivo KML.
geoXml = new GGeoXml(
'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml');
map.addOverlay(geoXml);
var layer = new google.maps.KmlLayer(
'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml', {
preserveViewport: true
});
layer.setMap(map);
Camada de trânsito
A v3 permite adicionar informações de trânsito em tempo real (quando compatível) aos seus mapas usando o objeto TrafficLayer
. As informações de tráfego são fornecidas durante o período da solicitação. Estes exemplos mostram as
informações de trânsito de Los Angeles:
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(34.0492459, -118.241043), 13);
map.setUIToDefault();
var trafficOptions = {incidents:false};
trafficInfo = new GTrafficOverlay(trafficOptions);
map.addOverlay(trafficInfo);
var map = new google.maps.Map(
document.getElementById('map'), {
center: new google.maps.LatLng(34.0492459, -118.241043),
mapTypeId: google.maps.MapTypeId.ROADMAP,
zoom: 13
});
var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);
Ao contrário da v2, não há opções para o construtor TrafficLayer
na v3. Incidentes não estão disponíveis na v3.
Serviços
Geocoding
A API Maps JavaScript oferece um objeto geocoder
para geocodificar endereços de maneira dinâmica a partir da entrada do usuário. Se você quiser geocodificar endereços estáticos e conhecidos, consulte a documentação da API Geocoding.
A API Geocoding foi atualizada e aprimorada significativamente, adicionando novos recursos e alterando a forma como os dados são representados.
GClientGeocoder
na API v2 forneceu dois métodos diferentes para geocodificação direta e inversa, bem como outros métodos para influenciar como a geocodificação foi realizada. Por outro lado, o objeto Geocoder
da v3
fornece apenas um método geocode()
, que usa um literal de objeto que contém os termos de entrada
(na forma de um objeto Solicitações
de geocodificação) e um método de callback. Dependendo se a solicitação contém um atributo textual address
ou um objeto LatLng
, a API Geocoding retornará uma resposta de geocodificação inversa ou inversa. É possível influenciar como a geocodificação é realizada ao transmitir outros campos para a solicitação de geocodificação:
- A inclusão de um
address
textual aciona a geocodificação direta,
equivalente a chamar o método getLatLng()
.
- A inclusão de um objeto
latLng
aciona a geocodificação inversa, equivalente a chamar o método getLocations()
.
- A inclusão do atributo
bounds
ativa a viés de janela de
visualização, equivalente a chamar o método setViewport()
.
- A inclusão do atributo
region
ativa a viés de código da região, o que equivale a chamar o método setBaseCountryCode()
.
As respostas de geocodificação na v3 são muito diferentes das respostas da v2. A API v3 substitui a estrutura aninhada que a v2 usa por uma estrutura mais plana, que é mais fácil de analisar. Além disso, as respostas da v3 são mais detalhadas: cada resultado tem vários componentes de endereço que ajudam a dar uma ideia melhor da resolução de cada resultado.
O código a seguir usa um endereço textual e mostra o primeiro resultado da geocodificação:
var geocoder = new GClientGeocoder();
var infoPanel;
var map;
var AccuracyDescription = [
'Unknown accuracy', 'country level accuracy',
'region level accuracy', 'sub-region level accuracy',
'town level accuracy', 'post code level accuracy',
'street level accuracy', 'intersection level accuracy',
'address level accuracy', 'premise level accuracy',
];
function geocode_result_handler(response) {
if (!response || response.Status.code != 200) {
alert('Geocoding failed. ' + response.Status.code);
} else {
var bounds = new GLatLngBounds(new GLatLng(
response.Placemark[0].ExtendedData.LatLonBox.south,
response.Placemark[0].ExtendedData.LatLonBox.west
), new GLatLng(
response.Placemark[0].ExtendedData.LatLonBox.north,
response.Placemark[0].ExtendedData.LatLonBox.east
));
map.setCenter(bounds.getCenter(),
map.getBoundsZoomLevel(bounds));
var latlng = new GLatLng(
response.Placemark[0].Point.coordinates[1],
response.Placemark[0].Point.coordinates[0]);
infoPanel.innerHTML += '<p>1st result is <em>' +
// No info about location type
response.Placemark[0].address +
'</em> of <em>' +
AccuracyDescription[response.Placemark[0].
AddressDetails.Accuracy] +
'</em> at <tt>' + latlng + '</tt></p>';
var marker_title = response.Placemark[0].address +
' at ' + latlng;
map.clearOverlays();
var marker = marker = new GMarker(
latlng,
{'title': marker_title}
);
map.addOverlay(marker);
}
}
function geocode_address() {
var address = document.getElementById('input-text').value;
infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
geocoder.getLocations(address, geocode_result_handler);
}
function initialize() {
map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(38, 15), 2);
map.setUIToDefault();
infoPanel = document.getElementById('info-panel');
}
var geocoder = new google.maps.Geocoder();
var infoPanel;
var map;
var marker;
function geocode_result_handler(result, status) {
if (status != google.maps.GeocoderStatus.OK) {
alert('Geocoding failed. ' + status);
} else {
map.fitBounds(result[0].geometry.viewport);
infoPanel.innerHTML += '<p>1st result for geocoding is <em>' +
result[0].geometry.location_type.toLowerCase() +
'</em> to <em>' +
result[0].formatted_address + '</em> of types <em>' +
result[0].types.join('</em>, <em>').replace(/_/, ' ') +
'</em> at <tt>' + result[0].geometry.location +
'</tt></p>';
var marker_title = result[0].formatted_address +
' at ' + latlng;
if (marker) {
marker.setPosition(result[0].geometry.location);
marker.setTitle(marker_title);
} else {
marker = new google.maps.Marker({
position: result[0].geometry.location,
title: marker_title,
map: map
});
}
}
}
function geocode_address() {
var address = document.getElementById('input-text').value;
infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
geocoder.geocode({'address': address}, geocode_result_handler);
}
function initialize() {
map = new google.maps.Map(document.getElementById('map'), {
center: new google.maps.LatLng(38, 15),
zoom: 2,
mapTypeId: google.maps.MapTypeId.HYBRID
});
infoPanel = document.getElementById('info-panel');
}
Rotas
A API Maps JavaScript v3 substitui a classe GDirections
da v2 pela classe DirectionsService
para calcular rotas.
O método route()
na v3 substitui os métodos load()
e loadFromWaypoints()
da API v2. Esse método usa um único literal de objeto DirectionsRequest
que contém os termos de entrada e um método de callback a ser executado no
recebimento da resposta. As opções podem ser fornecidas nesse literal de objeto, semelhante ao literal de objeto GDirectionsOptions
na v2.
Na API Maps JavaScript v3, a tarefa de enviar solicitações de rotas foi separada da tarefa de renderizar solicitações, que agora é processada com a classe DirectionsRenderer
. Você pode vincular um objeto DirectionsRenderer
a qualquer mapa ou objeto DirectionsResult
pelos métodos setMap()
e setDirections()
. Como o renderizador é um
MVCObject
, ele detectará todas as mudanças nas propriedades e
atualizará o mapa quando as rotas associadas mudarem.
O código a seguir demonstra como solicitar rotas a pé até um local específico usando caminhos de pedestres de um endereço. Somente a v3 pode fornecer rotas a pé no caminho de pedestres no Zoológico de Dublin.
var map;
var directions;
var directionsPanel;
function initialize() {
var origin = new google.maps.LatLng(53.348172, -6.297285);
var destination = new google.maps.LatLng(53.355502, -6.30557);
directionsPanel = document.getElementById("route");
map = new GMap2(document.getElementById('map'));
map.setCenter(origin, 10);
map.setUIToDefault();
directions = new GDirections(map, directionsPanel);
directions.loadFromWaypoints(
[origin, destination], {
travelMode: 'G_TRAVEL_MODE_WALKING',
});
}
var map;
var directionsRenderer;
var directionsService = new google.maps.DirectionsService();
function initialize() {
var origin = new google.maps.LatLng(53.348172, -6.297285);
var destination = new google.maps.LatLng(53.355502, -6.30557);
directionsRenderer = new google.maps.DirectionsRenderer();
map = new google.maps.Map(
document.getElementById('map'), {
center: origin,
zoom: 10,
mapTypeId: google.maps.MapTypeId.ROADMAP
});
directionsRenderer.setPanel(document.getElementById("route"));
directionsRenderer.setMap(map);
directionsService.route({
origin: origin,
destination: destination,
travelMode: google.maps.DirectionsTravelMode.WALKING
}, function(result, status) {
if (status == google.maps.DirectionsStatus.OK) {
directionsRenderer.setDirections(result);
}
});
}
Street View
O Google Street View oferece vistas interativas de 360° de locais designados na área de cobertura. A API v3 é compatível com o Street View nativamente no navegador, ao contrário da v2, que exigia o plug-in Flash® para exibir imagens do Street View.
As imagens do Street View são compatíveis com o uso do objeto StreetViewPanorama
na v3 ou do objeto GStreetviewPanorama
na v2. Essas classes têm interfaces diferentes, mas têm o mesmo papel: conectar o contêiner div
às imagens do Street View e permitir que você especifique o local e o POV (ponto de vista) do panorama do Street View.
function initialize() {
var fenwayPark = new GLatLng(42.345573, -71.098326);
panoramaOptions = {
latlng: fenwayPark,
pov: {
heading: 35,
pitch: 5,
zoom: 1
}
};
var panorama = new GStreetviewPanorama(
document.getElementById('pano'),
panoramaOptions);
GEvent.addListener(myPano, "error", handleNoFlash);
}
function handleNoFlash(errorCode) {
if (errorCode == FLASH_UNAVAILABLE) {
alert('Error: Your browser does not support Flash');
return;
}
}
function initialize() {
var fenway = new google.maps.LatLng(42.345573, -71.098326);
var panoramaOptions = {
position: fenway,
pov: {
heading: 35,
pitch: 5,
zoom: 1
}
};
var panorama = new google.maps.StreetViewPanorama(
document.getElementById('pano'),
panoramaOptions);
}
O acesso direto aos dados do Street View é possível por meio do objeto StreetViewService
na v3 ou do objeto GStreetviewClient
semelhante na v2. Ambos têm interfaces semelhantes para recuperar ou verificar a disponibilidade de dados do Street View e permitir a pesquisa por local ou ID do panorama.
Na v3, o Street View é ativado por padrão. O mapa será exibido com um controle do Pegman no Street View, e a API reutilizará o div do mapa para exibir panoramas do StreetView. O código a seguir ilustra como emular o comportamento da v2 separando os panoramas do Street View em um div separado.
var marker;
var panoClient = new GStreetviewClient();
function initialize() {
if (GBrowserIsCompatible()) {
var myPano = new GStreetviewPanorama(
document.getElementById('pano'));
GEvent.addListener(myPano, 'error', handleNoFlash);
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(42.345573, -71.098326), 16);
map.setUIToDefault();
GEvent.addListener(map, 'click', function(overlay, latlng) {
if (marker) {
marker.setLatLng(latlng);
} else {
marker = new GMarker(latlng);
map.addOverlay(marker);
}
var nearestPano = panoClient.getNearestPanorama(
latlng, processSVData);
});
function processSVData(panoData) {
if (panoData.code != 200) {
alert("Panorama data not found for this location.");
}
var latlng = marker.getLatLng();
var dLat = latlng.latRadians()
- panoData.location.latlng.latRadians();
var dLon = latlng.lngRadians()
- panoData.location.latlng.lngRadians();
var y = Math.sin(dLon) * Math.cos(latlng.latRadians());
var x = Math.cos(panoData.location.latlng.latRadians()) *
Math.sin(latlng.latRadians()) -
Math.sin(panoData.location.latlng.latRadians()) *
Math.cos(latlng.latRadians()) * Math.cos(dLon);
var bearing = Math.atan2(y, x) * 180 / Math.PI;
myPano.setLocationAndPOV(panoData.location.latlng, {
yaw: bearing
});
}
function handleNoFlash(errorCode) {
if (errorCode == FLASH_UNAVAILABLE) {
alert('Error: Your browser does not support Flash');
return;
}
}
}
}
// Load the API with libraries=geometry
var map;
var marker;
var panorama;
var sv = new google.maps.StreetViewService();
function radians(degrees) { return Math.PI * degrees / 180.0 };
function initialize() {
panorama = new google.maps.StreetViewPanorama(
document.getElementById("pano"));
map = new google.maps.Map(
document.getElementById('map'), {
center: new google.maps.LatLng(42.345573, -71.098326),
mapTypeId: google.maps.MapTypeId.ROADMAP,
zoom: 16
});
google.maps.event.addListener(map, 'click', function(event) {
if (!marker) {
marker = new google.maps.Marker({
position: event.latLng,
map: map
});
} else {
marker.setPosition(event.latLng);
}
sv.getPanoramaByLocation(event.latLng, 50, processSVData);
});
}
function processSVData(panoData, status) {
if (status == google.maps.StreetViewStatus.OK) {
alert("Panorama data not found for this location.");
}
var bearing = google.maps.geometry.spherical.computeHeading(
panoData.location.latLng, marker.getPosition());
panorama.setPano(panoData.location.pano);
panorama.setPov({
heading: bearing,
pitch: 0,
zoom: 1
});
panorama.setVisible(true);
marker.setMap(panorama);
}