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

Formes

Google Maps API for Android dispose de moyens simples vous permettant d'ajouter des formes à vos cartes afin de les personnaliser pour votre application.

  • Une polyligne (Polyline) est une série de segments de lignes connectés qui peuvent créer n'importe quelle forme et être utilisés pour marquer des tracés et des itinéraires sur la carte.
  • Un polygone (Polygon) est une forme fermée qui peut être utilisée pour marquer des zones sur la carte.
  • Un cercle (Circle) est une projection géographique précise d'un cercle sur la surface de la Terre dessinée sur la carte.

Il est possible de personnaliser l'aspect de toutes ces formes en modifiant un certain nombre de propriétés.

Échantillons de code

Le référentiel ApiDemos sur GitHub inclut des échantillons qui montrent comment utiliser les formes et leurs fonctionnalités :

Polylignes

La classe Polyline définit un ensemble de segments de lignes connectés sur la carte. Un objet de type Polyline est composé d'un ensemble de points géographiques LatLng qui créent une série de segments de lignes, lesquelles relient ces points dans une séquence ordonnée.

Cette vidéo vous explique comment aider vos utilisateurs à atteindre leur destination, en utilisant des polylignes pour dessiner un tracé sur la carte.

Pour créer une polyligne, vous devez d'abord créer un objet PolylineOptions et y ajouter des points. Les points représentent un lieu à la surface de la Terre et sont exprimés en tant qu'objet LatLng. Les segments de lignes sont alors dessinés entre ces points dans l'ordre dans lequel vous les ajoutez à l'objet PolylineOptions. Pour ajouter des points à un objet PolylineOptions, appelez PolylineOptions.add(). Notez que cette méthode accepte un nombre variable de paramètres pour que vous puissiez ajouter plusieurs points à la fois (vous pouvez également appeler PolylineOptions.addAll(Iterable<LatLng>) si les points sont déjà dans une liste).

Vous pouvez ensuite ajouter la polyligne à une carte en appelant GoogleMap.addPolyline(PolylineOptions). Cette méthode renvoie un objet Polyline avec lequel vous pourrez modifier la polyligne par la suite.

L'extrait de code suivant montre comment ajouter un rectangle à une carte :

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions rectOptions = new PolylineOptions()
        .add(new LatLng(37.35, -122.0))
        .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
        .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
        .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
        .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = myMap.addPolyline(rectOptions);

Pour modifier la forme de la polyligne après l'avoir ajoutée, vous pouvez appeler Polyline.setPoints() et fournir une nouvelle liste de points pour la polyligne.

Vous pouvez personnaliser l'aspect de la polyligne aussi bien avant qu'après l'avoir ajoutée à la carte. Voir la section sur la personnalisation de l'aspect ci-dessous pour plus de détails.

Événements liés aux polylignes

Par défaut, les polylignes ne sont pas cliquables. Vous pouvez activer et désactiver la cliquabilité en appelant Polyline.setClickable(boolean).

Utilisez un écouteur OnPolylineClickListener pour écouter les événements de clic sur une polyligne cliquable. Pour définir cet écouteur sur la carte, appelez GoogleMap.setOnPolylineClickListener(OnPolylineClickListener). Lorsqu'un utilisateur clique sur une polyligne, vous recevez un rappel onPolylineClick(Polyline).

Polygones

Les objets Polygon sont similaires aux objets Polyline dans la mesure où ils sont composés d'une série de coordonnées dans une séquence ordonnée. Toutefois, au lieu d'être ouverts, les polygones sont conçus pour définir des régions au sein d'une boucle fermée dont l'intérieur est plein.

Pour ajouter un Polygon à la carte, vous pouvez procéder de la même manière que pour ajouter une Polyline. Créez tout d'abord un objet PolygonOptions et ajoutez-y des points. Ces points forment le contour du polygone. Vous devez ensuite ajouter le polygone à la carte en appelant GoogleMap.addPolygon(PolygonOptions) qui renvoie un objet Polygon.

