C'est le 15e anniversaire de Google Maps Platform. Découvrez les dernières actualités et annonces.

Objets de carte

Dans l'API, les cartes sont représentées par les classes GoogleMap et MapFragment.

Exemples de code

Le référentiel ApiDemos sur GitHub inclut des exemples illustrant l'utilisation de l'objet GoogleMap et du fragment SupportMapFragment :

Ajouter une carte à une application Android

Les principales étapes pour ajouter une carte sont les suivantes :

  1. (Cette opération n'est à effectuer qu'une seule fois.) Suivez les étapes décrites dans le guide de configuration d'un projet pour télécharger l'API, obtenir une clé et ajouter les attributs obligatoires à votre fichier manifeste Android.
  2. Ajoutez un objet Fragment à la classe Activity qui va gérer la carte. Le plus simple est alors d'ajouter un élément <fragment> au fichier de mise en page pour la classe Activity.
  3. Ajoutez l'interface OnMapReadyCallback et utilisez la méthode de rappel onMapReady(GoogleMap) pour obtenir un handle de l'objet GoogleMap. L'objet GoogleMap correspond à la représentation interne de la carte elle-même. Pour définir les options d'affichage d'une carte, vous devez modifier l'objet GoogleMap correspondant.
  4. Appelez getMapAsync() sur le fragment pour enregistrer le rappel.

Vous trouverez ci-dessous des informations plus détaillées sur chaque étape.

Ajouter un fragment

Ajoutez un élément <fragment> au fichier de mise en page de l'activité pour définir un objet Fragment. Dans cet élément, définissez l'attribut android:name sur "com.google.android.gms.maps.MapFragment". Cette opération ajoute automatiquement un fragment MapFragment à l'activité.

Le fichier de mise en page suivant contient un élément <fragment> :

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

Vous pouvez également ajouter un fragment MapFragment à une classe Activity dans le code. Pour cela, créez une nouvelle instance MapFragment, puis appelez FragmentTransaction.add() pour ajouter le Fragment à la classe Activity actuelle.

 mMapFragment = MapFragment.newInstance();
 FragmentTransaction fragmentTransaction =
         getFragmentManager().beginTransaction();
 fragmentTransaction.add(R.id.my_container, mMapFragment);
 fragmentTransaction.commit();

Ajouter le code de la carte

Pour utiliser la carte dans votre application, vous devez ajouter l'interface OnMapReadyCallback et définir une instance du rappel sur un objet MapFragment ou MapView. Ce tutoriel utilise un objet MapFragment, car c'est le moyen le plus courant d'ajouter une carte à une application. La première étape consiste à mettre en place l'interface de rappel :

public class MainActivity extends FragmentActivity
    implements OnMapReadyCallback {
...
}

Dans la méthode Activity de votre onCreate(), définissez le fichier de mise en page en tant que vue de contenu. Par exemple, si le fichier de mise en page porte le nom main.xml, utilisez le code suivant :

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

Obtenez un handle vers le fragment en appelant FragmentManager.findFragmentById(), en lui spécifiant l'identifiant de ressource de votre élément <fragment>. Notez que l'identifiant de ressource R.id.map est ajouté automatiquement au projet Android lors de la création du fichier de mise en page.

Utilisez ensuite getMapAsync() pour définir le rappel sur le fragment.

MapFragment mapFragment = (MapFragment) getFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

Utilisez la méthode de rappel onMapReady(GoogleMap) pour obtenir un handle vers l'objet GoogleMap. Le rappel est déclenché dès que la carte est prête à être utilisée. Il fournit une instance non nulle de GoogleMap. Vous pouvez utiliser l'objet GoogleMap pour définir les options d'affichage de la carte ou ajouter un repère, par exemple.

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

L'objet de carte

Le SDK Maps pour Android vous permet d'afficher une carte Google dans votre application Android. Ces cartes ont la même apparence que celles qui apparaissent dans l'application Google Maps pour mobile et l'API présente de nombreuses fonctionnalités identiques. L'application Google Maps pour mobile et les cartes affichées par le SDK Maps pour Android présentent toutefois deux différences notables :

  • Les tuiles de carte affichées par l'API ne contiennent aucun contenu personnalisé, tel que des icônes intelligentes personnalisées.
  • Toutes les icônes de la carte ne sont pas cliquables. Par exemple, les icônes des arrêts de transports en commun ne sont pas cliquables. En revanche, les repères que vous ajoutez à la carte sont cliquables et l'API dispose d'une interface de rappel d'écouteur pour diverses interactions avec les repères.

Outre la fonctionnalité de cartographie, l'API prend aussi en charge toute une gamme d'interactions conformes au modèle de l'interface utilisateur Android. Vous pouvez, par exemple, paramétrer des interactions sur une carte en définissant des écouteurs qui répondent aux gestes de l'utilisateur.

