12k
All articles

Ajouter des cartes natives à une application React Native

Configurez expo-maps dans React Native avec Apple Plans et Google Maps, des marqueurs partagés, les permissions de localisation, la caméra, la clé Android et les limites iOS.

OpenReplay Team
OpenReplay Team
Ajouter des cartes natives à une application React Native

Installez expo-maps dans un build de développement, puis affichez AppleMaps.View sur iOS et GoogleMaps.View sur Android. Les deux composants acceptent les mêmes données de caméra, de marqueurs et de localisation : un seul wrapper suffit donc pour couvrir les deux plateformes.

La plupart des tutoriels React Native consacrés aux cartes sont écrits pour react-native-maps, et leurs props ne s’appliquent pas à la bibliothèque d’Expo. Copiez un extrait <MapView> dans un projet expo-maps et vous obtiendrez des erreurs de typage partout, y compris sur la caméra.

Ce guide couvre l’ensemble du processus avec expo-maps : choisir la bibliothèque, générer l’application, ajouter la clé d’API Android, afficher une carte sur les deux plateformes, ajouter des marqueurs, centrer la carte sur l’utilisateur et gérer les appuis sur les marqueurs. Il aborde également les contraintes de version iOS qui déterminent les fonctionnalités utilisables. Si vous préférez les tuiles vectorielles et les styles personnalisés de Mapbox, consultez créer une carte React Native avec Mapbox.

Points clés à retenir

  • expo-maps affiche Apple Maps sur iOS et Google Maps sur Android au moyen de deux composants, AppleMaps.View et GoogleMaps.View, et ne prend pas en charge Google Maps sur iOS.
  • Exécutez expo-maps dans un build de développement. Apple Maps ne nécessite aucune clé d’API, mais Android requiert une clé Google Maps dans android.config.googleMaps.apiKey du fichier app.json, suivie d’une regénération du build.
  • cameraPosition définit uniquement la position initiale de la carte. Pour déplacer la caméra par la suite, appelez setCameraPosition sur une ref pointant vers la carte.
  • La documentation d’Expo indique iOS 17 comme version minimale pour expo-maps, et les callbacks d’appui sur les marqueurs comme onMarkerClick nécessitent iOS 18.

Faut-il utiliser expo-maps ou react-native-maps ?

Pour un projet Expo qui utilise déjà des builds de développement, choisissez expo-maps. Optez pour react-native-maps si vous avez besoin de Google Maps sur iOS ou si vous devez exécuter l’application dans Expo Go. expo-maps est la bibliothèque de cartographie développée par Expo ; elle s’appuie sur SwiftUI sur iOS et sur Jetpack Compose sur Android. react-native-maps est maintenue par la communauté et propose une API MapView unique compatible avec plusieurs fournisseurs de cartes.

expo-mapsreact-native-maps
Développée parL’équipe ExpoLa communauté
Couche nativeSwiftUI (iOS), Jetpack Compose (Android)Un composant MapView unique
Fournisseur sur iOSApple Maps uniquementApple Maps ou Google Maps
Version iOS minimaleiOS 17 selon la documentation d’Expo ; le README du package indique iOS 18.0Non traité ici
Expo GoUtiliser un build de développementInclus dans Expo Go, selon la documentation d’Expo
Composants React comme marqueursNon pris en charge (marqueurs image à la place)Pris en charge
Forme de l’APIDeux composants spécifiques à chaque plateformeUn seul composant

Lors de son lancement, l’annonce d’expo-maps présentait la bibliothèque comme une version alpha : « Avec le SDK 53, nous publions la version alpha d’expo-maps. » La page de référence du SDK 58 n’affiche aucun statut. Consultez la référence d’expo-maps pour connaître son statut actuel avant la mise en production. La page react-native-maps d’Expo présente l’autre option.

Installer expo-maps et créer un build de développement

expo-maps nécessite deux éléments : le package et un binaire natif (un build de développement) qui l’intègre. Installez le package avec l’Expo CLI afin que sa version corresponde à votre SDK :

npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios      # or: npx expo run:android

