Polylignes et polygones pour représenter des itinéraires et des zones

Ce tutoriel vous montre comment ajouter une carte Google à votre application Android, et comment utiliser des polylignes et des polygones pour représenter des itinéraires et des zones sur une carte.

Suivez ce tutoriel pour créer une application Android en utilisant le SDK Maps pour Android. L'environnement de développement recommandé est Android Studio.

Obtenir le code

Clonez ou téléchargez le référentiel d'exemples Google Maps Android API v2 à partir de GitHub.

Configurer votre projet de développement

Suivez les étapes ci-dessous pour créer le projet du tutoriel dans Android Studio.

  1. Téléchargez et installez Android Studio.
  2. Ajoutez le package de services Google Play à Android Studio.
  3. Clonez ou téléchargez le référentiel d'exemples Google Maps Android API v2 si vous ne l'avez pas déjà fait au début de ce tutoriel.
  4. Importez le projet du tutoriel :

    • Dans Android Studio, sélectionnez File > New > Import Project.
    • Accédez à l'emplacement où vous avez enregistré le référentiel d'exemples Google Maps Android API v2 après l'avoir téléchargé.
    • Localisez le projet Polygons à l'adresse suivante :
      PATH-TO-SAVED-REPO/android-samples/tutorials/Polygons
    • Sélectionnez le répertoire du projet, puis cliquez sur OK. Android Studio crée à présent votre projet à l'aide de l'outil de compilation Gradle.

Obtenir une clé API et activer les API nécessaires

Pour suivre ce tutoriel, vous devez disposer d'une clé API Google autorisée à utiliser le SDK Maps pour Android.

Cliquez sur le bouton ci-dessous pour obtenir une clé et activer l'API.

Commencer

Pour plus d'informations, consultez le guide complet qui explique comment obtenir une clé API.

Ajouter la clé API à votre application

  1. Modifiez le fichier gradle.properties de votre projet.
  2. Collez votre clé API dans la valeur de la propriété GOOGLE_MAPS_API_KEY. Lorsque vous compilez l'application, Gradle copie la clé API dans le fichier manifeste Android de l'application, comme expliqué ci-dessous.

    GOOGLE_MAPS_API_KEY=PASTE-YOUR-API-KEY-HERE
    

Compiler et exécuter votre application

  1. Connectez un appareil Android à votre ordinateur. Suivez les instructions pour activer les options pour les développeurs sur votre appareil Android et configurer votre système afin qu'il détecte l'appareil. Vous pouvez également utiliser l'outil AVD (Android Virtual Device) Manager pour configurer un appareil virtuel. Lorsque vous choisissez un émulateur, assurez-vous de sélectionner une image qui inclut les API Google. Pour plus d'informations, consultez le guide de démarrage.
  2. Dans Android Studio, cliquez sur l'option de menu Run (ou sur l'icône du bouton de lecture). Choisissez un appareil lorsque vous y êtes invité.

Android Studio invoque Gradle pour créer l'application, puis l'exécute sur l'appareil ou sur l'émulateur.

Vous devriez voir une carte avec deux polygones superposés en haut de l'Australie, comme dans l'image sur cette page.

Résolution des erreurs :

  • Si aucune carte ne s'affiche, vérifiez que vous avez bien obtenu une clé API et que vous l'avez ajoutée à l'application, comme décrit ci-dessus. Consultez le journal Android Monitor d'Android Studio pour vérifier s'il contient des messages d'erreur concernant la clé API.
  • Utilisez les outils de débogage d'Android Studio pour afficher les journaux et déboguer l'application.

Comprendre le code

Cette partie du tutoriel décrit les principales composantes de l'application Polygons pour vous aider à comprendre comment créer une application similaire.

Vérifier votre fichier manifeste Android

Notez les éléments suivants dans le fichier AndroidManifest.xml de votre application :

  • Ajoutez un élément meta-data pour intégrer la version des services Google Play avec laquelle l'application a été compilée.

    <meta-data
        android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version" />
    
  • Ajoutez un élément meta-data spécifiant votre clé API. L'exemple accompagnant ce tutoriel associe la valeur de la clé API à une chaîne google_maps_key. Lorsque vous compilez l'application, Gradle copie la clé API du fichier gradle.properties de votre projet vers la valeur de la chaîne.

    <meta-data
      android:name="com.google.android.geo.API_KEY"
      android:value="@string/google_maps_key" />
    

    Pour voir comment la clé API est mappée sur la valeur de la chaîne, examinez le fichier build.gradle de votre application. Il contient la ligne suivante, qui mappe la chaîne google_maps_key sur la propriété GOOGLE_MAPS_API_KEY de l'outil Gradle :

    resValue "string", "google_maps_key",
            (project.findProperty("GOOGLE_MAPS_API_KEY") ?: "")
    

