Aggiungere una mappa

Seleziona la piattaforma: Android iOS JavaScript

Questo argomento descrive come aggiungere una mappa di base a un'app per Android dopo aver configurato il progetto in modo da utilizzare Maps SDK for Android. Dopo aver aggiunto una mappa, puoi modificare il tipo e le caratteristiche della mappa.

Nota: per creare rapidamente un'app che include già una mappa di base, puoi utilizzare il modello di Google Maps in Android Studio. Per maggiori dettagli, consulta la guida rapida.

Panoramica

Maps SDK for Android fornisce diverse classi che la tua app può utilizzare per gestire il ciclo di vita, le funzionalità e i dati di una mappa. Le classi supportano le interazioni degli utenti basate sul modello dell'interfaccia utente di Android, ad esempio l'impostazione dello stato iniziale della mappa e la risposta all'input tramite gesti dell'utente in fase di runtime.

L'interfaccia e le classi principali per la gestione delle mappe:

• GoogleMap : il punto di accesso per la gestione delle funzionalità e dei dati della mappa sottostante. La tua app può accedere a un oggetto GoogleMap solo dopo averlo recuperato da un oggetto SupportMapFragment o MapView.

• SupportMapFragment : un fragment per la gestione del ciclo di vita di un oggetto GoogleMap.

• MapView : una visualizzazione per la gestione del ciclo di vita di un oggetto GoogleMap.

• OnMapReadyCallback : un'interfaccia di callback che gestisce gli eventi e l'interazione dell'utente per l'oggetto GoogleMap.

Un oggetto GoogleMap esegue automaticamente queste operazioni:

• Connessione al servizio Google Maps.
• Download delle schede mappa.
• Visualizzazione dei riquadri sullo schermo del dispositivo.
• Visualizzazione di vari controlli, come lo spostamento e lo zoom.
• Risposta ai gesti di spostamento e zoom spostando la mappa e aumentando o riducendo lo zoom.

Per utilizzare un oggetto GoogleMap nella tua app, devi utilizzare un oggetto SupportMapFragment o MapView come oggetto contenitore per la mappa e poi recuperare l'oggetto GoogleMap dal contenitore. Poiché le classi contenitore derivano da un fragment o da una visualizzazione Android, forniscono alla mappa le funzionalità di gestione del ciclo di vita e dell'interfaccia utente delle classi di base di Android. La classe SupportMapFragment è il contenitore più moderno e comune per un oggetto GoogleMap.

Visualizzare il codice

Il seguente codice proviene dall'attività Java completa utilizzata in questo argomento quando si aggiunge un fragment in modo statico. Il progetto Android è stato creato dal modello di progetto vuoto e poi aggiornato in base alla guida alla configurazione del progetto. Dopo aver eseguito i passaggi descritti in questo argomento, il codice potrebbe variare a seconda del modello di progetto.

Mostra / Nascondi codice

  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"));
      }
  }

Per aggiungere una mappa

Questa sezione descrive come aggiungere una mappa di base utilizzando un fragment come contenitore della mappa, ma puoi utilizzare una visualizzazione. Per un esempio, consulta RawMapViewDemoActivity su GitHub.

I passaggi di base:

1. Per ottenere l'SDK, recuperare una chiave API e aggiungere i framework richiesti, segui i passaggi descritti in:

   1. Configurare nella console Google Cloud

   2. Utilizzare una chiave API

   3. Configurare un progetto Android Studio

2. Aggiungi un oggetto SupportMapFragment all'attività che gestirà la mappa. Puoi aggiungere il fragment in modo statico o dinamico.

3. Implementa l'interfaccia OnMapReadyCallback.

4. Imposta il file di layout come visualizzazione dei contenuti.

5. Se hai aggiunto il fragment in modo statico, recupera un handle per il fragment.

6. Registra il callback.

7. Recupera un handle per l'oggetto GoogleMap.

Aggiungere un oggetto SupportMapFragment

Puoi aggiungere un oggetto SupportMapFragment alla tua app in modo statico o dinamico. Il modo più semplice è aggiungerlo in modo statico. Se aggiungi il fragment in modo dinamico, puoi eseguire azioni aggiuntive sul fragment, ad esempio rimuoverlo e sostituirlo in fase di runtime.

Per aggiungere un fragment in modo statico

Nel file di layout dell'attività che gestirà la mappa:

1. Aggiungi un elemento fragment.
2. Aggiungi la dichiarazione del nome xmlns:map="http://schemas.android.com/apk/res-auto". In questo modo è possibile utilizzare maps attributi XML personalizzati.
3. Nell'elemento fragment, imposta l'attributo android:name su com.google.android.gms.maps.SupportMapFragment.
4. Nell'elemento fragment, aggiungi l'attributo android:id e impostalo sull' ID risorsa R.id.map (@+id/map).

Ad esempio, ecco un file di layout completo che include un 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"/>

Per aggiungere un fragment in modo dinamico

Nell'attività:

1. Crea un'istanza di SupportMapFragment.
2. Esegui il commit di una transazione che aggiunge il fragment all'attività. Per maggiori informazioni, consulta Transazioni di fragment.

Ad esempio:

Kotlin

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

      

Java

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

      

Implementare l'interfaccia OnMapReadyCallback

Aggiorna la dichiarazione dell'attività come segue:

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

Java

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

      

Impostare la visualizzazione dei contenuti

Nel onCreate metodo dell'attività, chiama il setContentView metodo e imposta il file di layout come visualizzazione dei contenuti.

Ad esempio, se il file di layout si chiama main.xml:

Kotlin

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

      

Java

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

      

Recuperare un handle per il fragment e registrare il callback

1. Per recuperare un handle per il fragment, chiama il FragmentManager.findFragmentById metodo e passagli l'ID risorsa del fragment nel file di layout. Se hai aggiunto il fragment in modo dinamico, salta questo passaggio perché hai già recuperato l'handle.

2. Chiama il metodo getMapAsync per impostare il callback sul fragment.

Ad esempio, se hai aggiunto il fragment in modo statico:

Kotlin

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

      

Java

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

      

Recuperare un handle per l'oggetto GoogleMap

Utilizza il metodo di callback onMapReady per recuperare un handle per l'oggetto GoogleMap. Il callback viene attivato quando la mappa è pronta a ricevere l'input dell'utente. Fornisce un'istanza non nulla della classe GoogleMap che puoi utilizzare per aggiornare la mappa.

In questo esempio, il onMapReady callback recupera un handle per l'GoogleMap oggetto e poi viene aggiunto un indicatore alla mappa:

Kotlin

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

      

Java

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

      

Quando crei ed esegui l'app, verrà visualizzata una mappa con un indicatore su Null Island (zero gradi di latitudine e zero gradi di longitudine).

Visualizza il codice per l'attività completa:

Visualizza l'attività completa

---

Passaggi successivi

Dopo aver completato questi passaggi, puoi configurare le impostazioni della mappa.