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 de 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à effectué les étapes de la Configuration page 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 dans 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:mode="hybrid"
    map3d:centerLat="38.544012"
    map3d:mode="hybrid"
    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 d'affichage, 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 OnMap3DViewReadyCallback.

Ouvrez votre fichier MainActivity.kt, qui se trouve généralement dans 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 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.cameraController.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 Map3DView en ajoutant les remplacements suivants à 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 activity_main.xml.

États de chargement et d'erreur de la carte

Le SDK Maps 3D pour Android affiche automatiquement un feedback 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 fiche 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, utilisez GoogleMap3D.setMap3DClickListener. Cet écouteur est déclenché lorsqu'un utilisateur clique sur la carte et fournit l'emplacement et l'ID de lieu du point cliqué.

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

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

Notez que le gestionnaire de clics ne s'exécute pas sur le thread principal (ou d'UI). Si vous souhaitez apporter des modifications à l'UI (par exemple, afficher un message Toast), vous devez passer au thread principal. Pour Kotlin, vous pouvez le faire à l'aide de lifecycleScope.launch(Dispatchers.Main).

É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.