Voici un exemple complet de fichier manifeste :

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.polygons">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <!--
             The API key for Google Maps-based APIs.
        -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="@string/google_maps_key" />

        <activity
            android:name="com.example.polygons.PolyActivity"
            android:label="@string/title_activity_maps">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Ajouter une carte

Affichez une carte à l'aide du SDK Maps pour Android.

  1. Ajoutez un élément <fragment> au fichier de mise en page de votre activité, activity_maps.xml. Cet élément définit un fragment SupportMapFragment pour servir de conteneur à la carte et donner accès à l'objet GoogleMap. Ce tutoriel utilise la version du fragment de carte issue de la bibliothèque Android Support afin de garantir sa rétrocompatibilité avec les versions précédentes du framework Android.

    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context="com.example.polygons.PolyActivity" />
    
    
  2. Dans la méthode onCreate() de votre activité, définissez le fichier de mise en page en tant que vue de contenu. Obtenez un handle vers le fragment de carte en appelant FragmentManager.findFragmentById(). Ensuite, utilisez getMapAsync() pour vous inscrire au rappel de la carte :

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps);
    
        // Get the SupportMapFragment and request notification when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(map);
        mapFragment.getMapAsync(this);
    }
    
  3. Ajoutez l'interface OnMapReadyCallback et ignorez la méthode onMapReady(). L'API invoque ce rappel lorsque l'objet GoogleMap est disponible. Vous pouvez ainsi ajouter des objets à la carte et la personnaliser pour votre application :

    public class PolyActivity extends AppCompatActivity
            implements
                    OnMapReadyCallback,
                    GoogleMap.OnPolylineClickListener,
                    GoogleMap.OnPolygonClickListener {
    
        // More code goes here, including the onCreate() method described above.
    
        @Override
        public void onMapReady(GoogleMap googleMap) {
    
            // Add polylines and polygons to the map. This section shows just
            // a single polyline. Read the rest of the tutorial to learn more.
            Polyline polyline1 = googleMap.addPolyline(new PolylineOptions()
                    .clickable(true)
                    .add(
                            new LatLng(-35.016, 143.321),
                            new LatLng(-34.747, 145.592),
                            new LatLng(-34.364, 147.891),
                            new LatLng(-33.501, 150.217),
                            new LatLng(-32.306, 149.248),
                            new LatLng(-32.491, 147.309)));
    
            // Position the map's camera near Alice Springs in the center of Australia,
            // and set the zoom factor so most of Australia shows on the screen.
            googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(-23.684, 133.903), 4));
    
            // Set listeners for click events.
            googleMap.setOnPolylineClickListener(this);
            googleMap.setOnPolygonClickListener(this);
        }
    }
    

Ajouter une polyligne pour tracer une ligne sur la carte

Une Polyline est une série de segments de ligne connectés. Les polylignes sont utiles pour représenter des itinéraires, des trajets ou d'autres connexions entre des lieux sur la carte.

  1. Créez un objet PolylineOptions et ajoutez-lui des points. Chaque point représente un emplacement sur la carte, que vous définissez avec un objet LatLng contenant des valeurs de latitude et de longitude. L'exemple de code ci-dessous crée une polyligne comportant 6 points.

  2. Appelez GoogleMap.addPolyline() pour ajouter la polyligne à la carte.

    Polyline polyline1 = googleMap.addPolyline(new PolylineOptions()
            .clickable(true)
            .add(
                    new LatLng(-35.016, 143.321),
                    new LatLng(-34.747, 145.592),
                    new LatLng(-34.364, 147.891),
                    new LatLng(-33.501, 150.217),
                    new LatLng(-32.306, 149.248),
                    new LatLng(-32.491, 147.309)));
    

Définissez l'option clickable de la polyligne sur true si vous souhaitez gérer les événements de clic sur la polyligne. Vous trouverez plus d'informations sur la gestion des événements dans ce tutoriel.

Stocker des données arbitraires avec une polyligne

Vous pouvez stocker des objets de données arbitraires avec des polylignes et d'autres objets de géométrie.

  1. Appelez Polyline.setTag() pour stocker un objet de données avec la polyligne. Le code ci-dessous définit un tag arbitraire (A) indiquant un type de polyligne.

    Polyline polyline1 = googleMap.addPolyline(new PolylineOptions()
            .clickable(true)
            .add(
                    new LatLng(-35.016, 143.321),
                    new LatLng(-34.747, 145.592),
                    new LatLng(-34.364, 147.891),
                    new LatLng(-33.501, 150.217),
                    new LatLng(-32.306, 149.248),
                    new LatLng(-32.491, 147.309)));
    // Store a data object with the polyline, used here to indicate an arbitrary type.
    polyline1.setTag("A");
    
  2. Récupérez les données en utilisant Polyline.getTag(), comme le montre la section suivante.

