Adicionar um mapa

Este tópico descreve como adicionar um mapa básico a um app Android depois de configurar o projeto com o objetivo de usar o SDK do Maps para Android. Depois de adicionar um mapa, você pode alterar o tipo e os recursos dele.

Visão geral

O SDK do Maps para Android disponibiliza várias classes que seu app pode usar para gerenciar o ciclo de vida, a funcionalidade e os dados de um mapa. As classes são compatíveis com interações do usuário que têm como base o modelo da IU do Android, como a definição do estado inicial do mapa e a resposta à entrada de gestos do usuário no tempo de execução.

A interface principal e as classes para trabalhar com mapas são as seguintes:

  • GoogleMap: o ponto de entrada para gerenciar os recursos e dados subjacentes do mapa. Seu app só acessará um objeto GoogleMap depois que ele for recuperado de um SupportMapFragment ou MapView.

  • SupportMapFragment: um fragmento para gerenciar o ciclo de vida de um objeto GoogleMap.

  • MapView: uma visualização para gerenciar o ciclo de vida de um objeto GoogleMap.

  • OnMapReadyCallback: uma interface de callback que processa eventos e interação do usuário para o objeto GoogleMap.

Um objeto GoogleMap executa automaticamente estas operações:

  • 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

Para usar um objeto GoogleMap no seu app, utilize um SupportMapFragment ou MapView como um contêiner para o mapa e, depois, recupere o GoogleMap do contêiner. Como as classes de contêiner derivam de um fragmento ou de uma visualização do Android, elas fornecem ao mapa os recursos de gerenciamento do ciclo de vida e IU das classes de base do Android. A classe SupportMapFragment é o contêiner mais moderno e comum de um objeto GoogleMap.

Ver o código

O código a seguir é da atividade Java completa usada neste tópico ao adicionar um fragmento de forma estática. O projeto Android foi criado com base no modelo vazio e atualizado de acordo com o guia de configuração do projeto. Depois que você executar as etapas deste tópico, o código poderá ficar diferente do modelo do projeto.

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  import com.google.android.gms.maps.GoogleMap;
  import com.google.android.gms.maps.OnMapReadyCallback;
  import com.google.android.gms.maps.SupportMapFragment;
  import com.google.android.gms.maps.model.LatLng;
  import com.google.android.gms.maps.model.MarkerOptions;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

Adicionar um mapa

Esta seção fala sobre como adicionar um mapa básico usando um fragmento como contêiner. No entanto, se quiser, você poderá usar uma visualização. Para ver um exemplo, consulte RawMapViewDemoActivity no GitHub.

Etapas básicas

  1. Antes de começar: verifique se você concluiu as etapas do guia de configuração do projeto para usar o SDK do Maps para Android.

  2. Adicione um objeto SupportMapFragment à atividade que vai trabalhar com o mapa. Você pode adicionar o fragmento de forma estática ou dinâmica.

  3. Implemente a interface OnMapReadyCallback.

  4. Defina o arquivo de layout como a visualização de conteúdo.

  5. Se você adicionou o fragmento estaticamente, gere um identificador para ele.

  6. Registre o callback.

  7. Gere um identificador para o objeto GoogleMap.

Adicionar um objeto SupportMapFragment

Você pode adicionar um objeto SupportMapFragment ao seu app de forma estática ou dinâmica. A maneira mais simples é adicioná-lo estaticamente. Se você adicionar o fragmento dinamicamente, será possível executar outras ações nele, como remover e substituí-lo no ambiente de execução.

Adicionar um fragmento de forma estática

No arquivo de layout da atividade que processará o mapa:

  1. adicione um elemento fragment;
  2. adicione a declaração de nome xmlns:map="http://schemas.android.com/apk/res-auto". Isso permite o uso de atributos maps XML personalizados;
  3. defina o atributo android:name como com.google.android.gms.maps.SupportMapFragmentno elemento fragment;
  4. adicione o atributo android:id no elemento fragment e defina-o como o ID do recurso do R.id.map (@+id/map).

Por exemplo, aqui está um arquivo completo de layout que inclui um elemento fragment:

<?xml version="1.0" encoding="utf-8"?>
<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"/>

Adicionar um fragmento de forma dinâmica

Na atividade, faça o seguinte:

  1. Crie uma instância SupportMapFragment.
  2. Confirme uma transação que adicione o fragmento à atividade. Para mais informações, consulte Transações de fragmento.

Exemplo:

Java

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();
      

Kotlin

val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit()
      

Implementar a interface OnMapReadyCallback

Atualize a declaração da atividade da seguinte forma:

Java

class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}
      

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}
      

Definir a visualização de conteúdo

No método onCreate da sua atividade, chame o método setContentView e defina o arquivo de layout como a visualização de conteúdo.

Por exemplo, se o nome do arquivo de layout for main.xml:

Java

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

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}
      

Gerar um identificador para o fragmento e registrar o callback

  1. Gere um identificador para o fragmento chamando o método FragmentManager.findFragmentById e transmita a ele o ID do recurso do fragmento no seu arquivo de layout. Se você adicionou o fragmento dinamicamente, pule esta etapa porque o identificador já foi recuperado.

  2. Chame o método getMapAsync para definir o callback no fragmento.

Por exemplo, se você adicionou o fragmento estaticamente:

Java

SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);
      

Kotlin

val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)
      

Gerar um identificador para o objeto GoogleMap

Use o método de callback onMapReady se quiser um identificador para o objeto GoogleMap. O callback será acionado quando o mapa estiver pronto para receber a entrada do usuário. Ele fornece uma instância não nula da classe GoogleMap que pode ser usada para atualizar o mapa.

Neste exemplo, o callback onMapReady recupera um identificador para o objeto GoogleMap e, em seguida, um marcador é adicionado ao mapa:

Java

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

Kotlin

override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker")
    )
}
      


Captura de tela com o mapa e o marcador centralizados na Ilha Nula.

Quando você criar e executar o app, ele exibirá um mapa com um marcador na Ilha Nula (zero graus de latitude e longitude).

Veja o código da atividade completa:

Ver atividade completa


Próxima etapa

Depois de concluir essas etapas, você poderá definir as configurações do mapa.