É o 15º aniversário da Plataforma Google Maps: confira as notícias e avisos mais recentes

Objetos "map"

Os mapas são representados na API pelas classes GoogleMap e MapFragment.

Amostras de código

O repositório ApiDemos no GitHub inclui exemplos que demonstram o uso do objeto GoogleMap e o SupportMapFragment:

Adicionar um mapa a um app para Android

Veja como adicionar um mapa:

  1. Você só precisa concluir esta etapa uma vez. Siga as instruções no guia de configuração do projeto para acessar a API, receber uma chave e incluir os atributos necessários no manifesto do Android.
  2. Adicione um objeto Fragment à Activity que lidará com o mapa. A maneira mais fácil de fazer isso é incluir um elemento <fragment> no arquivo de layout da Activity.
  3. Implemente a interface OnMapReadyCallback e use o método de callback onMapReady(GoogleMap) para aplicar um identificador ao objeto GoogleMap. O objeto GoogleMap é a representação interna do próprio mapa. Para definir as opções de visualização de um mapa, você precisa modificar o objeto GoogleMap dele.
  4. Chame getMapAsync() no fragmento para registrar o callback.

Veja a seguir mais detalhes sobre cada etapa.

Adicionar um fragmento

Inclua um elemento <fragment> no arquivo de layout da atividade para configurar um objeto Fragment. Nesse elemento, defina o atributo android:name como "com.google.android.gms.maps.MapFragment". Isso anexa automaticamente um MapFragment à atividade.

O arquivo de layout a seguir contém um elemento <fragment>:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.gms.maps.MapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Você também pode adicionar um MapFragment a uma Activity no código. Para fazer isso, crie uma nova instância MapFragment e, depois, chame FragmentTransaction.add() para incluir o Fragment na Activity atual.

 mMapFragment = MapFragment.newInstance();
 FragmentTransaction fragmentTransaction =
         getFragmentManager().beginTransaction();
 fragmentTransaction.add(R.id.my_container, mMapFragment);
 fragmentTransaction.commit();

Adicionar código do mapa

Para trabalhar com o mapa no seu app, implemente a interface OnMapReadyCallback e defina uma instância do callback em um objeto MapFragment ou MapView. Neste tutorial, usamos um MapFragment, porque essa é a maneira mais comum de adicionar um mapa a um app. A primeira etapa é implementar a interface de callback:

public class MainActivity extends FragmentActivity
    implements OnMapReadyCallback {
...
}

No método onCreate() da Activity, defina o arquivo de layout como a visualização de conteúdo. Por exemplo, se o arquivo tiver o nome main.xml, use este código:

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

Receba um identificador para o fragmento ao chamar FragmentManager.findFragmentById() e transmitir o ID do recurso do seu elemento <fragment>. O ID R.id.map é adicionado automaticamente ao projeto Android quando você cria o arquivo de layout.

Em seguida, use getMapAsync() para definir o callback no fragmento.

MapFragment mapFragment = (MapFragment) getFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

Use o método de callback onMapReady(GoogleMap) se quiser receber um identificador para o objeto GoogleMap. O callback será acionado quando o mapa estiver pronto para ser utilizado. Ele fornece uma instância não nula de GoogleMap. Você pode usar o objeto GoogleMap para definir as opções de visualização do mapa ou adicionar um marcador, por exemplo.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

Objeto "map"

Com o Maps SDK for Android, você pode exibir um mapa do Google no seu aplicativo para Android. Esses mapas têm a mesma aparência que aqueles no app Google Maps para dispositivos móveis (GMM, na sigla em inglês), e a API expõe muitos dos mesmos elementos. Confira duas diferenças consideráveis entre o aplicativo GMM e os mapas exibidos pelo Maps SDK for Android:

  • Os blocos de mapa exibidos pela API não apresentam conteúdo personalizado, como ícones inteligentes personalizados.
  • Nem todos os ícones no mapa são clicáveis. Por exemplo, não é possível clicar em ícones de estação de transporte público. No entanto, os marcadores adicionados ao mapa são clicáveis, e a API tem uma interface de callback de listener para diversas interações com marcador.