Ajouter un style personnalisé à votre polyligne

Vous pouvez spécifier différentes propriétés de style dans l'objet PolylineOptions. Les options de style incluent la couleur du trait, la largeur du trait, la forme du trait, les types de jointure, ainsi que les terminaisons de début et de fin. Si vous ne spécifiez pas de propriété particulière, l'API utilise la valeur par défaut de cette propriété.

Le code suivant applique une terminaison arrondie à la fin de la ligne et une terminaison de début qui varie selon le type de la polyligne, le type étant une propriété arbitraire stockée dans l'objet de données de la polyligne. L'exemple spécifie également une largeur de trait, une couleur de trait et un type de jointure :

private static final int COLOR_BLACK_ARGB = 0xff000000;
private static final int POLYLINE_STROKE_WIDTH_PX = 12;

private void stylePolyline(Polyline polyline) {
    String type = "";
    // Get the data object stored with the polyline.
    if (polyline.getTag() != null) {
        type = polyline.getTag().toString();
    }

    switch (type) {
        // If no type is given, allow the API to use the default.
        case "A":
            // Use a custom bitmap as the cap at the start of the line.
            polyline.setStartCap(
                    new CustomCap(
                            BitmapDescriptorFactory.fromResource(R.drawable.ic_arrow), 10));
            break;
        case "B":
            // Use a round cap at the start of the line.
            polyline.setStartCap(new RoundCap());
            break;
    }

    polyline.setEndCap(new RoundCap());
    polyline.setWidth(POLYLINE_STROKE_WIDTH_PX);
    polyline.setColor(COLOR_BLACK_ARGB);
    polyline.setJointType(JointType.ROUND);
}

Le code ci-dessus spécifie une image bitmap personnalisée pour le début de la polyligne de type A et spécifie une largeur de trait de référence de 10 pixels. L'API met à l'échelle l'image bitmap en fonction de la largeur du trait de référence. Lorsque vous spécifiez la largeur du trait de référence, indiquez la largeur que vous avez utilisée lors de la conception de l'image bitmap, à la dimension d'origine de l'image. Conseil : Ouvrez l'image bitmap à 100 % de zoom dans un éditeur d'images et définissez la largeur de trait souhaitée par rapport à l'image.

En savoir plus sur les terminaisons de ligne et sur les autres options de personnalisation des formes

Gérer les événements de clic sur la polyligne

  1. Rendez la polyligne cliquable en appelant la méthode Polyline.setClickable(). Par défaut, les polylignes ne sont pas cliquables et votre application ne reçoit pas de notification lorsque l'utilisateur appuie sur une polyligne.

  2. Ajoutez l'interface OnPolylineClickListener et appelez la méthode GoogleMap.setOnPolylineClickListener() pour définir l'écouteur sur la carte :

    public class PolyActivity extends AppCompatActivity
            implements
                    OnMapReadyCallback,
                    GoogleMap.OnPolylineClickListener,
                    GoogleMap.OnPolygonClickListener {
    
        @Override
        public void onMapReady(GoogleMap googleMap) {
            // Add a polyline to the map.
            Polyline polyline1 = googleMap.addPolyline((new PolylineOptions())
                    .clickable(true)
                    .add(new LatLng(-35.016, 143.321),
                            new LatLng(-34.747, 145.592),
                            new LatLng(-34.364, 147.891),
                            new LatLng(-33.501, 150.217),
                            new LatLng(-32.306, 149.248),
                            new LatLng(-32.491, 147.309)));
    
            // Set listeners for click events.
            googleMap.setOnPolylineClickListener(this);
            googleMap.setOnPolygonClickListener(this);
        }
    }
    
  3. Ignorez la méthode de rappel onPolylineClick(). L'exemple suivant modifie le motif du trait en passant de la ligne continue à la ligne en pointillé chaque fois que l'internaute clique sur la polyligne :

    private static final PatternItem DOT = new Dot();
    private static final PatternItem GAP = new Gap(PATTERN_GAP_LENGTH_PX);
    //
    // Create a stroke pattern of a gap followed by a dot.
    private static final List<PatternItem> PATTERN_POLYLINE_DOTTED = Arrays.asList(GAP, DOT);
    
    @Override
    public void onPolylineClick(Polyline polyline) {
        // Flip from solid stroke to dotted stroke pattern.
        if ((polyline.getPattern() == null) || (!polyline.getPattern().contains(DOT))) {
            polyline.setPattern(PATTERN_POLYLINE_DOTTED);
        } else {
            // The default pattern is a solid stroke.
            polyline.setPattern(null);
        }
    
        Toast.makeText(this, "Route type " + polyline.getTag().toString(),
                Toast.LENGTH_SHORT).show();
    }
    

Ajouter des polygones pour représenter les zones sur la carte

