Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps Android API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou choisir un projet
  2. Activer Google Maps Android API
  3. Créer les clés appropriées
Continuer

Marqueurs

Les marqueurs indiquent des points géographiques uniques sur la carte. Vous pouvez personnaliser vos marqueurs en changeant la couleur par défaut, ou en remplaçant l'icône du marqueur par une image personnalisée. Les fenêtres d'info peuvent fournir plus de contexte sur un marqueur.

Échantillons de code

Le référentiel ApiDemos sur GitHub inclut un échantillon qui illustre différentes fonctionnalités des marqueurs.

Introduction

Les marqueurs identifient des points géographiques sur la carte. Le marqueur par défaut utilise une icône standard, commune à toute l'interface Google Maps. Il est possible de changer la couleur de l'icône, l'image ou le point d'ancrage via l'API. Les marqueurs sont des objets de type Marker, et sont ajoutés à la carte avec la méthode GoogleMap.addMarker(markerOptions).

Les marqueurs sont conçus pour être interactifs. Ils reçoivent des événements de click par défaut et sont souvent utilisés avec des écouteurs d'événements qui permettent d'afficher des fenêtres d'info. Le fait de définir la propriété draggable d'un marqueur sur true, permet à l'utilisateur de changer la position du marqueur. Utilisez une pression prolongée pour activer la possibilité de déplacer le marqueur.

Par défaut, lorsqu'un utilisateur touche un marqueur, la barre d'outils de la carte apparaît en bas à droite de la carte, ce qui lui permet d'accéder rapidement à l'application mobile Google Maps. Vous pouvez désactiver la barre d'outils Pour plus d'informations, voir le guide des commandes.

Premiers pas avec les marqueurs

Cet épisode de Maps Live aborde les aspects fondamentaux de l'ajout de marqueurs à votre carte à l'aide de Google Maps Android API.

Ajouter un marqueur

L'exemple suivant montre comment ajouter un marqueur à une carte. Le marqueur est créé aux coordonnées 10,10 et affiche la chaîne « Hello world » dans une fenêtre d'info lors d'un clic.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Hello world"));
}

Afficher des informations supplémentaires sur un marqueur

Il est courant de vouloir afficher des informations supplémentaires sur un lieu lorsque l'utilisateur appuie sur un marqueur sur une carte. Voir le guide sur les fenêtres d'info.

Associer des données à un marqueur