L'extrait de code suivant ajoute un rectangle à une carte (notez que comme aucune couleur de remplissage n'a été définie, et que la couleur de remplissage par défaut est transparente, l'apparence sera exactement la même que celle de la polyligne dans l'extrait de code de la section précédente) :

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions rectOptions = new PolygonOptions()
              .add(new LatLng(37.35, -122.0),
                   new LatLng(37.45, -122.0),
                   new LatLng(37.45, -122.2),
                   new LatLng(37.35, -122.2),
                   new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = myMap.addPolygon(rectOptions);

Pour modifier la forme du polygone après l'avoir ajouté, vous pouvez appeler Polygon.setPoints() et fournir une nouvelle liste de points pour le contour du polygone.

Vous pouvez personnaliser l'aspect du polygone aussi bien avant qu'après l'avoir ajouté à la carte. Voir la section sur la personnalisation de l'aspect ci-dessous pour plus de détails.

Saisie semi-automatique des polygones

Dans l'exemple ci-dessus, le polygone est composé de cinq coordonnées, mais vous remarquerez que la première et la dernière correspondent au même point géographique, puisqu'il s'agit d'une boucle. Dans la pratique, en effet, comme les polygones définissent des zones fermées, vous n'avez pas besoin de définir la dernière coordonnée. Si la dernière coordonnée diffère de la première, l'API « ferme » automatiquement le polygone en ajoutant la première coordonnée à la fin de la séquence de coordonnées.

Les deux polygones ci-dessous sont équivalents, et le fait d'appeler polygon.getPoints() pour chacun renvoie les 4 points.

Polygon polygon = map.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(0, 0))
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE));

Polygon polygon = map.addPolygon(new PolygonOptions()
         .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
         .strokeColor(Color.RED)
         .fillColor(Color.BLUE));

Créer un polygone creux

Il est possible de combiner plusieurs tracés dans un même objet Polygon afin de créer des formes complexes, comme des anneaux pleins, ou « donuts » (où les zones polygonales apparaissent à l'intérieur du polygone comme des « îles »). Les formes complexes sont toujours composées de plusieurs tracés plus simples.

Deux tracés doivent être définis dans la même zone. La plus grande des deux régions définit la zone de remplissage et correspond à un polygone simple sans option supplémentaire. Transmettez ensuite un second tracé à la méthode addHole(). Une fois que le second tracé, plus petit, est totalement englobé par le tracé plus grand, on a l'impression qu'une partie du polygone a été retirée. Si le trou intersecte le contour du polygone, celui-ci sera rendu sans aucun remplissage.

Le fragment ci-dessous permet de créer un rectangle, avec un trou rectangulaire plus petit.

mMap.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(3, 0), new LatLng(0, 0))
        .addHole(new LatLng(1, 1), new LatLng(1, 2), new LatLng(2, 2), new LatLng(2, 1), new LatLng(1, 1))
        .fillColor(Color.BLUE));

Événements liés aux polygones

Par défaut, les polygones ne sont pas cliquables. Vous pouvez activer et désactiver la cliquabilité en appelant Polygon.setClickable(boolean).

Utilisez un écouteur OnPolygonClickListener pour écouter les événements de clic sur un polygone cliquable. Pour définir cet écouteur sur la carte, appelez GoogleMap.setOnPolygonClickListener(OnPolygonClickListener). Lorsqu'un utilisateur clique sur un polygone, vous recevez un rappel onPolygonClick(Polygon).

Cercles

En plus de la classe générique Polygon, Maps API inclut également des classes spécifiques pour les objets Circle afin de simplifier leur construction.

Pour construire un cercle, vous devez spécifier les deux propriétés suivantes :

  • center en tant que LatLng.
  • radius en mètres.