Un Polygon est une forme constituée d'une série de coordonnées dans une séquence ordonnée, semblable à une Polyline. La différence réside dans le fait qu'un polygone définit une zone fermée, dont l'intérieur peut être rempli, tandis qu'une polyligne définit une zone ouverte.

  1. Créez un objet PolygonOptions et ajoutez-lui des points. Chaque point représente un emplacement sur la carte, que vous définissez avec un objet LatLng contenant des valeurs de latitude et de longitude. L'exemple de code ci-dessous crée un polygone comportant 4 points.

  2. Rendez le polygone cliquable en appelant la méthode Polygon.setClickable(). Par défaut, les polygones ne sont pas cliquables et votre application ne reçoit pas de notification lorsque l'utilisateur appuie sur un polygone. Les événements de clic sur un polygone se gèrent de la même manière que les événements de clic sur une polyligne, comme expliqué précédemment dans ce tutoriel.

  3. Appelez GoogleMap.addPolygon() pour ajouter le polygone à la carte.

  4. Appelez Polygon.setTag() pour stocker un objet de données avec le polygone. Le code ci-dessous définit un type arbitraire (alpha) pour le polygone.

    Polygon polygon1 = googleMap.addPolygon(new PolygonOptions()
            .clickable(true)
            .add(
                    new LatLng(-27.457, 153.040),
                    new LatLng(-33.852, 151.211),
                    new LatLng(-37.813, 144.962),
                    new LatLng(-34.928, 138.599)));
    // Store a data object with the polygon, used here to indicate an arbitrary type.
    polygon1.setTag("alpha");
    

Ajouter un style personnalisé à votre polygone

Vous pouvez spécifier un certain nombre de propriétés de style dans l'objet PolygonOptions. Les options de style incluent la couleur du trait, la largeur du trait, le motif du trait, les types de jointure et la couleur de remplissage. Si vous ne spécifiez pas de propriété particulière, l'API utilise la valeur par défaut de cette propriété.

Le code suivant applique des couleurs et des motifs de trait spécifiques en fonction du type du polygone, le type étant une propriété arbitraire stockée dans l'objet de données du polygone :

private static final int COLOR_BLACK_ARGB = 0xff000000;
private static final int COLOR_WHITE_ARGB = 0xffffffff;
private static final int COLOR_GREEN_ARGB = 0xff388E3C;
private static final int COLOR_PURPLE_ARGB = 0xff81C784;
private static final int COLOR_ORANGE_ARGB = 0xffF57F17;
private static final int COLOR_BLUE_ARGB = 0xffF9A825;

private static final int POLYGON_STROKE_WIDTH_PX = 8;
private static final int PATTERN_DASH_LENGTH_PX = 20;
private static final int PATTERN_GAP_LENGTH_PX = 20;
private static final PatternItem DOT = new Dot();
private static final PatternItem DASH = new Dash(PATTERN_DASH_LENGTH_PX);
private static final PatternItem GAP = new Gap(PATTERN_GAP_LENGTH_PX);

// Create a stroke pattern of a gap followed by a dash.
private static final List<PatternItem> PATTERN_POLYGON_ALPHA = Arrays.asList(GAP, DASH);

// Create a stroke pattern of a dot followed by a gap, a dash, and another gap.
private static final List<PatternItem> PATTERN_POLYGON_BETA =
        Arrays.asList(DOT, GAP, DASH, GAP);

private void stylePolygon(Polygon polygon) {
    String type = "";
    // Get the data object stored with the polygon.
    if (polygon.getTag() != null) {
        type = polygon.getTag().toString();
    }

    List<PatternItem> pattern = null;
    int strokeColor = COLOR_BLACK_ARGB;
    int fillColor = COLOR_WHITE_ARGB;

    switch (type) {
        // If no type is given, allow the API to use the default.
        case "alpha":
            // Apply a stroke pattern to render a dashed line, and define colors.
            pattern = PATTERN_POLYGON_ALPHA;
            strokeColor = COLOR_GREEN_ARGB;
            fillColor = COLOR_PURPLE_ARGB;
            break;
        case "beta":
            // Apply a stroke pattern to render a line of dots and dashes, and define colors.
            pattern = PATTERN_POLYGON_BETA;
            strokeColor = COLOR_ORANGE_ARGB;
            fillColor = COLOR_BLUE_ARGB;
            break;
    }

    polygon.setStrokePattern(pattern);
    polygon.setStrokeWidth(POLYGON_STROKE_WIDTH_PX);
    polygon.setStrokeColor(strokeColor);
    polygon.setFillColor(fillColor);
}

En savoir plus sur les motifs de trait et sur les autres options de personnalisation des formes

Étapes suivantes

En savoir plus sur l'objet Cercle Les cercles sont similaires aux polygones, mais leurs propriétés reflètent la forme d'un cercle.