Adicionar um mapa

Neste tópico, descrevemos 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 interface do Android, como a definição do estado inicial do mapa e a resposta a gestos do usuário no ambiente 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 movimento 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, traga 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 UI 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 dependendo 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 explica como adicionar um mapa básico usando um fragmento como contêiner. No entanto, se quiser, você poderá usar uma visualização. Para conferir um exemplo, consulte RawMapViewDemoActivity no GitHub.

Etapas básicas:

1. Para baixar o SDK, conseguir uma chave de API e adicionar os frameworks necessários, siga as etapas em:

   1. Configuração no console do Google Cloud

   2. Como usar chaves de API

   3. Configurar um projeto do Android Studio

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 handle para ele.

6. Registre o callback.

7. Gere um handle 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 a remoção e a substituição dele 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.SupportMapFragment no 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. Faça commit em uma transação que adicione o fragmento à atividade. Para mais informações, consulte Transações de fragmento.

Por exemplo:

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

      

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

      

Implementar a interface OnMapReadyCallback

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

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

class MainActivity extends AppCompatActivity implements 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:

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

      

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

      

Gerar um handle para o fragmento e registrar o callback

1. Para gerar um handle para o fragmento, chame 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 handle já foi recuperado.

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

Por exemplo, se você adicionou o fragmento estaticamente:

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

      

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

      

Gerar um handle para o objeto GoogleMap

Use o método de callback onMapReady se quiser um handle 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 handle para o objeto GoogleMap e, em seguida, um marcador é adicionado ao mapa:

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

      

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

      

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:

arrow_upwardVer atividade completa

Próxima etapa

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