La classe principale lors de l'utilisation d'un objet de carte est la classe GoogleMap. GoogleMap modélise l'objet de carte dans votre application. Dans votre interface utilisateur, une carte sera représentée soit par un objet MapFragment, soit par un objet MapView.

GoogleMap gère 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)

En plus de ces opérations automatiques, vous pouvez contrôler le comportement des cartes avec les objets et les méthodes de l'API. Par exemple, GoogleMap dispose de méthodes de rappel qui répondent à l'appui sur les touches du clavier et aux gestes effectués sur l'écran tactile sur la carte. Vous pouvez également définir des icônes de repère sur votre carte et y ajouter des superpositions, en utilisant des objets qui vous fournissez à GoogleMap.

MapFragment

MapFragment, une sous-classe de la classe Android Fragment, vous permet de placer une carte dans un fragment Android. Les objets MapFragment servent de conteneur à la carte et donnent accès à l'objet GoogleMap.

Contrairement à une View, un Fragment représente un comportement ou une partie de l'interface utilisateur dans une activité. Vous pouvez combiner plusieurs fragments dans une même activité pour créer une interface utilisateur à plusieurs volets et réutiliser un fragment dans plusieurs activités. Reportez-vous à la documentation Android sur Fragments pour en savoir plus.

MapView

MapView, une sous-classe de la classe Android View, vous permet de placer une carte dans une View Android. Une View représente une zone rectangulaire de l'écran. C'est une composante fondamentale des applications et des widgets Android. À l'instar d'un MapFragment, le MapView joue le rôle de conteneur pour la carte, en activant la fonctionnalité de carte principale via l'objet GoogleMap.

S'ils utilisent l'API en mode interactif complet, les utilisateurs de la classe MapView doivent transmettre les méthodes suivantes du cycle de vie d'activité aux méthodes correspondantes de la classe MapView : onCreate(), onStart(), onResume(), onPause(), onStop(), onDestroy(), onSaveInstanceState() et onLowMemory(). Le référentiel ApiDemos sur GitHub inclut un exemple qui montre comment transférer les méthodes du cycle de vie d'activité. Lorsque l'API est utilisée en mode simplifié, le transfert des événements de cycle de vie est facultatif. Pour plus d'informations, consultez la documentation du mode simplifié.

Types de carte

De nombreux types de cartes sont disponibles dans le SDK Maps pour Android. Le type d'une carte régit la représentation générale de cette carte. Par exemple, un atlas contient généralement des cartes politiques qui mettent l'accent sur les frontières et des cartes routières qui montrent toutes les routes d'une ville ou d'une région.

Le SDK Maps pour Android propose quatre types de cartes, ainsi qu'une option pour n'afficher aucune carte :

Normal
Carte routière classique. Affiche les routes, certains ouvrages construits par l'homme et les éléments naturels importants comme les rivières. Les libellés des routes et des éléments géographiques sont également visibles.
Mixte
Données de photographies satellite avec l'ajout de cartes routières. Les libellés des routes et des éléments géographiques sont également visibles.
Satellite
Données de photographies satellite. Les libellés des cartes et des éléments géographiques ne sont pas visibles.
Relief (terrain)
Données topographiques. La carte inclut des couleurs, des lignes de contour, des libellés et des ombres pour la perspective. Certaines routes et certains libellés sont également visibles.
Aucune
Aucune tuile. Le rendu de la carte est effectué sous la forme d'une grille vide, sans aucune tuile.

Changer de type de carte

Pour définir le type d'une carte, appelez la méthode GoogleMap de l'objet setMapType(), en indiquant l'une des constantes de type définies dans GoogleMap. Par exemple, pour afficher une carte satellite :

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

Les images ci-dessous montrent une comparaison de cartes de type normal, mixte (hybrid) et relief (terrain) pour un même point géographique :

Comparaison de types de carte

Plans d'intérieur

À un niveau de zoom élevé, la carte affiche les plans d'étage à l'intérieur des bâtiments comme les aéroports, les centres commerciaux, les grands magasins et les arrêts de transports en commun. Ces plans d'étages, appelés plans d'intérieur, sont affichés pour les types de plan "normal" et "satellite" (GoogleMap.MAP_TYPE_NORMAL et GoogleMap.MAP_TYPE_SATELLITE). Ils sont automatiquement activés dès que l'utilisateur effectue un zoom avant, et disparaissent lorsqu'il effectue un zoom arrière sur la carte.