Vous pouvez stocker un objet de données arbitraires avec un marqueur en utilisant Marker.setTag(), puis récupérer l'objet de données en utilisant Marker.getTag(), tel qu'illustré dans cet échantillon de code :

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends FragmentActivity implements
        OnMarkerClickListener,
        OnMapReadyCallback {

    private static final LatLng PERTH = new LatLng(-31.952854, 115.857342);
    private static final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
    private static final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

    private Marker mPerth;
    private Marker mSydney;
    private Marker mBrisbane;

    private GoogleMap mMap;

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

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

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        // Add some markers to the map, and add a data object to each marker.
        mPerth = mMap.addMarker(new MarkerOptions()
                .position(PERTH)
                .title("Perth");
        mPerth.setTag(0);

        mSydney = mMap.addMarker(new MarkerOptions()
                .position(SYDNEY)
                .title("Sydney");
        mSydney.setTag(0);

        mBrisbane = mMap.addMarker(new MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane");
        mBrisbane.setTag(0);

        // Set a listener for marker click.
        mMap.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @Override
    public boolean onMarkerClick(final Marker marker) {

        // Retrieve the data from the marker.
        Integer clickCount = (Integer) marker.getTag();

        // Check if a click count was set, then display the click count.
        if (clickCount != null) {
            clickCount = clickCount + 1;
            marker.setTag(clickCount);
            Toast.makeText(this,
                           marker.getTitle() +
                           " has been clicked " + clickCount + " times.",
                           Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

Voici des exemples de scénarios pour lesquels il peut s'avérer utile de stocker et de récupérer des données avec des marqueurs :

  • Votre application peut répondre aux besoins de différents types de marqueurs et vous souhaitez les traiter différemment lorsque l'utilisateur clique dessus. Pour ce faire, vous pouvez stocker un objet String avec le marqueur pour indiquer son type.
  • Vous pouvez être en interface avec un système qui présente des identifiants d'enregistrement uniques et dans lequel les marqueurs représentent des enregistrements spécifiques.
  • Les données de marqueur peuvent indiquer une priorité à utiliser lors du choix de la propriété z-index d'un marqueur.

Faire glisser un marqueur

Vous pouvez repositionner un marqueur une fois qu'il a été ajouté à la carte tant que sa propriété draggable est définie sur true. Appuyez de façon prolongée sur le marqueur pour activer le glissement. Lorsque vous relâchez votre doigt de l'écran, le marqueur reste dans cette position.

Par défaut, les marqueurs ne sont pas déplaçables. Vous devez explicitement définir le marqueur comme déplaçable soit avec MarkerOptions.draggable(boolean) avant de l'ajouter à la carte, soit avec Marker.setDraggable(boolean) une fois qu'il a été ajouté à la carte. Vous pouvez écouter des événements de glissement sur le marqueur, comme décrit dans la section Événements de glissement de marqueur.

Le fragment ci-dessous ajoute un marqueur déplaçable à Perth, en Australie.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .draggable(true));

Personnaliser un marqueur

Cette vidéo montre différentes façons d'utiliser des marqueurs pour visualiser des points géographiques sur une carte.

Les marqueurs peuvent définir une image personnalisée qui s'affiche à la place de l'icône par défaut. La définition d'une icône implique de paramétrer un certain nombre de propriétés qui affectent le comportement visuel du marqueur.

Les marqueurs peuvent être personnalisés par le biais des propriétés suivantes :

Position (obligatoire)
Valeur LatLng correspondant à la position du marqueur sur la carte. Il s'agit de la seule propriété obligatoire pour un objet Marker.
anchor
Le point sur l'image qui sera placé à la position LatLng du marqueur. La valeur par défaut correspond au milieu du bas de l'image.
alpha
Définit l'opacité du marqueur. La valeur par défaut est 1.0.
title
Chaîne qui s'affiche dans la fenêtre d'info lorsque l'utilisateur touche le marqueur.
snippet
Texte supplémentaire qui s'affiche en dessous du titre.
icon
Image bitmap qui s'affiche à la place de l'image du marqueur par défaut.
draggable
Définissez cette propriété sur true si vous souhaitez autoriser l'utilisateur à déplacer le marqueur. La valeur par défaut est false.
visible
Définissez cette propriété sur false pour rendre le marqueur invisible. La valeur par défaut est true.
Orientation flat ou billboard
Par défaut, les marqueurs sont orientés par rapport à l'écran et ne pivotent pas ou ne s'inclinent pas avec l'appareil photo. Les marqueurs plats sont orientés par rapport à la surface de la Terre, et pivotent et s'inclinent avec l'appareil photo. Les deux types de marqueur ne changent pas de taille en fonction du zoom. Utilisez GroundOverlays si vous souhaitez obtenir cet effet.
rotation
L'orientation du marqueur, spécifiée en degrés dans le sens horaire. La position par défaut change si le marqueur est plat. La position par défaut d'un marqueur plat est alignée sur le nord. Si le marqueur n'est pas plat, la position par défaut est à la verticale vers le haut et la rotation est telle que le marqueur est toujours face à l'appareil photo.

Le fragment ci-dessous crée un marqueur simple, avec l'icône par défaut.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE));

Personnaliser la couleur du marqueur

Il est possible de personnaliser la couleur de l'image par défaut du marqueur en transmettant un objet BitmapDescriptor à la méthode icon(). Vous pouvez utiliser un ensemble de couleurs prédéfinies dans l'objet BitmapDescriptorFactory ,ou définir une couleur de marqueur personnalisée avec la méthode BitmapDescriptorFactory.defaultMarker(float hue). La teinte est une valeur comprise entre 0 et 360, représentant des points sur une roue chromatique.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

Personnaliser l'opacité du marqueur

Vous pouvez contrôler l'opacité du marqueur avec la méthode MarkerOptions.alpha(). La valeur alpha doit être définie en tant que valeur flottante comprise entre 0.0 et 1.0, où 0 est totalement transparent et 1 totalement opaque.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .alpha(0.7f));

Personnaliser l'image d'un marqueur

Vous pouvez remplacer l'image de marqueur par défaut par une image de marqueur personnalisée, souvent appelée icône. Les icônes personnalisées sont toujours paramétrées en tant que BitmapDescriptor et définies à l'aide de l'une des méthodes de la classe BitmapDescriptorFactory.

fromAsset(String assetName)
Crée un marqueur personnalisé en utilisant le nom d'une image Bitmap dans le répertoire de ressources.
fromBitmap(Bitmap image)
Crée un marqueur personnalisé à partir d'une image Bitmap.
fromFile(String fileName)
Crée une icône personnalisée en utilisant le nom d'un fichier d'image Bitmap enregistré dans la mémoire de stockage interne.
fromPath(String absolutePath)
Crée un marqueur personnalisé à partir du chemin d'accès absolu d'un fichier d'image Bitmap.
fromResource(int resourceId)
Crée un marqueur personnalisé en utilisant l'ID de ressource d'une image Bitmap.

L'extrait ci-dessous crée un marqueur avec une icône personnalisée.

  private static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
  private Marker melbourne = mMap.addMarker(new MarkerOptions()
                            .position(MELBOURNE)
                            .title("Melbourne")
                            .snippet("Population: 4,137,400")
                            .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

Aplatir un marqueur

Les icônes de marqueur sont normalement dessinées en tenant compte de l'écran ; une rotation, une inclinaison ou un zoom sur la carte ne changent pas l'orientation du marqueur. Vous pouvez définir l'orientation d'un marqueur pour qu'elle soit plane par rapport à la terre. Les marqueurs qui sont orientés de cette façon pivotent lorsque l'on fait pivoter la carte, et changent de perspective lorsque la carte est inclinée. Les marqueurs plats conservent leurs dimensions lorsque l'on effectue un zoom avant ou arrière sur la carte.

Pour changer l'orientation du marqueur, définissez la propriété flat du marqueur sur true.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .flat(true));

Faire pivoter un marqueur

Vous pouvez faire pivoter un marqueur sur son point d'ancrage à l'aide de la méthode Marker.setRotation(). La rotation se mesure en degrés dans le sens horaire à partir de la position par défaut. Lorsque le marqueur est plat sur la carte, la position par défaut est le nord. Si le marqueur n'est pas plat, la position par défaut pointe vers le haut et la rotation est telle que le marqueur est toujours orienté face à l'appareil photo.

L'exemple ci-dessous fait pivoter le marqueur de 90°. En réglant le point d'ancrage sur 0.5,0.5, le marqueur pivote sur son centre, et non sur sa base.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .anchor(0.5,0.5)
                          .rotation(90.0));

Propriété z-index du marqueur

La propriété z-index indique l'ordre d'empilement d'un marqueur par rapport aux autres marqueurs sur la carte. Un marqueur avec une propriété z-index élevée apparaît au-dessus des marqueurs ayant une propriété z-index moins élevée. La valeur par défaut de la propriété z-index est 0.

Définissez la propriété z-index dans l'objet options du marqueur en appelant MarkerOptions.zIndex(), tel qu'illustré dans l'extrait de code suivant :

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Marker z1")
        .zIndex(1.0f));
}

Vous pouvez accéder à la propriété z-index du marqueur en appelant Marker.getZIndex() et la modifier en appelant Marker.setZIndex().

Les marqueurs sont toujours affichés au-dessus des calques de tuiles et des autres superpositions non constituées de marqueurs (superpositions au sol, polylignes, polygones et autres formes), et ce quelle que soit la propriété z-index des autres superpositions. Les marqueurs sont en effet considérés comme appartenant à un groupe z-index distinct par rapport aux autres superpositions.

Voir l'incidence de la propriété z-index sur les événements de clic ci-dessous.

Gérer les événements de marqueur

Maps API vous permet d'écouter et de répondre à des événements de marqueur. Pour écouter ces événements, vous devez régler l'écouteur (listener) correspondant sur l'objet GoogleMap auquel les marqueurs appartiennent. Lorsque l'événement se produit sur l'un des marqueurs de la carte, le rappel de l'écouteur est appelé avec l'objet Marker correspondant passé comme paramètre. Pour comparer cet objet Marker contenant votre propre référence à un objet Marker, vous devez utiliser equals() et non ==.

Vous pouvez écouter les événements suivants :

Événements de clic sur un marqueur

Vous pouvez utiliser un OnMarkerClickListener pour écouter les événements de clic sur le marqueur. Pour définir cet écouteur sur la carte, appelez GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Dès qu'un utilisateur clique sur un marqueur, onMarkerClick(Marker) est appelé et le marqueur est transmis en tant qu'argument. Cette méthode renvoie une valeur booléenne qui indique si vous avez consommé l'événement (pour supprimer le comportement par défaut, par exemple). Si la valeur est false, le comportement par défaut se produit en plus du comportement personnalisé. Le comportement par défaut pour un événement de clic sur un marqueur est d'afficher sa fenêtre d'info (si disponible) et de déplacer l'appareil photo de sorte que le marqueur soit centré sur la carte.

Incidence de la propriété z-index sur les événements de clic :

  • Lorsqu'un utilisateur clique sur un groupe de marqueurs, l'événement de clic est déclenché pour le marqueur ayant la valeur z-index la plus élevée.
  • Un seul événement peut être déclenché par clic. En d'autres termes, le clic n'est pas répercuté aux marqueurs ou autres superpositions ayant des valeurs z-index moins élevées.
  • Lorsque l'utilisateur clique sur un groupe de marqueurs, les clics suivants sélectionnent tour à tour tous les autres marqueurs du groupe. L'ordre dépend d'abord de la valeur z-index, puis de la proximité avec le point sur lequel l'utilisateur a cliqué.
  • Si l'utilisateur ne clique pas à proximité du groupe, l'API recalcule le groupe et réinitialise le cycle de clics pour qu'il recommence du début.

  • L'événement de clic passe des groupes de marqueurs aux autres formes et superpositions avant de revenir au début du cycle.

  • Les marqueurs sont considérés comme appartenant à un groupe z-index distinct par rapport aux autres superpositions ou formes (polylignes, polygones, cercles et/ou superpositions au sol), et ce quelle que soit la propriété z-index des autres superpositions. Si plusieurs marqueurs, superpositions ou formes sont superposées les un(e)s sur les autres, l'événement de clic passe d'abord d'un marqueur à l'autre dans le groupe de marqueurs, puis il est déclenché pour les autres superpositions ou formes en fonction de leur valeur z-index.

Événements de glissement de marqueur

Vous pouvez utiliser un OnMarkerDragListener pour écouter les événements de glissement de marqueur. Pour définir cet écouteur sur la carte, appelez GoogleMap.setOnMarkerDragListener. Pour faire glisser un marqueur, l'utilisateur doit appuyer dessus de façon prolongée. Dès que l'utilisateur retire son doigt de l'écran, le marqueur reste dans cette position. Lors du glissement d'un marqueur, onMarkerDragStart(Marker) est appelé au départ. Pendant le glissement du marqueur, onMarkerDrag(Marker) est appelé en continu. À la fin du glissement onMarkerDragEnd(Marker) est appelé. Vous pouvez obtenir la position du marqueur à tout moment en appelant Marker.getPosition().

Remarque : Par défaut, un marqueur n'est pas déplaçable. Un marqueur doit explicitement être défini comme déplaçable avant qu'un utilisateur puisse le faire glisser. Cela peut se faire avec MarkerOptions.draggable(boolean) avant de l'ajouter à la carte, ou avec Marker.setDraggable(boolean) une fois qu'il a été ajouté à la carte.

Envoyer des commentaires concernant…

Google Maps Android API
Google Maps Android API
Besoin d'aide ? Consultez notre page d'assistance.