Além do mapeamento, a API também aceita várias interações semelhantes ao modelo de IU do Android. Por exemplo, você pode configurar as interações com um mapa definindo listeners que respondem a gestos do usuário.

A classe mais importante ao trabalhar com um objeto "map" é GoogleMap. GoogleMap modela o objeto "map" no seu aplicativo. Na IU, um mapa será representado por um objeto MapFragment ou MapView.

GoogleMap lida com as seguintes operações automaticamente:

  • Conexão com o serviço do Google Maps
  • Download de blocos de mapas
  • Exibição de blocos na tela do dispositivo
  • Exibição de vários controles, como panorâmica e zoom
  • Resposta aos gestos de movimento e de zoom, deslocando o mapa e aumentando ou diminuindo o zoom

Além dessas operações automáticas, você pode controlar o comportamento dos mapas com objetos e métodos da API. Por exemplo, GoogleMap tem métodos de callback que respondem a toques de tela e gestos de toque. Também é possível definir ícones de marcador no seu mapa e adicionar sobreposições a ele usando os objetos definidos para GoogleMap.

MapFragment

MapFragment, uma subclasse de Fragment do Android, permite que você insira um mapa em um fragmento do Android. Os objetos MapFragment atuam como contêineres e dão acesso ao GoogleMap.

Ao contrário de um objeto View, um Fragment representa um comportamento ou parte da interface do usuário em uma atividade. Você pode combinar vários fragmentos em uma única atividade para criar uma IU de vários painéis e reutilizar um fragmento em diversas atividades. Consulte a documentação de fragmentos do Android para saber mais.

MapView

MapView, uma subclasse de View do Android, permite que você insira um mapa em uma View do Android. Uma View representa uma região retangular da tela e é fundamental para os aplicativos e widgets desse sistema operacional. Assim como um MapFragment, a MapView atua como um contêiner que mostra funcionalidades importantes do mapa usando o objeto GoogleMap.

Ao utilizar a API no modo totalmente interativo, a classe MapView precisa encaminhar os seguintes métodos de ciclo da atividade aos métodos correspondentes da MapView: onCreate(), onStart(), onResume(), onPause(), onStop(), onDestroy(), onSaveInstanceState() e onLowMemory(). O repositório ApiDemos no GitHub inclui um exemplo sobre como fazer isso. Ao usar a API no Modo Lite, o encaminhamento dos eventos de ciclo de vida é opcional. Para ver detalhes, consulte a documentação relacionada.

Tipos de mapa

Há muitos tipos de mapa disponíveis no Maps SDK for Android, que controlam a representação geral do mapa. Por exemplo, um atlas geralmente contém mapas políticos que mostram fronteiras e mapas rodoviários que incluem todas as vias de uma cidade ou região.

O Maps SDK for Android oferece quatro tipos de mapa, além de uma opção para não exibir nenhuma representação visual.

Normal
Mapa rodoviário comum. Mostra vias, alguns elementos criados pelo homem e recursos naturais importantes, como rios. Etiquetas de estradas e de elementos também são visíveis.
Híbrido
Dados de fotografia de satélite com mapas rodoviários. Etiquetas de estradas e de elementos também são visíveis.
Satélite
Dados de fotografia de satélite. Marcadores de estradas e de elementos não são visíveis.
Relevo
Dados topográficos. O mapa inclui cores, curvas de nível e etiquetas, além de sombreamento de perspectiva. Algumas vias e etiquetas também são visíveis.
Nenhum
Nenhum bloco. O mapa será renderizado como uma grade vazia, sem carregar blocos.

Alterar o tipo de mapa

Para configurar o tipo de um mapa, chame o método setMapType() do objeto GoogleMap, transferindo uma das constantes de tipo definidas em GoogleMap. Por exemplo, para exibir um mapa de satélite:

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

