Questa pagina è stata tradotta dall'API Cloud Translation.

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 per l'utilizzo dell'SDK di Maps per Android. Dopo aver aggiunto una mappa, puoi modificare il tipo di mappa e gli elementi.

Panoramica

L'SDK di Maps per Android offre diverse classi che l'app può utilizzare per gestire il ciclo di vita, le funzionalità e i dati di una mappa. Le classi supportano le interazioni degli utenti in base al modello di interfaccia utente Android, ad esempio l'impostazione dello stato iniziale della mappa e la risposta all'input dei gesti da parte dell'utente in fase di esecuzione.

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

GoogleMap: il punto di accesso per la gestione dei dati e delle funzionalità di mappa sottostanti. La tua app può accedere a un oggetto GoogleMap solo dopo che è stato recuperato da un oggetto SupportMapFragment o MapView.
SupportMapFragment: un frammento per la gestione del ciclo di vita di un oggetto GoogleMap.
MapView: una vista per gestire il 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 in corso...
Download dei riquadri della mappa in corso...
Visualizzazione dei riquadri sullo schermo del dispositivo.
Visualizzazione di vari controlli, ad esempio panoramica e zoom.
Rispondere ai gesti di panoramica e zoom spostando la mappa e aumentando o diminuendo lo zoom.

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

Visualizza il codice

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

  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 frammento come contenitore di mappa, ma puoi utilizzare una vista. Per un esempio, consulta RawMapViewDemoActivity su GitHub.

Passaggi di base:

Per ottenere l'SDK, ottieni una chiave API e aggiungi i framework richiesti, segui questi passaggi:
Aggiungi un oggetto SupportMapFragment all'attività che gestirà la mappa. Puoi aggiungere il frammento in modo statico o dinamico.
Implementa l'interfaccia OnMapReadyCallback.
Imposta il file di layout come visualizzazione dei contenuti.
Se hai aggiunto il frammento in modo statico, ottieni un handle al frammento.
Registra il callback.
Crea un handle per l'oggetto GoogleMap.

Aggiungi un oggetto SupportMapFragment

Puoi aggiungere un oggetto SupportMapFragment alla tua app in modo statico o dinamico. Il modo più semplice è quello di aggiungerlo in modo statico. Se aggiungi il frammento in modo dinamico, puoi compiere azioni aggiuntive sul frammento, come rimuoverlo e sostituirlo in fase di esecuzione.

Per aggiungere un frammento in modo statico

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

Aggiungi un elemento fragment.
Aggiungi la dichiarazione del nome xmlns:map="http://schemas.android.com/apk/res-auto". Ciò consente l'utilizzo di maps attributi XML personalizzati.
Nell'elemento fragment, imposta l'attributo android:name su com.google.android.gms.maps.SupportMapFragment.
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"/>

Aggiungere un frammento in modo dinamico

Nell'attività:

Crea un'istanza SupportMapFragment.
Esegui il commit di una transazione che aggiunge il frammento all'attività. Per ulteriori informazioni, consulta la pagina Transazioni di frammenti.

Ad esempio:

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()

Implementa l'interfaccia `OnMapReadyCallback`

Aggiorna la dichiarazione relativa all'attività come segue:

Java


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

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

Impostare la visualizzazione dei contenuti

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

Ad esempio, se il file di layout è denominato 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)
}

Ottieni un handle sul frammento e registra il callback

Per ottenere un handle, chiama il metodo FragmentManager.findFragmentById e trasmettilo all'ID risorsa del frammento nel tuo file di layout. Se hai aggiunto il frammento in modo dinamico, salta questo passaggio perché hai già recuperato l'handle.
Chiama il metodo getMapAsync per impostare il callback sul frammento.

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

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)

Aggiungi un handle all'oggetto `GoogleMap`

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

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

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

Screenshot con la mappa e l'indicatore centrati su Null Island.

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

Visualizza il codice per visualizzare l'attività completa:

Visualizza l'attività completa

Passaggi successivi

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

Aggiungere una mappa

Panoramica

Visualizza il codice

Per aggiungere una mappa

Aggiungi un oggetto SupportMapFragment

Per aggiungere un frammento in modo statico

Aggiungere un frammento in modo dinamico

Java

Kotlin

Implementa l'interfaccia OnMapReadyCallback

Java

Kotlin

Impostare la visualizzazione dei contenuti

Java

Kotlin

Ottieni un handle sul frammento e registra il callback

Java

Kotlin

Aggiungi un handle all'oggetto GoogleMap

Java

Kotlin

Passaggi successivi

Implementa l'interfaccia `OnMapReadyCallback`

Aggiungi un handle all'oggetto `GoogleMap`