Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Ajouter une carte 3D à votre application

Sélectionnez une plate-forme : Android iOS JavaScript

Carte 3D montrant New York

Cette page explique comment ajouter une carte 3D de base à une application Android à l'aide du SDK Maps 3D pour Android. Les instructions de cette page supposent que vous avez déjà suivi les étapes de la page de configuration et que vous disposez des éléments suivants :

Un projet Google Cloud avec le SDK Maps 3D pour Android activé
Une clé API configurée pour être utilisée avec le SDK Maps 3D pour Android
Un projet Android Studio configuré pour être utilisé avec le SDK Maps 3D pour Android

Pour en savoir plus sur ces prérequis, consultez la section Configuration.

Partie 1 : Mettre à jour le fichier de mise en page (`activity_main.xml`) pour ajouter le composant `Map3DView`

Le composant Map3DView est la vue qui affiche la carte 3D dans l'application. Les étapes suivantes ajoutent le composant et configurent l'état initial de la carte, y compris la position de la caméra et les attributs associés :

Ouvrez le fichier de mise en page de votre activité principale, qui se trouve généralement à l'adresse app/src/main/res/layout/activity_main.xml.
Dans la racine ConstraintLayout (ou votre élément de mise en page racine), ajoutez l'espace de noms XML map3d :
```
xmlns:map3d="http://schemas.android.com/apk/res-auto"
```
Supprimez le <TextView> par défaut qui affiche "Hello World!".

Ajoutez le composant Map3DView à votre mise en page. Vous pouvez personnaliser la position de la caméra et d'autres attributs :

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

Partie 2 : Mettre à jour MainActivity.kt

Les étapes suivantes initialisent le composant Map3DView ajouté au fichier activity_main.xml dans la partie 1 et gèrent les événements de cycle de vie des composants.

Notez que le SDK Maps 3D pour Android n'accepte qu'une seule instance Map3DView active à la fois. L'affichage simultané de plusieurs instances Map3DView (par exemple, dans la même mise en page ou dans différentes activités ou fragments visibles) n'est pas pris en charge et peut entraîner des problèmes de rendu, tels que des écrans noirs sur les vues secondaires.

De plus, tous les Map3DView partageront et refléteront le même état de carte (par exemple, la position de la caméra, les repères ajoutés, les polygones, etc.), qui persistera même si un Map3DView est détruit (à l'aide de onDestroy) et qu'un autre est créé, sauf s'il est effacé manuellement. Par exemple, si vous ajoutez des repères à Map3DView1, puis que vous le détruisez et créez Map3DView2, ces mêmes repères seront toujours présents sur Map3DView2.

Responsabilités du développeur :

Une vue à la fois : assurez-vous qu'un seul Map3DView se trouve dans une partie active de votre hiérarchie de vues à tout moment.
Nettoyage manuel : lorsque vous passez d'un Map3DView (par exemple, Map3DView1) à un autre (par exemple, Map3DView2), vous devez appeler onDestroy() sur l'ancienne instance (Map3DView1). Étant donné que l'état de la carte sous-jacente est partagé, pour vous assurer que Map3DView2 commence avec un état nouveau ou spécifique, vous devez effacer manuellement tout état défini par Map3DView1. Cela inclut la suppression des repères, des superpositions, etc., et la réinitialisation de la position de la caméra à l'aide de l'objet GoogleMap3D obtenu dans le OnMap3DViewReadyCallback.

Ouvrez votre fichier MainActivity.kt, qui se trouve généralement à l'adresse app/src/main/java/com/example/yourpackagename/MainActivity.kt.

Ajoutez les importations nécessaires pour le SDK Maps 3D pour Android :

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

Modifiez la classe MainActivity pour implémenter OnMap3DViewReadyCallback :

class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

Déclarez des variables pour Map3DView et GoogleMap3D :

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

Dans la méthode onCreate, après setContentView(...) et le bloc ViewCompat.setOnApplyWindowInsetsListener, initialisez le map3DView, appelez sa méthode de cycle de vie onCreate et demandez la carte de manière asynchrone :

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

Remplacez les méthodes onMap3DViewReady et onError. Ces rappels sont déclenchés lorsque la carte est prête à être utilisée ou lorsqu'une erreur se produit lors de l'initialisation :

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

Transférez les événements de cycle de vie de votre activité vers le Map3DView en ajoutant les remplacements suivants au 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()
}

Partie 3 : Synchroniser Gradle et exécuter

Maintenant que vous avez mis à jour la mise en page et l'activité de votre application, vous pouvez la compiler et l'exécuter pour afficher la vue de carte 3D.

Pour synchroniser votre projet avec Gradle, sélectionnez File > Sync Project with Gradle Files (Fichier > Synchroniser le projet avec les fichiers Gradle).
Pour compiler et exécuter votre application sur un émulateur ou un appareil physique, sélectionnez Run > Run (Exécuter > Exécuter).

Si tout est correctement configuré, une carte 3D s'affiche dans votre application, centrée près des coordonnées spécifiées dans votre activity_main.xml.

États de chargement et d'erreur de la carte

Le SDK Maps 3D pour Android affiche automatiquement un retour visuel intégré tout en gérant l'état de la carte :

Superposition de chargement : un indicateur de progression centré s'affiche lorsque la vue de carte est initialisée pour la première fois ou qu'elle charge sa fenêtre d'affichage initiale.
Superposition d'erreur : une carte d'erreur stylisée s'affiche en cas d'échec critique, par exemple une clé API non valide, une erreur réseau ou une exécution sur un appareil non compatible.

Vous pouvez capturer ces erreurs d'initialisation ou de chargement par programmation en remplaçant onError(error: Exception) dans votre OnMap3DViewReadyCallback implémentation.

Écouter les événements de clic sur la carte

Pour écouter les événements de clic sur la carte, appelez setMap3DClickListener sur GoogleMap3D. Lorsqu'un utilisateur clique sur la carte, le onMap3DClick rappel reçoit un Map3DClickEvent objet qui fournit l' location et le placeId du point cliqué, et renvoie un Boolean (true pour supprimer le widget d'interface utilisateur Places par défaut ou false pour l'afficher). Pour en savoir plus, consultez Interagir avec les points d'intérêt.

L'exemple suivant montre comment définir un écouteur de clic sur la carte :

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

Étapes suivantes

Maintenant que vous avez ajouté une carte 3D de base à votre application, vous pouvez explorer des fonctionnalités plus avancées du SDK Maps 3D pour Android, telles que les animations de chemin de caméra, les repères 3D, ou les polygones.