3D‑Karte in Ihre App einbinden

Plattform auswählen: Android iOS JavaScript

Eine 3D-Karte von New York City

Auf dieser Seite wird anhand eines Beispiels gezeigt, wie Sie mit dem Maps 3D SDK for Android eine einfache 3D-Karte zu einer Android-App hinzufügen. Die Anleitung auf dieser Seite setzt voraus, dass Sie die Schritte auf der Einrichtung Seite bereits ausgeführt haben und Folgendes vorhanden ist:

Ein Google Cloud-Projekt mit aktiviertem Maps 3D SDK for Android
Ein API-Schlüssel, der für die Verwendung mit dem Maps 3D SDK for Android konfiguriert ist
Ein Android Studio-Projekt, das für die Verwendung mit dem Maps 3D SDK for Android eingerichtet ist

Weitere Informationen zu diesen Voraussetzungen finden Sie unter Einrichtung.

Teil 1: Layoutdatei (`activity_main.xml`) aktualisieren, um die Komponente `Map3DView` hinzuzufügen

Die Komponente Map3DView ist die Ansicht, in der die 3D-Karte in der App gerendert wird. In den folgenden Schritten wird die Komponente hinzugefügt und der Anfangszustand der Karte konfiguriert, einschließlich der Kameraposition und der zugehörigen Attribute:

Öffnen Sie die Layoutdatei Ihrer Hauptaktivität, die sich normalerweise unter app/src/main/res/layout/activity_main.xml befindet.
Fügen Sie im Stammverzeichnis ConstraintLayout (oder Ihrem Stammlayout-Element) den XML-Namespace map3d hinzu:
```
xmlns:map3d="http://schemas.android.com/apk/res-auto"
```
Löschen Sie das Standard-<TextView>, in dem „Hello World!“ angezeigt wird.

Fügen Sie Ihrem Layout die Komponente Map3DView hinzu. Sie können die Kameraposition und andere Attribute anpassen:

<?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>

Teil 2: MainActivity.kt aktualisieren

In den folgenden Schritten wird die Komponente Map3DView initialisiert, die in Teil 1 der Datei activity_main.xml hinzugefügt wurde, und es werden Lebenszyklusereignisse der Komponente verwaltet.

Das Maps 3D SDK for Android unterstützt jeweils nur eine aktive Map3DView Instanz. Die gleichzeitige Anzeige mehrerer Map3DView-Instanzen (z. B. im selben Layout oder in verschiedenen sichtbaren Aktivitäten oder Fragmenten) wird nicht unterstützt und kann zu Renderingproblemen führen, z. B. zu schwarzen Bildschirmen in sekundären Ansichten.

Außerdem verwenden alle Map3DView denselben Kartenstatus (z. B. Kameraposition, hinzugefügte Markierungen, Polygone usw.) und spiegeln ihn wider. Dieser Status bleibt auch dann erhalten, wenn eine Map3DView zerstört (mit onDestroy) und eine andere erstellt wird, es sei denn, er wird manuell gelöscht. Wenn Sie beispielsweise Map3DView1 Markierungen hinzufügen, sie dann zerstören und Map3DView2 erstellen, sind dieselben Markierungen weiterhin in Map3DView2 vorhanden.

Aufgaben des Entwicklers:

Jeweils eine Ansicht: Achten Sie darauf, dass sich zu jedem Zeitpunkt nur eine Map3DView in einem aktiven Teil Ihrer Ansichtshierarchie befindet.
Manuelle Bereinigung: Wenn Sie von einer Map3DView (z.B. Map3DView1) zu einer anderen (z.B. Map3DView2) wechseln, müssen Sie onDestroy() für die alte Instanz (Map3DView1) aufrufen. Da der zugrunde liegende Kartenstatus gemeinsam genutzt wird, müssen Sie alle von Map3DView1 festgelegten Status manuell löschen, damit Map3DView2 mit einem neuen oder bestimmten Status beginnt. Dazu gehört das Entfernen von Markierungen, Overlays usw. und das Zurücksetzen der Kameraposition mit dem GoogleMap3D-Objekt, das im OnMap3DViewReadyCallback abgerufen wurde.

Öffnen Sie die Datei MainActivity.kt, die sich normalerweise unter app/src/main/java/com/example/yourpackagename/MainActivity.kt befindet.

Fügen Sie die erforderlichen Importe für das Maps 3D SDK for Android hinzu:

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

Ändern Sie die Klasse MainActivity, um OnMap3DViewReadyCallback zu implementieren:
```
class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
```

Deklarieren Sie Variablen für Map3DView und GoogleMap3D:

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

Initialisieren Sie in der Methode onCreate nach setContentView(...) und dem Block ViewCompat.setOnApplyWindowInsetsListener die map3DView, rufen Sie die Lebenszyklusmethode onCreate auf und fordern Sie die Karte asynchron an:

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

Überschreiben Sie die Methode onMap3DViewReady. Dieser Callback wird ausgelöst, sobald die Karte einsatzbereit ist:

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 { ... })
}

Leiten Sie Lebenszyklusereignisse von Ihrer Aktivität an Map3DView weiter, indem Sie der MainActivity die folgenden Überschreibungen hinzufügen:

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

Teil 3: Gradle synchronisieren und ausführen

Nachdem Sie das Layout und die Aktivität Ihrer App aktualisiert haben, können Sie die App erstellen und ausführen, um die 3D-Kartenansicht zu sehen.

Wählen Sie Datei > Projekt mit Gradle-Dateien synchronisieren aus, um Ihr Projekt mit Gradle zu synchronisieren.
Wählen Sie Ausführen > Ausführen aus, um Ihre App auf einem Emulator oder einem physischen Gerät zu erstellen und auszuführen.

Wenn alles richtig konfiguriert ist, sollte in Ihrer App eine 3D-Karte angezeigt werden, die in der Nähe der in activity_main.xml angegebenen Koordinaten zentriert ist.

Nächste Schritte

Nachdem Sie Ihrer App eine einfache 3D-Karte hinzugefügt haben, können Sie weitere erweiterte Funktionen des Maps 3D SDK for Android kennenlernen, z. B. Kamerapfadanimationen, 3D-Markierungen, oder Polygone.

Auf Kartenklickereignisse warten

Verwenden Sie GoogleMap3D.setMap3DClickListener, um auf Klickereignisse auf der Karte zu warten. Dieser Listener wird ausgelöst, wenn ein Nutzer auf die Karte klickt, und liefert den Standort und die Orts-ID des angeklickten Punkts.

Im folgenden Beispiel wird gezeigt, wie Sie einen Kartenklick-Listener festlegen:

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

Beachten Sie, dass der Klick-Handler nicht im Hauptthread (oder UI-Thread) ausgeführt wird. Wenn Sie Änderungen an der Benutzeroberfläche vornehmen möchten (z. B. eine Toast-Nachricht anzeigen), müssen Sie zum Hauptthread wechseln. In Kotlin können Sie dazu lifecycleScope.launch(Dispatchers.Main) verwenden.