expo-location fournira plus loin dans ce guide les coordonnées de l’utilisateur. expo-dev-client transforme le binaire en build de développement. La documentation d’expo-maps décrit uniquement son exécution dans un build de développement : utilisez-en donc un. Vous pouvez également générer le build dans le cloud avec EAS. Pour un projet prêt à l’emploi, npx create-expo-app --example with-maps crée un projet dans lequel expo-maps est déjà installé et configuré.

Ajouter la clé d’API Google Maps pour Android

Apple Maps fonctionne sans clé. Google Maps sur Android nécessite une clé d’API Google Cloud avec le Maps SDK for Android activé, ajoutée au fichier app.json, puis une regénération de l’application.

  1. Créez un projet Google Cloud et activez Maps SDK for Android.
  2. Créez une clé d’API et restreignez-la aux applications Android à l’aide de votre nom de package et de l’empreinte SHA-1 de votre certificat de signature. Pour les builds EAS, la commande eas credentials affiche cette empreinte.
  3. Ajoutez la clé et le plugin d’autorisation de localisation au fichier app.json :
{
  "expo": {
    "android": {
      "package": "com.example.places",
      "config": {
        "googleMaps": { "apiKey": "YOUR_ANDROID_MAPS_KEY" }
      }
    },
    "plugins": [
      [
        "expo-maps",
        {
          "requestLocationPermission": true,
          "locationPermission": "Allow $(PRODUCT_NAME) to show your position on the map"
        }
      ]
    ]
  }
}
  1. Regénérez le build avec npx expo run:android. Un simple rechargement JavaScript ne prend pas en compte les modifications de la configuration native.

Dans les options du plugin, requestLocationPermission est un booléen qui ajoute les autorisations dans AndroidManifest.xml et Info.plist, et locationPermission définit le message d’utilisation propre à iOS. Le fichier app.json ne peut pas lire les variables d’environnement. Pour ne pas versionner la clé dans le contrôle de source, déplacez le même chemin android.config.googleMaps.apiKey dans app.config.js et lisez-y la clé depuis process.env.

Afficher une carte sur les deux plateformes

expo-maps ne propose pas de composant multiplateforme : écrivez donc un petit wrapper qui choisit AppleMaps.View ou GoogleMaps.View en fonction de Platform.OS et transmet aux deux la même cameraPosition. Un CameraPosition est un objet contenant coordinates et zoom :

import { Platform, Text } from 'react-native';
import { AppleMaps, GoogleMaps } from 'expo-maps';

const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };

export function BasicMap() {
  if (Platform.OS === 'ios') return <AppleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
  if (Platform.OS === 'android') return <GoogleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
  return <Text>Maps are only available on Android and iOS.</Text>;
}

La dernière branche gère le web et toute autre plateforme, sur lesquels aucun des deux composants n’existe.

Ajouter des marqueurs à partir d’un seul tableau de données

AppleMaps.View et GoogleMaps.View acceptent tous deux un tableau markers, et les deux types de marqueurs acceptent id, title et coordinates. Une seule fonction de transformation peut donc alimenter les deux plateformes. Ajoutez les champs propres à chaque plateforme, comme tintColor sur Apple ou snippet sur Google, en les décomposant (spread) sur le marqueur commun :

type Place = { id: string; title: string; latitude: number; longitude: number };

export const PLACES: Place[] = [
  { id: 'office', title: 'Office', latitude: 51.5154, longitude: -0.141 },
  { id: 'cafe', title: 'Cafe', latitude: 51.5113, longitude: -0.1198 },
];

export const toMarker = (p: Place) => ({
  id: p.id,
  title: p.title,
  coordinates: { latitude: p.latitude, longitude: p.longitude },
});

// iOS:     markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
// Android: markers={PLACES.map((p) => ({ ...toMarker(p), snippet: 'Open now' }))}

expo-maps ne peut pas afficher de composants React en tant que marqueurs. Pour des épingles personnalisées, la bibliothèque prend en charge des icônes image chargées avec useImage d’expo-image.

Comment afficher la position de l’utilisateur et centrer la carte dessus ?

