Ajouter une carte

Cette rubrique explique comment ajouter une carte de base à une application Android après avoir configuré le projet pour utiliser le SDK Maps pour Android. Une fois que vous avez ajouté une carte, vous pouvez modifier son type et ses éléments géographiques.

Présentation

Le SDK Maps pour Android fournit plusieurs classes que votre application peut utiliser pour gérer le cycle de vie, les fonctionnalités et les données d'une carte. Les classes prennent en charge les interactions utilisateur basées sur le modèle de l'UI Android. Par exemple, elles permettent de définir l'état initial de la carte et les réactions aux entrées gestuelles de l'utilisateur lors de l'exécution.

Interface principale et classes principales pour la gestion des cartes :

  • GoogleMap : point d'entrée pour gérer les données et les éléments géographiques sous-jacents de la carte. Votre application ne peut accéder à un objet GoogleMap qu'une fois qu'il a été récupéré depuis un objet SupportMapFragment ou MapView.

  • SupportMapFragment : fragment pour gérer le cycle de vie d'un objet GoogleMap.

  • MapView : vue pour gérer le cycle de vie d'un objet GoogleMap.

  • OnMapReadyCallback : interface de rappel qui gère les événements et les interactions utilisateur pour l'objet GoogleMap.

Un objet GoogleMap exécute automatiquement les opérations suivantes :

  • Connexion au service Google Maps
  • Téléchargement des tuiles de carte
  • Affichage des tuiles sur l'écran de l'appareil
  • Affichage de diverses commandes comme le panoramique et le zoom
  • Réponse aux gestes de panoramique et de zoom (déplacement de la carte et zoom avant ou arrière)

Pour utiliser un objet GoogleMap dans votre application, vous devez utiliser un objet SupportMapFragment ou MapView en tant que conteneur pour la carte, puis récupérer l'objet GoogleMap du conteneur. Comme les classes du conteneur sont dérivées d'un fragment ou d'une vue Android, elles fournissent à la carte les fonctionnalités de gestion du cycle de vie et d'UI de leurs classes Android de base. La classe SupportMapFragment est le conteneur le plus moderne et le plus courant pour un objet GoogleMap.

Afficher le code

Le code suivant provient de l'activité Java complète utilisée dans cette rubrique, lorsque vous êtes amené à ajouter fragment en mode statique. Le projet Android a été créé à partir du modèle de projet vide, puis mis à jour comme indiqué dans le guide de configuration du projet. Si vous avez suivi les étapes décrites dans cette rubrique, votre code peut varier en fonction du modèle de projet.

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  import com.google.android.gms.maps.GoogleMap;
  import com.google.android.gms.maps.OnMapReadyCallback;
  import com.google.android.gms.maps.SupportMapFragment;
  import com.google.android.gms.maps.model.LatLng;
  import com.google.android.gms.maps.model.MarkerOptions;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

Ajouter une carte

Cette section explique comment ajouter une carte de base en utilisant un fragment en tant que conteneur de carte. Vous pouvez toutefois utiliser une vue à la place. Pour voir un exemple, consultez RawMapViewDemoActivity sur GitHub.

Principales étapes :

  1. Avant de commencer : Assurez-vous d'avoir terminé les étapes du guide Configuration du projet afin que votre projet soit configuré pour utiliser le SDK Maps pour Android.

  2. Ajoutez un objet SupportMapFragment à l'activité qui va gérer la carte. Vous pouvez ajouter le fragment en mode statique ou dynamique.

  3. Implémentez l'interface OnMapReadyCallback.

  4. Définissez le fichier de mise en page en tant que vue de contenu.

  5. Si vous avez ajouté le fragment en mode statique, obtenez un handle pour ce fragment.

  6. Enregistrez le rappel.

  7. Obtenez un handle vers l'objet GoogleMap.

Ajouter un objet SupportMapFragment

Vous pouvez ajouter un objet SupportMapFragment à votre application en mode statique ou dynamique. Le moyen le plus simple est de l'ajouter en mode statique. Si vous ajoutez le fragment en mode dynamique, vous pouvez effectuer des actions supplémentaires sur celui-ci, comme le supprimer et le remplacer au moment de l'exécution.

Ajouter un fragment en mode statique

Dans le fichier de mise en page de l'activité qui gérera la carte :

  1. Ajoutez un élément fragment.
  2. Ajoutez la déclaration de nom xmlns:map="http://schemas.android.com/apk/res-auto". Cela permet d'utiliser les attributs XML personnalisés de maps.
  3. Dans l'élément fragment, définissez l'attribut android:name sur com.google.android.gms.maps.SupportMapFragment.
  4. Dans l'élément fragment, ajoutez l'attribut android:id et définissez-le sur l'ID de ressource R.id.map (@+id/map).

Par exemple, voici un fichier de mise en page complet incluant un élément fragment :

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Ajouter un fragment en mode dynamique

Dans l'activité :

  1. Créez une instance SupportMapFragment.
  2. Effectuez un commit d'une transaction qui ajoute le fragment à l'activité. Pour en savoir plus, consultez Transactions de fragment.

Exemple :

Java

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();
      

Kotlin

val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit()
      

Implémenter l'interface OnMapReadyCallback

Mettez à jour la déclaration d'activité comme suit :

Java

class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}
      

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}
      

Définir la vue de contenu

Dans la méthode onCreate de votre activité, appelez la méthode setContentView et définissez le fichier de mise en page en tant que vue de contenu.

Par exemple, si le fichier de mise en page s'appelle main.xml :

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}
      

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}
      

Obtenir un handle vers le fragment et enregistrer le rappel

  1. Pour obtenir un handle vers le fragment, appelez la méthode FragmentManager.findFragmentById et transmettez-lui l'ID de ressource du fragment dans votre fichier de mise en page. Si vous avez ajouté le fragment en mode dynamique, ignorez cette étape, car vous avez déjà récupéré le handle.

  2. Appelez la méthode getMapAsync pour définir le rappel sur le fragment.

Par exemple, si vous avez ajouté le fragment en mode statique :

Java

SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);
      

Kotlin

val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)
      

Obtenir un handle vers l'objet GoogleMap

Utilisez la méthode de rappel onMapReady pour obtenir un handle vers l'objet GoogleMap. Le rappel est déclenché lorsque la carte est prête à recevoir des entrées utilisateur. Il fournit une instance non nulle de la classe GoogleMap que vous pouvez utiliser pour mettre à jour la carte.

Dans cet exemple, le rappel onMapReady récupère un handle vers l'objet GoogleMap, puis un repère est ajouté à la carte :

Java

@Override
public void onMapReady(GoogleMap googleMap) {
    googleMap.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}
      

Kotlin

override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker")
    )
}
      


Capture d&#39;écran avec la carte et le repère centrés sur Null Island.

Lorsque vous compilez et exécutez correctement l'application, celle-ci affiche une carte avec un repère sur Null Island (à zéro degré de latitude et de longitude).

Vous pouvez consulter le code de l'activité complète :

Afficher l'activité complète


Étapes suivantes

Une fois que vous aurez réalisé les étapes ci-dessous, vous pourrez configurer les paramètres de la carte.