A imagem abaixo mostra uma comparação entre mapas normais, híbridos e de terreno para o mesmo local:

Comparação de MapType

Mapas internos

O mapa mostra, em níveis altos de zoom, plantas baixas para espaços internos, como aeroportos, shoppings, grandes lojas de varejo e estações de transporte público. Essas plantas, chamadas de mapas internos, são exibidas para os tipos de mapa "Normal" e "Satélite" (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Elas são ativadas automaticamente quando o usuário aumenta o zoom e desaparecem quando ele é reduzido.

Aviso de suspensão de uso: em uma versão futura, os mapas internos só estarão disponíveis no tipo de mapa normal. A partir dela, esses mapas não serão compatíveis com satellite, terrain ou hybrid. Mesmo quando o modo interno não for aceito, isIndoorEnabled() continuará retornando o valor definido usando setIndoorEnabled(), como já acontece. Por padrão, setIndoorEnabled é true. As notas da versão informarão quando o suporte ao modo interno ficar indisponível nesses tipos de mapa.

Exemplo de mapa interno

Trabalhar com mapas internos na API

Veja a seguir um resumo da funcionalidade dos mapas internos na API:

A estilização do mapa básico não afeta os mapas internos.

Adicionar plantas baixas

Os mapas internos (plantas baixas) estão disponíveis em locais específicos. Se não houver dados de planta baixa para um edifício que você quer destacar no seu aplicativo, será possível fazer o seguinte:

Camada de trânsito

Você pode permitir que os usuários visualizem o mapa com informações de densidade de trânsito sobrepostas. Com isso, eles terão acesso a um resumo visual da situação do trânsito local. É possível ativar ou desativar essa camada chamando o método setTrafficEnabled(). Para saber se ela está ativada, invoque isTrafficEnabled(). O exemplo a seguir mostra como a camada de tráfego pode aparecer em um mapa.

Um mapa do Google mostrando a camada de trânsito

Configurar o estado inicial

Com a API Maps, você pode configurar o estado inicial do mapa para atender às necessidades do seu aplicativo. É possível especificar o seguinte:

  • A posição da câmera, incluindo: localização, zoom, direção e inclinação. Consulte Câmera e visualização para mais detalhes sobre o posicionamento da câmera.
  • O tipo de mapa.
  • Se os botões do zoom e/ou da bússola aparecem na tela.
  • Os gestos que um usuário pode usar para manipular a câmera.
  • Se o Modo Lite está ativado ou não. Um mapa no Modo Lite é uma imagem em bitmap de um mapa que oferece suporte a um subconjunto das funções oferecidas pela API completa.

Você pode configurar o estado inicial por XML, se tiver adicionado o mapa ao arquivo de layout da sua atividade, ou de modo programático, se tiver incluído o mapa dessa maneira.

Como usar atributos XML

Nesta seção, descrevemos como definir o estado inicial se você tiver adicionado um mapa ao seu aplicativo usando um arquivo de layout XML.

A API Maps define um conjunto de atributos XML personalizados para um MapFragment ou uma MapView que você pode usar para configurar o estado inicial diretamente do arquivo de layout. Os seguintes atributos estão definidos no momento:

  • mapType. Permite especificar o tipo de mapa que será exibido. Os valores válidos incluem: none, normal, hybrid, satellite e terrain.
  • cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt. Permitem especificar a posição inicial da câmera. Veja mais detalhes sobre a posição da câmera e as propriedades dela.
  • uiZoomControls, uiCompass. Permitem definir se os controles de zoom e a bússola aparecerão no mapa. Consulte UiSettings para mais detalhes.
  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures. Permitem especificar quais gestos podem ser usados para interagir com o mapa. Consulte UiSettings para mais detalhes.
  • zOrderOnTop. Controla se a superfície da visualização de mapa será posicionada sobre a janela. Consulte SurfaceView.setZOrderOnTop(boolean) para mais detalhes. Esse item abrange todos as outras visualizações que podem aparecer no mapa (por exemplo, os controles de zoom, o botão "Meu local").
  • useViewLifecycle. Só é válido com um MapFragment. Esse atributo especifica se o ciclo de vida do mapa deve ser vinculado à visualização do fragmento ou ao próprio fragmento. Consulte este link para mais detalhes.
  • liteMode. Um valor true altera o mapa para o Modo Lite. Um mapa no Modo Lite é uma imagem em bitmap que oferece suporte a um subconjunto das funções oferecidas pela API completa. O valor padrão desse atributo é false.

Para usar esses atributos personalizados no seu arquivo de layout XML, adicione primeiro a seguinte declaração de namespace. Você pode escolher qualquer namespace (não precisa ser map):

xmlns:map="http://schemas.android.com/apk/res-auto"

Em seguida, é possível incluir os atributos com um prefixo map: nos componentes do layout, como você faria com os atributos padrão do Android.

O snippet de código XML a seguir mostra como configurar um MapFragmentcom algumas opções personalizadas. Os mesmos atributos podem ser aplicados a uma MapView.

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:map="http://schemas.android.com/apk/res-auto"
  android:name="com.google.android.gms.maps.SupportMapFragment"
  android:id="@+id/map"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

De forma programática

Nesta seção, explicamos como definir o estado inicial se você tiver adicionado um mapa ao seu aplicativo de maneira programática.

Se você tiver incluído MapFragment (ou MapView) de forma programática, poderá configurar o estado inicial transmitindo um objeto GoogleMapOptions com as opções especificadas. As opções disponíveis são as mesmas do XML. Você pode criar um objeto GoogleMapOptions como este:

GoogleMapOptions options = new GoogleMapOptions();

E configurá-lo da seguinte forma:

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

Para aplicar essas opções durante a criação do mapa, realize uma das seguintes ações:

Padding do mapa

Este vídeo mostra um exemplo de padding do mapa.

Um mapa do Google deve preencher toda a região definida pelo elemento do contêiner (normalmente uma MapView ou um MapFragment). Vários aspectos da exibição e do comportamento de um mapa são definidos pelas dimensões do contêiner:

  • A alvo da câmera será o centro da região preenchida.
  • Os controles do mapa são posicionados em relação às margens dele.
  • Informações legais, como declarações de direitos autorais ou o logotipo do Google, aparecem na margem inferior.

Para adicionar padding ao redor das margens do mapa, use o método GoogleMap.setPadding(). O mapa continuará preenchendo todo o contêiner, mas o posicionamento do texto e dos controles, os gestos do mapa e os movimentos da câmera responderão como se estivessem em um espaço menor. Isso resulta nas seguintes alterações:

  • Os movimentos da câmera por meio de chamadas de API ou pressionamento de botões (por exemplo, botões da bússola, de zoom ou "Meu local") serão relativos à região preenchida.
  • getCameraPosition() retornará o centro da região preenchida.
  • Projection.getVisibleRegion() retornará a região preenchida.
  • O controles de IU serão deslocados da margem do contêiner pelo número especificado de pixels.

O padding pode ser útil ao criar IUs que se sobrepõem a uma parte do mapa. Por exemplo, na imagem inferior, o mapa é preenchido nas margens superior e direita. Controles de mapa e texto legal visíveis são exibidos nas margens da região preenchida, em verde, enquanto o mapa continua preenchendo o contêiner inteiro, mostrado em azul. Nesse exemplo, você poderia exibir um menu flutuante no lado direito, sem ocultar os controles.

Padding do mapa

Traduzir seu mapa

Quando você adiciona uma MapView ou um MapFragment ao seu app, os elementos textuais do mapa são exibidos no idioma apropriado com base nas configurações do dispositivo e no local do usuário. É possível restringir os idiomas utilizados pelo aplicativo a um subconjunto de todos os idiomas compatíveis. Basta adicionar um item resConfigs ao seu arquivo do Gradle. Isso é útil para remover idiomas não utilizados e reduzir o tamanho binário do seu app. Exemplo:

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

Saiba como traduzir seu app para Android.