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 in eine Android-App einfügen. Die Anleitung auf dieser Seite setzt voraus, dass Sie die Schritte auf der Seite Einrichtung bereits ausgeführt haben und Folgendes haben:

  • 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 für Android konfiguriert ist
  • Ein Android Studio-Projekt, das für die Verwendung mit dem Maps 3D SDK für 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. Mit den folgenden Schritten fügen Sie die Komponente hinzu und konfigurieren den Anfangszustand der Karte, einschließlich der Kameraposition und zugehöriger Attribute:

  1. Öffnen Sie die Layoutdatei Ihrer Hauptaktivität, die sich normalerweise unter app/src/main/res/layout/activity_main.xml befindet.

  2. Fügen Sie im Stamm-ConstraintLayout (oder im Stammlayoutelement) den XML-Namespace map3d hinzu:

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

  3. Löschen Sie den Standard-<TextView>, der „Hello World!“ anzeigt.

  4. 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:mapMode="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 Lifecycle-Events der Komponente verwaltet.

Das Maps 3D SDK for Android unterstützt nur eine aktive Map3DView-Instanz gleichzeitig. 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 haben alle Map3DView-Elemente denselben Kartenstatus (z. B. Kameraposition, hinzugefügte Markierungen, Polygone usw.). Dieser bleibt auch dann erhalten, wenn ein Map3DView-Element gelöscht (mit onDestroy) und ein anderes erstellt wird, sofern er nicht manuell gelöscht wird. Wenn Sie beispielsweise Markierungen zu Map3DView1 hinzufügen, diese dann löschen und Map3DView2 erstellen, sind dieselben Markierungen weiterhin auf Map3DView2 vorhanden.

Verantwortlichkeiten des Entwicklers:

  • Eine Ansicht nach der anderen:Achten Sie darauf, dass sich jeweils 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ören das Entfernen von Markierungen, Overlays usw. und das Zurücksetzen der Kameraposition mit dem GoogleMap3D-Objekt, das in OnMap3DViewReadyCallback abgerufen wurde.

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

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

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

  3. Ändern Sie die Klasse MainActivity, um OnMap3DViewReadyCallback zu implementieren:

    class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

  4. Deklarieren Sie Variablen für Map3DView und GoogleMap3D:

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

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

  6. Überschreiben Sie die Methoden onMap3DViewReady und onError. Diese Callbacks werden ausgelöst, wenn die Karte einsatzbereit ist oder wenn während der Initialisierung ein Fehler auftritt:

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

override fun onError(error: Exception) {
    // Handle the error gracefully here (for example, show an error dialog or log the error).
    Log.e("MainActivity", "Error loading 3D map", error)
}

  7. Leiten Sie Lifecycle-Events von Ihrer Aktivität an die Map3DView weiter, indem Sie die folgenden Überschreibungen in die MainActivity einfü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.

  1. Wählen Sie Datei > Projekt mit Gradle-Dateien synchronisieren aus, um Ihr Projekt mit Gradle zu synchronisieren.

  2. Wenn Sie Ihre App auf einem Emulator oder einem physischen Gerät erstellen und ausführen möchten, wählen Sie Ausführen > Ausführen aus.

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

Lade- und Fehlerstatus der Karte

Das Maps 3D SDK für Android zeigt automatisch integriertes visuelles Feedback an, während der Status der Karte verwaltet wird:

  • Lade-Overlay:Eine zentrierte Fortschrittsanzeige wird eingeblendet, wenn die Kartenansicht zum ersten Mal initialisiert wird oder der erste Darstellungsbereich geladen wird.
  • Fehler-Overlay:Bei einem kritischen Fehler, z. B. einem ungültigen API-Schlüssel, einem Netzwerkfehler oder bei der Ausführung auf einem nicht unterstützten Gerät, wird eine formatierte Fehlerkarte angezeigt.

Sie können diese Initialisierungs- oder Ladefehler programmatisch erfassen, indem Sie onError(error: Exception) in Ihrer OnMap3DViewReadyCallback-Implementierung überschreiben.

Auf Klickereignisse für die Karte warten

Wenn Sie Click-Events auf der Karte erfassen möchten, rufen Sie setMap3DClickListener für GoogleMap3D auf. Wenn ein Nutzer auf die Karte klickt, empfängt der Callback onMap3DClick ein Map3DClickEvent-Objekt, das die location und die placeId des angeklickten Punkts enthält. Außerdem wird ein Boolean zurückgegeben (true, um das standardmäßige Places-UI-Widget zu unterdrücken, oder false, um es anzuzeigen). Weitere Informationen finden Sie unter Mit POIs interagieren.

Im folgenden Beispiel wird gezeigt, wie Sie einen Klick-Listener für die Karte festlegen:

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

Nächste Schritte

Nachdem Sie Ihrer App eine einfache 3D-Karte hinzugefügt haben, können Sie sich mit den erweiterten Funktionen des Maps 3D SDK for Android vertraut machen, z. B. Kamerapfad-Animationen, 3D-Markierungen oder Polygonen.