Avis d'obsolescence : Dans une future version, les plans d'intérieur ne seront disponibles que dans le type de carte normal. À partir de cette version, les plans d'intérieur ne seront plus disponibles dans les cartes satellite, terrain et hybrid. Même si les plans d'intérieur ne sont pas disponibles, isIndoorEnabled() continuera de renvoyer la valeur qui a été définie via setIndoorEnabled(), comme c'est le cas actuellement. La valeur par défaut de setIndoorEnabled est true. Consultez les notes de version pour savoir quand les plans d'intérieur ne seront plus pris en charge par ces types de cartes.

Exemple de plan d'intérieur

Utiliser des plans d'intérieur dans l'API

Voici un résumé de la fonctionnalité de plans d'intérieur dans l'API :

  • Vous pouvez désactiver les plans d'intérieur en appelant GoogleMap.setIndoorEnabled(false). Par défaut, les plans d'intérieur sont activés. Les plans d'intérieur s'affichent sur une carte à la fois. Par défaut, il s'agit de la première carte ajoutée à votre application. Si vous préférez afficher des plans d'intérieur sur une autre carte, désactivez-les sur la première carte, puis appelez setIndoorEnabled(true) sur la deuxième carte.
  • Pour désactiver le sélecteur de niveau par défaut, appelez GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Pour en savoir plus, consultez la section Interagir avec la carte.
  • Une interface GoogleMap, OnIndoorStateChangeListener, vous permet de définir un écouteur à appeler dès qu'un nouveau bâtiment entre dans le champ de vision ou qu'un nouveau niveau est activé dans un bâtiment. Pour en savoir plus, consultez la section Interagir avec la carte.
  • GoogleMap.getFocusedBuilding() vous indique le bâtiment qui est actuellement au centre. Vous pouvez alors trouver le niveau actuellement actif en appelant IndoorBuilding.getActiveLevelIndex(). Reportez-vous à la documentation de référence pour consulter toutes les informations disponibles sur les objets IndoorBuilding et IndoorLevel.

Le style de la carte de base n'a pas d'incidence sur les plans d'intérieur.

Ajouter des plans d'étages

Les plans d'intérieur (plans d'étages) sont disponibles pour certains lieux. Si les données de plan d'étage ne sont pas disponibles pour un bâtiment que vous souhaiteriez faire figurer dans votre application, vous pouvez :

Le calque de trafic

Vous pouvez donner à vos utilisateurs la possibilité d'afficher la carte en y superposant des informations sur la densité du trafic. Cela leur permet d'obtenir un aperçu visuel des conditions de circulation locales. Vous pouvez activer ou désactiver le calque de trafic en appelant la méthode setTrafficEnabled(). Pour savoir si le calque de trafic est actuellement activé, appelez la méthode isTrafficEnabled(). L'exemple suivant montre comment le calque de trafic peut apparaître sur une carte.

Carte Google affichant le calque de trafic

Configurer l'état initial

L'API Google Maps vous permet de configurer l'état initial de la carte afin de répondre aux besoins de votre application. Vous pouvez spécifier les points suivants :

  • La position de la caméra, y compris l'emplacement, le niveau de zoom, la direction et l'inclinaison Reportez-vous à la section Caméra et affichage pour plus de détails sur la position de la caméra.
  • Le type de carte
  • L'affichage ou non des boutons de zoom et/ou de la boussole à l'écran
  • Les gestes que l'utilisateur peut utiliser pour manipuler la caméra
  • Si le mode simplifié est activé ou non. Une carte en mode simplifié correspond à une image bitmap de la carte, proposant un sous-ensemble des fonctionnalités fournies par l'API complète.

Vous pouvez configurer l'état initial de la carte soit via XML, si vous avez ajouté la carte au fichier de disposition de votre activité, soit par programmation, si vous avez ajouté la carte de cette façon.

Utilisation des attributs XML

Cette section décrit comment définir l'état initial de la carte si vous avez ajouté une carte à votre application à l'aide d'un fichier de mise en page XML.

L'API Google Maps définit un ensemble de attributs XML personnalisés pour un MapFragment ou un MapView que vous pouvez utiliser pour configurer l'état initial de la carte directement à partir du fichier de mise en page. Les attributs suivants sont actuellement définis :

  • mapType. Il permet de spécifier le type de carte à afficher. Les valeurs autorisées sont les suivantes : none, normal, hybrid, satellite et terrain.
  • cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt. Ces attributs permettent de spécifier la position initiale de la caméra. Cliquez ici pour plus d'informations sur la position de la caméra et ses propriétés.
  • uiZoomControls, uiCompass. Ces attributs permettent d'indiquer si les commandes de zoom et la boussole doivent apparaître ou non sur la carte. Pour plus d'informations, consultez la section UiSettings.
  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures. Ces attributs permettent de spécifier les gestes à activer/désactiver pour l'interaction avec la carte. Pour plus d'informations, consultez la section UiSettings.
  • zOrderOnTop. Cet attribut indique si la surface de la carte doit être placée ou non au-dessus de sa fenêtre. Pour plus d'informations, consultez la section SurfaceView.setZOrderOnTop(boolean). Notez que cela couvre toutes les autres vues qui pourraient apparaître sur la carte (par exemple, les commandes de zoom et le bouton Ma position).
  • useViewLifecycle. Valide uniquement lorsqu'il est accompagné de MapFragment. Cet attribut indique si le cycle de vie de la carte doit être lié à la vue du fragment ou au fragment lui-même. Cliquez ici pour en savoir plus.
  • liteMode. Une valeur true passe la carte en mode simplifié. Une carte en mode simplifié correspond à une image bitmap de la carte, proposant un sous-ensemble des fonctionnalités fournies par l'API complète. La valeur par défaut de cet attribut est false.