Afficher la position de l’utilisateur avec expo-maps se fait en trois étapes : demander l’autorisation de localisation, afficher le point de localisation une fois l’autorisation accordée, puis déplacer la caméra lorsque les coordonnées sont disponibles. L’autorisation doit être à la fois déclarée dans le build et demandée à l’exécution pour que le point puisse apparaître. Le hook useLocationPermissions d’expo-maps renvoie le statut actuel ainsi qu’une fonction permettant de demander l’autorisation.

TâcheAppleMaps.ViewGoogleMaps.View
Point de localisationproperties.isMyLocationEnabledproperties.isMyLocationEnabled plus userLocation
Suivre l’utilisateurAppeler setCameraPositionuserLocation.followUserLocation
Durée d’animationNon prise en chargeduration en ms

N’activez le point de localisation qu’une fois l’autorisation accordée. Un problème signalé sur Android a montré qu’activer isMyLocationEnabled sans autorisation faisait planter l’application sur Android, alors qu’iOS l’ignorait. Un correctif a été fusionné dans la branche principale d’Expo le 4 novembre 2026, mais les versions plus anciennes d’expo-maps ne l’intègrent pas, et conditionner l’affichage du point à l’autorisation fonctionne quelle que soit la version. Ce ticket souligne également que l’option requestLocationPermission du plugin de configuration se contente de déclarer les autorisations au moment du build et ne demande rien à l’exécution.

Dans expo-maps, la prop cameraPosition est documentée comme la position initiale de la caméra : la modifier via le state n’est donc pas la méthode documentée pour déplacer la caméra. Appelez plutôt setCameraPosition sur une ref. Sur iOS, la durée d’animation n’est pas prise en charge, et la promesse renvoyée est résolue dès que la mise à jour de la caméra est planifiée, et non à la fin de son animation.

import { useEffect, useRef, useState, type ComponentRef } from 'react';
import { Platform, Text, View } from 'react-native';
import { AppleMaps, GoogleMaps, useLocationPermissions } from 'expo-maps';
import * as Location from 'expo-location';
import { PLACES, toMarker } from './places';

const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
type Coords = { latitude: number; longitude: number };

export function PlacesMap({ onSelect }: { onSelect: (id: string) => void }) {
  const appleRef = useRef<ComponentRef<typeof AppleMaps.View>>(null);
  const [permission, requestPermission] = useLocationPermissions();
  const [me, setMe] = useState<Coords | null>(null);
  const granted = !!permission?.granted;

  useEffect(() => {
    if (permission && !permission.granted && permission.canAskAgain) requestPermission();
  }, [permission]);

  useEffect(() => {
    if (!granted) return;
    Location.getCurrentPositionAsync().then(({ coords }) => {
      const here = { latitude: coords.latitude, longitude: coords.longitude };
      setMe(here);
      appleRef.current?.setCameraPosition({ coordinates: here, zoom: 14 }); // iOS only; no duration
    });
  }, [granted]);

  const handleMarker = (m: { id?: string }) => m.id && onSelect(m.id);
  const denied = permission && !permission.granted && !permission.canAskAgain;

  const map =
    Platform.OS === 'ios' ? (
      <AppleMaps.View
        ref={appleRef}
        style={{ flex: 1 }}
        cameraPosition={START}
        markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
        properties={{ isMyLocationEnabled: granted }}
        onMarkerClick={handleMarker} // iOS 18+
      />
    ) : Platform.OS === 'android' ? (
      <GoogleMaps.View
        style={{ flex: 1 }}
        cameraPosition={START}
        markers={PLACES.map(toMarker)}
        properties={{ isMyLocationEnabled: granted }}
        userLocation={me ? { coordinates: me, followUserLocation: true } : undefined}
        onMarkerClick={handleMarker}
      />
    ) : (
      <Text>Maps are only available on Android and iOS.</Text>
    );

  return (
    <View style={{ flex: 1 }}>
      {map}
      {denied && <Text>Location is off. Enable it in Settings to see where you are.</Text>}
    </View>
  );
}

Location.getCurrentPositionAsync fournit les coordonnées. Sur Android, followUserLocation maintient la caméra sur l’utilisateur ; le code n’appelle donc setCameraPosition que sur iOS. Si l’autorisation est refusée définitivement, la carte reste positionnée sur START et un message non bloquant s’affiche en dessous.

