Aggiungere una mappa 3D all'app

Questo prodotto o questa funzionalità è sperimentale (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le offerte pre-GA sono coperte dai Termini specifici di servizio di Google Maps Platform. Per saperne di più, consulta le descrizioni della fase di lancio.

Seleziona la piattaforma: Android iOS JavaScript

Questa pagina illustra un esempio di come aggiungere una mappa 3D di base a un'app Android utilizzando l'SDK Maps 3D per Android. Le istruzioni riportate in questa pagina presuppongono che tu abbia già completato i passaggi nella pagina Configurazione e che tu disponga di quanto segue:

• Un progetto Google Cloud con l'SDK Maps 3D per Android abilitato
• Una chiave API configurata per l'utilizzo con l'SDK Maps 3D per Android
• Un progetto Android Studio configurato per l'utilizzo con l'SDK Maps 3D per Android

Per ulteriori informazioni su questi prerequisiti, vedi Configurazione.

Parte 1: aggiorna il file di layout (activity_main.xml) per aggiungere il componente Map3DView

Il componente Map3DView è la visualizzazione che esegue il rendering della mappa 3D all'interno dell'app. I seguenti passaggi aggiungono il componente e configurano lo stato iniziale della mappa, inclusi la posizione della videocamera e gli attributi correlati:

Nota :i passaggi descritti in questa sezione presuppongono che tu abbia creato e configurato il progetto Android Studio utilizzando la procedura descritta in Configurazione o che tu abbia aggiunto una nuova attività View a un progetto esistente. Se crei un nuovo progetto Android Studio senza aggiungere un'attività View, il progetto non conterrà un file activity_main.xml.

1. Apri il file di layout dell'attività principale, che di solito si trova in app/src/main/res/layout/activity_main.xml.

2. Nell'elemento principale ConstraintLayout (o nell'elemento di layout principale), aggiungi lo spazio dei nomi XML map3d:

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

3. Elimina il <TextView> predefinito che mostra "Hello World!".

4. Aggiungi il componente Map3DView al layout. Puoi personalizzare la posizione della videocamera e altri attributi:

   <?xml version="1.0" encoding="utf-8"?>
   <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/main"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     tools:context=".MainActivity">
   
     <com.google.android.gms.maps3d.Map3DView
       android:id="@+id/map3dView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       map3d:mode="hybrid"
       map3d:centerLat="38.544012"
       map3d:centerLng="-107.670428"
       map3d:centerAlt="2427.6"
       map3d:heading="310"
       map3d:tilt="63"
       map3d:range="8266"
       map3d:roll="0"
       map3d:minAltitude="0"
       map3d:maxAltitude="1000000"
       map3d:minHeading="0"
       map3d:maxHeading="360"
       map3d:minTilt="0"
       map3d:maxTilt="90"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />
   </androidx.constraintlayout.widget.ConstraintLayout>
   

Parte 2: aggiorna MainActivity.kt

I passaggi seguenti inizializzano il componente Map3DView aggiunto al file activity_main.xml nella Parte 1 e gestiscono gli eventi del ciclo di vita del componente:

1. Apri il file MainActivity.kt, che di solito si trova in app/src/main/java/com/example/yourpackagename/MainActivity.kt.

2. Aggiungi le importazioni necessarie per l'SDK Maps 3D per Android:

   import com.google.android.gms.maps3d.GoogleMap3D
   import com.google.android.gms.maps3d.Map3DView
   import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
   

3. Modifica la classe MainActivity per implementare OnMap3DViewReadyCallback:

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. Dichiara le variabili per Map3DView e GoogleMap3D:

   private lateinit var map3DView: Map3DView
   private var googleMap3D: GoogleMap3D? = null
   

5. Nel metodo onCreate, dopo setContentView(...) e il blocco ViewCompat.setOnApplyWindowInsetsListener, inizializza map3DView, chiama il metodo del ciclo di vita onCreate e richiedi la mappa in modo asincrono:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       enableEdgeToEdge()
       setContentView(R.layout.activity_main)
       ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
           val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
           v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
           insets
       }
   
       map3DView = findViewById(R.id.map3dView)
       map3DView.onCreate(savedInstanceState)
       map3DView.getMap3DViewAsync(this)
   }
   

6. Esegui l'override del metodo onMap3DViewReady. Questo callback viene attivato quando la mappa è pronta per essere utilizzata:

   override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
       // Interact with the googleMap3D object here
       this.googleMap3D = googleMap3D
       // You can now make calls to the googleMap3D object, e.g.,
       // googleMap3D.cameraController.flyTo(camera { ... })
   }
   

7. Inoltra gli eventi del ciclo di vita dall'attività a Map3DView aggiungendo i seguenti override a MainActivity:

   override fun onStart() {
       super.onStart()
       map3DView.onStart()
   }
   
   override fun onResume() {
       super.onResume()
       map3DView.onResume()
   }
   
   override fun onPause() {
       map3DView.onPause()
       super.onPause()
   }
   
   override fun onStop() {
       map3DView.onStop()
       super.onStop()
   }
   
   override fun onDestroy() {
       map3DView.onDestroy()
       super.onDestroy()
   }
   
   override fun onSaveInstanceState(outState: Bundle) {
       super.onSaveInstanceState(outState)
       map3DView.onSaveInstanceState(outState)
   }
   
   override fun onLowMemory() {
       super.onLowMemory()
       map3DView.onLowMemory()
   }
   

Parte 3: sincronizza Gradle ed esegui

Ora che hai aggiornato il layout e l'attività dell'app, puoi creare ed eseguire l'app per visualizzare la mappa 3D.

1. Per sincronizzare il progetto con Gradle, seleziona File > Sync Project with Gradle Files (Sincronizza progetto con i file Gradle).

2. Per creare ed eseguire l'app su un emulatore o un dispositivo fisico, seleziona Esegui > Esegui.

Se tutto è configurato correttamente, dovresti vedere una mappa 3D visualizzata nella tua app, centrata vicino alle coordinate specificate nel tuo activity_main.xml.

Passaggi successivi

Ora che hai aggiunto una mappa 3D di base alla tua app, puoi esplorare le funzionalità più avanzate dell'SDK Maps 3D per Android, come animazioni del percorso della videocamera, indicatori 3D o poligoni.