Un cercle est ensuite défini comme étant l'ensemble de tous les points à la surface de la Terre situés dans un rayon (radius) de n mètres autour d'un centre (center) donné. Étant donné que Maps API utilise une projection de Mercator pour effectuer le rendu d'une sphère sur une surface plane, cela donnera l'apparence d'un cercle presque parfait sur une carte au niveau de l'équateur, et de moins en moins circulaire (à l'écran) à mesure que ce cercle s'éloigne de l'équateur.

L'extrait de code suivant ajoute un cercle à la carte en construisant un objet CircleOptions et en appelant GoogleMap.addCircle(CircleOptions) :

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)); // In meters

// Get back the mutable Circle
Circle circle = myMap.addCircle(circleOptions);

Pour modifier la forme du cercle après l'avoir ajouté, vous pouvez appeler Circle.setRadius() ou Circle.setCenter() et fournir de nouvelles valeurs.

Vous pouvez personnaliser l'aspect du cercle aussi bien avant qu'après l'avoir ajouté à la carte. Voir la section sur la personnalisation de l'aspect ci-dessous pour plus de détails.

Événements liés aux cercles

Par défaut, les cercles ne sont pas cliquables. Vous pouvez activer et désactiver la cliquabilité en appelant GoogleMap.addCircle() avec CircleOptions.clickable(boolean) ou en appelant Circle.setClickable(boolean).

Utilisez un écouteur OnCircleClickListener pour écouter les événements de clic sur un cercle cliquable. Pour définir cet écouteur sur la carte, appelez GoogleMap.setOnCircleClickListener(OnCircleClickListener).

Lorsqu'un utilisateur clique sur un cercle, vous recevez un rappel onCircleClick(Circle), comme illustré dans l'échantillon de code suivant :

public class MyActivity extends FragmentActivity
        implements OnMapReadyCallback {

        private GoogleMap mMap;
        private Circle circle;

        @Override
        public void onMapReady(GoogleMap map) {
            mMap = map;

            circle = mMap.addCircle(new CircleOptions()
                .center(new LatLng(37.4, -122.1))
                .radius(1000)
                .strokeWidth(10)
                .strokeColor(Color.GREEN)
                .fillColor(Color.argb(128, 255, 0, 0))
                .clickable(true);

            map.setOnCircleClickListener(new OnCircleClickListener() {

                @Override
                public void onCircleClick(Circle circle) {
                    // Flip the r, g and b components of the circle's
                    // stroke color.
                    int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                    circle.setStrokeColor(strokeColor);
                }
            });
        }
}

Personnaliser l'aspect

Vous pouvez modifier l'aspect d'une forme aussi bien avant (en spécifiant la propriété souhaitée sur l'objet d'options) qu'après l'avoir ajoutée à la carte. Des accesseurs sont également proposés pour toutes les propriétés afin que vous puissiez accéder facilement à l'état actuel de la forme.

Le fragment suivant trace une polyligne épaisse bleue avec des segments géodésiques de Melbourne à Perth. Les sections ci-dessous expliquent ces différentes propriétés plus en détail.

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Remarque : Même si la plupart de ces propriétés peuvent être appliquées à n'importe quelle forme décrite ici, il se peut que quelques-unes d'entre elles n'aient aucun sens pour certaines formes (par exemple, une polyligne ne peut pas avoir de couleur de remplissage car elle n'a pas d'intérieur).

Couleur du trait

La couleur du trait est un nombre entier 32 bits ARVB (alpha-rouge-vert-bleu) qui détermine l'opacité et la couleur du trait de la forme. Définissez cette propriété sur l'objet d'options de la forme en appelant *Options.strokeColor() (ou PolylineOptions.color() dans le cas d'une polyligne). Si elle n'est pas spécifiée, la couleur du trait par défaut est le noir (Color.BLACK).

Une fois que la forme a été ajoutée à la carte, il est possible d'accéder à la couleur du trait en appelant getStrokeColor() (ou getColor() pour une polyligne) et de la modifier en appelant setStrokeColor() (setColor() for a polyline).

Couleur de remplissage

La couleur de remplissage ne s'applique qu'aux polygones et aux cercles. Elle ne s'applique pas aux polylignes car elles ne comportent pas d'intérieur défini. Pour un polygone, les régions situées à l'intérieur de ses trous ne font pas partie de l'intérieur du polygone et ne sont donc pas colorées si une couleur de remplissage est définie.