Réagir aux appuis sur les marqueurs avec onMarkerClick

Pour gérer les appuis sur les marqueurs dans expo-maps, transmettez onMarkerClick à AppleMaps.View ou à GoogleMaps.View. Le callback reçoit le marqueur touché : vous pouvez ainsi lire son id et retrouver l’enregistrement correspondant dans vos données. Sur Android, il fonctionne sur toutes les versions prises en charge. Sur iOS, la documentation d’Expo l’indique comme iOS 18.0+, et cette même limite s’applique aux autres callbacks d’appui ainsi qu’à la sélection programmatique via selectMarker et selectAnnotation.

Sur les appareils sous iOS 17, la carte s’affiche toujours, mais un appui sur un marqueur ne déclenche rien côté JavaScript. Si votre interface dépend des appuis, définissez ios.deploymentTarget sur 18.0 via expo-build-properties. Sinon, ajoutez sous la carte une liste qui pilote le même état de sélection, afin que les utilisateurs d’iOS 17 puissent tout de même accéder à chaque lieu.

Conclusion

expo-maps couvre l’écran de carte classique avec des composants natifs : Apple Maps sur iOS, Google Maps sur Android, un seul tableau de données partagé et une courte condition sur Platform.OS. Prochaine étape : regénérez le build avec votre clé Android et testez sur un véritable appareil sous iOS 17 et sur un appareil sous iOS 18. C’est là que les différences liées aux appuis et aux autorisations se manifestent. Après la mise en production, le session replay pour React Native révèle les problèmes invisibles dans les logs, comme des utilisateurs qui déplacent la carte dans tous les sens à la recherche d’une épingle ou qui ferment la demande d’autorisation de localisation. Observer ces sessions vous indique si le parcours cartographique fonctionne réellement pour vos utilisateurs.

FAQ

Pourquoi la carte Google fonctionne-t-elle en développement mais reste-t-elle vide dans le build publié sur le Play Store ?

La clé d'API est généralement restreinte à la mauvaise empreinte SHA-1. Avec la signature d'application par Google Play (Play App Signing), Google signe à nouveau la version publiée : l'application installée porte donc le certificat de signature d'application de Google, et non votre clé d'importation ou de débogage. Copiez l'empreinte SHA-1 de signature d'application depuis la page Intégrité de l'application de la Play Console et ajoutez-la aux restrictions d'application Android de la clé. Conservez également votre empreinte de développement sur la clé.

expo-maps peut-il tracer des itinéraires, des zones ou des cercles de rayon ?

Oui. AppleMaps.View et GoogleMaps.View acceptent tous deux les props polylines, polygons et circles. Chaque prop reçoit un tableau de formes construites à partir de coordonnées, et un cercle prend un centre et un rayon en mètres. expo-maps dessine les formes mais ne calcule pas d'itinéraires. Pour un trajet en voiture ou à pied, récupérez la géométrie de l'itinéraire auprès d'un service de directions et transmettez les coordonnées décodées sous forme de polyline.

Comment passer expo-maps en vue satellite ?

Définissez mapType dans la prop properties. Sur AppleMaps.View, utilisez l'enum AppleMapsMapType : STANDARD, IMAGERY (satellite uniquement) ou HYBRID (satellite avec routes et libellés). Sur GoogleMaps.View, utilisez GoogleMapsMapType : NORMAL, SATELLITE, HYBRID ou TERRAIN. Les noms de valeurs diffèrent selon la plateforme : un wrapper commun doit donc faire correspondre un même réglage, par exemple 'satellite', à IMAGERY sur iOS et à SATELLITE sur Android.

L'autorisation de localisation accordée via expo-maps s'applique-t-elle aussi à expo-location ?

Oui. Android et iOS accordent l'accès à la localisation à l'application dans son ensemble, et non à une bibliothèque en particulier. Dès que l'utilisateur accepte la demande d'autorisation au premier plan émise par le hook useLocationPermissions d'expo-maps, expo-location voit la même autorisation : getCurrentPositionAsync s'exécute donc sans seconde demande. La localisation en arrière-plan fait l'objet d'une autorisation distincte sur les deux plateformes et nécessite sa propre demande via expo-location.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.