Pour utiliser ces attributs personnalisés dans votre fichier de mise en page XML, vous devez d'abord ajouter la déclaration d'espace de noms suivante. Vous pouvez choisir n'importe quel espace de noms. Il n'est pas obligatoire que ce soit map :

xmlns:map="http://schemas.android.com/apk/res-auto"

Vous pouvez ensuite ajouter les attributs comportant le préfixe map: dans vos composants de mise en page, comme vous le feriez avec les attributs Android standards.

L'extrait de code XML suivant montre comment configurer une classe MapFragment avec des options personnalisées. Les mêmes attributs peuvent également être appliqués à une classe MapView.

<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"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

Par programmation

Cette section explique comment définir l'état initial de la carte si vous avez ajouté une carte à votre application en utilisant la programmation.

Si vous avez ajouté un MapFragment (ou MapView) en utilisant la programmation, vous pouvez alors configurer son état initial en indiquant un objet GoogleMapOptions contenant vos options spécifiées. Les options dont vous disposez sont exactement les mêmes que celles disponibles via XML. Vous pouvez créer un objet GoogleMapOptions semblable à celui-ci :

GoogleMapOptions options = new GoogleMapOptions();

Puis le configurer comme suit :

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

Pour appliquer ces options lors de la création d'une carte, procédez de l'une des façons suivantes :

Marge extérieure de carte

Cette vidéo montre un exemple d'ajout d'une marge extérieure à une carte.

Une carte Google est conçue pour remplir toute la zone définie par son élément conteneur, généralement un MapView ou un MapFragment. Plusieurs aspects liés à l'apparence et au comportement de la carte sont définis par les dimensions de son conteneur :

  • La cible de la caméra reflète le centre de la zone remplie.
  • Les commandes de carte sont positionnées par rapport aux bords de la carte.
  • Les informations légales, comme les déclarations de droits d'auteur ou le logo Google apparaissent sur le bord inférieur de la carte.

Vous pouvez ajouter une marge extérieure le long des bords de la carte en utilisant la méthode GoogleMapsetPadding(). La carte continue de remplir la totalité du conteneur, mais le positionnement du texte et des commandes, les gestes sur la carte et les mouvements de caméra s'effectuent comme si l'espace était plus restreint. Cela entraîne les changements suivants :

  • Les mouvements de caméra via les appels d'API ou les actions des boutons (boussole, zoom ou Ma position, par exemple) sont effectués par rapport à la zone délimitée.
  • getCameraPosition() renvoie le centre de la zone délimitée.
  • Projection.getVisibleRegion() renverra la zone délimitée.
  • Les commandes de l'interface utilisateur sont décalées par rapport au bord du conteneur du nombre de pixels indiqué.

L'ajout d'une marge extérieure peut être utile lors de la conception d'interfaces utilisateur qui chevauchent une partie de la carte. Par exemple, dans l'image ci-dessous, la carte présente une marge extérieure sur les bords supérieur et droit. Les commandes et le texte légal visibles de la carte s'affichent alors le long des bords de la zone délimitée, affichée en vert, tandis que la carte continue de remplir l'intégralité du conteneur, affiché en bleu. Dans cet exemple, vous pourriez ajouter un menu sur la partie droite de la carte sans en masquer les commandes.

Marge extérieure de carte

Localiser votre carte

Lorsque vous ajoutez un MapView ou un MapFragment à votre application, les éléments textuels sur la carte s'affichent dans la langue appropriée en fonction des paramètres de l'appareil de l'utilisateur et de son emplacement. Vous pouvez limiter les langues utilisées par votre application à un sous-ensemble de toutes les langues disponibles, en ajoutant un élément resConfigs à votre fichier Gradle. Cela permet de supprimer les langues inutilisées et de réduire la taille binaire de votre application. Exemple :

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

En savoir plus sur la localisation de votre application Android