La couleur de remplissage correspond à un entier ARVB (alpha-rouge-vert-bleu) 32 bits définissant l'opacité et la couleur de l'intérieur de la forme. Définissez cette propriété sur l'objet d'options de la forme en appelant *Options.fillColor(). Si aucune couleur n'est spécifiée, la couleur de trait par défaut est transparente (Color.TRANSPARENT).

Une fois que la forme a été ajoutée à la carte, il est possible d'accéder à la couleur de remplissage en appelant getFillColor() et de la modifier en appelant setFillColor().

Épaisseur du trait

L'épaisseur du trait, en tant que valeur flottante en pixels (px). L'épaisseur n'est pas ajustée lors d'un zoom sur la carte (autrement dit, la forme garde la même épaisseur de trait à tous les niveaux de zoom). Définissez cette propriété sur l'objet d'option de la forme en appelant *Options.strokeWidth() (ou PolylineOptions.width() pour une polyligne). Si aucune option n'est spécifiée, l'épaisseur du trait par défaut est de 10 pixels.

Une fois que la forme a été ajoutée à la carte, il est possible d'accéder à l'épaisseur du trait en appelant getStrokeWidth() (ou getWidth() pour une polyligne) et de la modifier en appelant setStrokeWidth() (setWidth() for a polyline).

Segments géodésiques

Le paramètre géodésique ne s'applique qu'aux polylignes et aux polygones. Il ne s'applique pas aux cercles car ils ne sont pas définis comme une série de segments.

Le paramètre géodésique détermine comment sont dessinés les segments de lignes entre des sommets consécutifs de la polyligne/du polygone. Les segments géodésiques sont ceux qui suivent le tracé le plus court à la surface de la Terre (sphère) ; ils apparaissent souvent comme des lignes courbes sur une carte utilisant une projection de Mercator. Les segments non géodésiques sont représentés par des lignes droites sur la carte.

Définissez cette propriété sur l'objet d'option de la forme en appelant *Options.geodesic()true indique que les segments doivent être représentés sous forme de géodésiques et false indique que les segments doivent être représentés sous forme de lignes droites. Si aucune valeur n'est spécifiée, la valeur par défaut correspond à des segments non géodésiques (false).

Une fois que la forme a été ajoutée à la carte, il est possible d'accéder au paramètre géodésique en appelant isGeodesic() et de le modifier en appelant setGeodesic().

Propriété z-index

La propriété z-index désigne l'ordre d'empilement de cette forme par rapport aux autres superpositions (autres formes, superpositions au sol et superpositions de tuiles) sur la carte. Une superposition avec un z-index élevé s'affiche au-dessus des superpositions comportant des z-index plus faibles. Deux superpositions comportant la même valeur z-index apparaissent dans un ordre arbitraire.

Notez que les marqueurs sont toujours dessinés au-dessus d'autres superpositions, quelle que soit la propriété z-index de ces autres superpositions.

Définissez cette propriété sur l'objet d'options de la forme en appelant *Options.zIndex(). Si aucune valeur n'est indiquée, la valeur par défaut du z-index est 0. Une fois que la forme a été ajoutée à la carte, il est possible d'accéder au z-index en appelant getZIndex() et de le modifier en appelant setZIndex().

Visibilité

La visibilité détermine si la forme doit être dessinée sur la carte, où true indique qu'elle doit être dessinée et false qu'elle ne doit pas être dessinée. Elle vous permet de désactiver temporairement l'affichage d'une forme sur la carte. Pour supprimer définitivement la forme de la carte, appelez remove() sur cette forme.

Définissez cette propriété sur l'objet d'options de la forme en appelant *Options.visible(). Si aucune valeur n'est indiquée, la valeur par défaut de la visibilité est true. Une fois que la forme a été ajoutée à la carte, il est possible d'accéder à la visibilité en appelant isVisible() et de la modifier en appelant setVisible().

Envoyer des commentaires concernant…

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