Native Karten in einer React-Native-App einbinden
Richten Sie expo-maps in React Native ein: Apple Karten und Google Maps, gemeinsame Markierungen, Standortberechtigungen, Kamerasteuerung, Android-Schlüssel und iOS-Limits.
Installieren Sie expo-maps in einem Development Build und rendern Sie anschließend AppleMaps.View unter iOS und GoogleMaps.View unter Android. Beide Komponenten verarbeiten dieselben Kamera-, Marker- und Standortdaten, sodass ein einziger Wrapper beide Plattformen abdeckt.
Die meisten Karten-Tutorials für React Native beziehen sich auf react-native-maps, deren Props sich daher nicht auf die Expo-Bibliothek übertragen lassen. Kopieren Sie ein <MapView>-Snippet in ein expo-maps-Projekt, erhalten Sie bei so gut wie allem Typfehler, einschließlich der Kamera.
Dieser Leitfaden behandelt den gesamten Ablauf mit expo-maps: die Wahl der Bibliothek, das Erstellen der App, das Hinzufügen des Android-API-Schlüssels, das Rendern einer Karte auf beiden Plattformen, das Hinzufügen von Markern, das Zentrieren auf den Standort des Nutzers und die Verarbeitung von Marker-Taps. Außerdem geht er auf die iOS-Versionsgrenzen ein, die bestimmen, welche Funktionen Sie nutzen können. Wenn Sie stattdessen Vektorkacheln und benutzerdefinierte Stile von Mapbox verwenden möchten, lesen Sie Erstellen einer React-Native-Karte mit Mapbox.
Das Wichtigste in Kürze
- expo-maps zeigt Apple Maps unter iOS und Google Maps unter Android über zwei Komponenten an,
AppleMaps.ViewundGoogleMaps.View, und unterstützt Google Maps unter iOS nicht. - Führen Sie expo-maps in einem Development Build aus. Apple Maps benötigt keinen API-Schlüssel, Android hingegen einen Google-Maps-Schlüssel unter
android.config.googleMaps.apiKeyin der app.json, gefolgt von einem Rebuild. cameraPositionlegt nur fest, wo die Karte beginnt. Um die Kamera später zu bewegen, rufen SiesetCameraPositionüber eine Ref auf die Karte auf.- Laut Expo-Dokumentation ist iOS 17 die Mindestversion für expo-maps, und Marker-Tap-Callbacks wie
onMarkerClickerfordern iOS 18.
Sollten Sie expo-maps oder react-native-maps verwenden?
Für ein Expo-Projekt, das bereits Development Builds nutzt, ist expo-maps die richtige Wahl. Greifen Sie zu react-native-maps, wenn Sie Google Maps unter iOS benötigen oder die App in Expo Go ausführen müssen. expo-maps ist die hauseigene Kartenbibliothek von Expo und rendert unter iOS über SwiftUI und unter Android über Jetpack Compose. react-native-maps wird von der Community gepflegt und bietet eine einheitliche MapView-API, die mit mehreren Kartenanbietern funktioniert.
| expo-maps | react-native-maps | |
|---|---|---|
| Entwickelt von | Expo-Team | Community |
| Native Schicht | SwiftUI (iOS), Jetpack Compose (Android) | Eine MapView-Komponente |
| iOS-Anbieter | Nur Apple Maps | Apple Maps oder Google Maps |
| iOS-Mindestversion | iOS 17 laut Expo-Dokumentation; die Paket-README nennt iOS 18.0 | Hier nicht behandelt |
| Expo Go | Development Build verwenden | Laut Expo-Dokumentation in Expo Go enthalten |
| React-Komponenten als Marker | Nicht unterstützt (stattdessen Bild-Marker) | Unterstützt |
| API-Aufbau | Zwei plattformspezifische Komponenten | Eine Komponente |
Zum Launch wurde die Bibliothek in der Ankündigung von expo-maps als Alpha bezeichnet: „With SDK 53, we are releasing our alpha version of expo-maps.“ Die Referenzseite für SDK 58 zeigt keine Statuskennzeichnung. Prüfen Sie vor dem Release den aktuellen Status in der expo-maps-Referenz. Die react-native-maps-Seite von Expo behandelt die Alternative.
expo-maps installieren und einen Development Build erstellen
expo-maps benötigt zwei Dinge: das Paket und ein natives Binary (einen Development Build), das dieses enthält. Installieren Sie das Paket mit der Expo CLI, damit die Version zu Ihrem SDK passt:
npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios # or: npx expo run:android
expo-location liefert im weiteren Verlauf dieses Leitfadens die Koordinaten des Nutzers. expo-dev-client macht das Binary zu einem Development Build. Die expo-maps-Dokumentation beschreibt ausschließlich die Ausführung in einem Development Build, verwenden Sie also einen solchen. Alternativ können Sie mit EAS in der Cloud bauen. Für ein fertiges Projekt startet npx create-expo-app --example with-maps mit bereits installiertem und konfiguriertem expo-maps.
Den Android-API-Schlüssel für Google Maps hinzufügen
Apple Maps funktioniert ohne Schlüssel. Google Maps unter Android benötigt einen Google-Cloud-API-Schlüssel mit aktiviertem Maps SDK for Android, der in der app.json hinterlegt wird; anschließend muss die App neu gebaut werden.
- Erstellen Sie ein Google-Cloud-Projekt und aktivieren Sie das Maps SDK for Android.
- Erstellen Sie einen API-Schlüssel und beschränken Sie ihn auf Android-Apps mit Ihrem Paketnamen und dem SHA-1-Fingerabdruck Ihres Signaturzertifikats. Bei EAS-Builds zeigt
eas credentialsden Fingerabdruck an. - Fügen Sie den Schlüssel und das Plugin für die Standortberechtigung zur app.json hinzu:
{
"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"
}
]
]
}
}
- Bauen Sie die App mit
npx expo run:androidneu. Ein JavaScript-Reload übernimmt Änderungen an der nativen Konfiguration nicht.
In den Plugin-Optionen ist requestLocationPermission ein Boolean, der Berechtigungen in AndroidManifest.xml und Info.plist einträgt, und locationPermission legt die ausschließlich unter iOS verwendete Nutzungsbeschreibung fest. Die app.json kann keine Umgebungsvariablen lesen. Um den Schlüssel aus der Versionskontrolle herauszuhalten, verschieben Sie denselben Pfad android.config.googleMaps.apiKey in die app.config.js und lesen den Schlüssel dort aus process.env.
Eine Karte auf beiden Plattformen anzeigen
expo-maps bietet keine plattformübergreifende Komponente. Schreiben Sie daher einen kleinen Wrapper, der anhand von Platform.OS zwischen AppleMaps.View und GoogleMaps.View wählt und beiden dieselbe cameraPosition übergibt. Eine CameraPosition ist ein Objekt mit coordinates und 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>;
}
Der letzte Zweig behandelt das Web und alle anderen Plattformen, auf denen keine der beiden Komponenten existiert.
Marker aus einem gemeinsamen Daten-Array hinzufügen
Sowohl AppleMaps.View als auch GoogleMaps.View akzeptieren ein markers-Array, und beide Marker-Typen unterstützen id, title und coordinates. Somit kann eine einzige Mapping-Funktion beide Plattformen bedienen. Plattformspezifische Felder wie tintColor unter Apple oder snippet unter Google fügen Sie per Spread-Operator zum gemeinsamen Marker hinzu:
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 kann keine React-Komponenten als Marker rendern. Für benutzerdefinierte Pins unterstützt die Bibliothek Bild-Icons, die mit useImage aus expo-image geladen werden.
Wie zeigen Sie den Standort des Nutzers an und zentrieren die Karte darauf?
Die Anzeige des Nutzerstandorts in expo-maps erfordert drei Schritte: Standortberechtigung anfordern, den Standortpunkt anzeigen, sobald die Berechtigung erteilt wurde, und die Kamera bewegen, wenn die Koordinaten vorliegen. Die Berechtigung muss sowohl im Build deklariert als auch zur Laufzeit angefordert werden, bevor der Punkt erscheinen kann. Der Hook useLocationPermissions aus expo-maps liefert den aktuellen Status sowie eine Funktion zum Anfordern der Berechtigung.
| Aufgabe | AppleMaps.View | GoogleMaps.View |
|---|---|---|
| Standortpunkt | properties.isMyLocationEnabled | properties.isMyLocationEnabled plus userLocation |
| Dem Nutzer folgen | setCameraPosition aufrufen | userLocation.followUserLocation |
| Animationsdauer | Nicht unterstützt | duration in ms |
Aktivieren Sie den Punkt erst, nachdem die Berechtigung erteilt wurde. Ein gemeldetes Android-Problem zeigte, dass das Einschalten von isMyLocationEnabled ohne Berechtigung die App unter Android zum Absturz brachte, während iOS die Einstellung ignorierte. Am 4. November 2026 wurde ein Fix in den Main-Branch von Expo gemergt, ältere expo-maps-Releases enthalten ihn jedoch nicht – die Kopplung des Punkts an die Berechtigung funktioniert dagegen in jeder Version. Das Issue weist zudem darauf hin, dass die Option requestLocationPermission des Config-Plugins die Berechtigungen lediglich zur Build-Zeit deklariert und zur Laufzeit nichts anfordert.
In expo-maps ist die Prop cameraPosition als initiale Kameraposition der Karte dokumentiert. Sie im State zu ändern, ist daher nicht der dokumentierte Weg, um die Kamera zu bewegen. Rufen Sie stattdessen setCameraPosition über eine Ref auf. Unter iOS wird keine Animationsdauer unterstützt, und das zurückgegebene Promise wird aufgelöst, sobald das Kamera-Update eingeplant ist – nicht erst, wenn die Animation abgeschlossen ist.
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 liefert die Koordinaten. Unter Android hält followUserLocation die Kamera auf den Nutzer gerichtet, daher ruft der Code setCameraPosition nur unter iOS auf. Wird die Berechtigung dauerhaft verweigert, bleibt die Karte bei START, und darunter erscheint ein nicht blockierender Hinweis.
Mit onMarkerClick auf Marker-Taps reagieren
Um Marker-Taps in expo-maps zu verarbeiten, übergeben Sie onMarkerClick an AppleMaps.View oder GoogleMaps.View. Der Callback erhält den angetippten Marker, sodass Sie dessen id auslesen und den passenden Datensatz in Ihren Daten finden können. Unter Android funktioniert dies in jeder unterstützten Version. Unter iOS kennzeichnet die Expo-Dokumentation die Funktion mit iOS 18.0+; dieselbe Einschränkung gilt für die übrigen Tap-Callbacks sowie für die programmatische Auswahl mit selectMarker und selectAnnotation.
Auf Geräten mit iOS 17 wird die Karte zwar weiterhin gerendert, ein Tippen auf einen Marker löst in JavaScript jedoch nichts aus. Ist eine Tap-gesteuerte Oberfläche zwingend erforderlich, setzen Sie ios.deploymentTarget über expo-build-properties auf 18.0. Andernfalls ergänzen Sie unterhalb der Karte eine Liste, die denselben Auswahl-State steuert, damit auch Nutzer mit iOS 17 jeden Ort erreichen können.
Fazit
expo-maps deckt den typischen Kartenbildschirm mit nativen Komponenten ab: Apple Maps unter iOS, Google Maps unter Android, ein gemeinsames Daten-Array und eine kurze Platform.OS-Verzweigung. Bauen Sie als Nächstes die App mit Ihrem Android-Schlüssel neu und testen Sie sie auf einem echten iOS-17- und einem iOS-18-Gerät. Genau dort zeigen sich die Unterschiede bei Taps und Berechtigungen. Nach dem Release macht Session Replay für React Native die Probleme sichtbar, die Sie in Logs nicht erkennen – etwa Nutzer, die auf der Suche nach einem Pin auf der Karte umherscrollen, oder die den Standortdialog wegklicken. Die Auswertung dieser Sessions zeigt Ihnen, ob der Karten-Flow für echte Nutzer funktioniert.
FAQs
Warum funktioniert die Google-Karte in der Entwicklung, bleibt aber im Play-Store-Build leer?
In der Regel ist der API-Schlüssel auf den falschen SHA-1-Fingerabdruck beschränkt. Bei der Play App-Signatur signiert Google das Release neu, sodass die installierte App das App-Signaturzertifikat von Google statt Ihres Upload- oder Debug-Schlüssels trägt. Kopieren Sie den SHA-1-Wert des App-Signaturschlüssels von der Seite „App-Integrität“ in der Play Console und fügen Sie ihn den Android-App-Einschränkungen des Schlüssels hinzu. Behalten Sie Ihren Entwicklungs-Fingerabdruck ebenfalls im Schlüssel bei.
Kann expo-maps Routen, Flächen oder Radiuskreise zeichnen?
Ja. Sowohl AppleMaps.View als auch GoogleMaps.View akzeptieren die Props polylines, polygons und circles. Jede Prop erwartet ein Array von Formen, die aus Koordinaten aufgebaut sind; ein Kreis benötigt einen Mittelpunkt und einen Radius in Metern. expo-maps zeichnet Formen, berechnet aber keine Routen. Für eine Fahr- oder Fußgängerroute beziehen Sie die Routengeometrie von einem Routing-Dienst und übergeben die dekodierten Koordinaten als Polyline.
Wie schalte ich expo-maps auf die Satellitenansicht um?
Setzen Sie mapType innerhalb der Prop properties. Verwenden Sie bei AppleMaps.View das Enum AppleMapsMapType: STANDARD, IMAGERY (nur Satellit) oder HYBRID (Satellit mit Straßen und Beschriftungen). Verwenden Sie bei GoogleMaps.View GoogleMapsMapType: NORMAL, SATELLITE, HYBRID oder TERRAIN. Da sich die Wertebezeichnungen je nach Plattform unterscheiden, sollte ein gemeinsamer Wrapper eine einheitliche Einstellung wie 'satellite' unter iOS auf IMAGERY und unter Android auf SATELLITE abbilden.
Gilt eine über expo-maps erteilte Standortberechtigung auch für expo-location?
Ja. Android und iOS erteilen den Standortzugriff der App als Ganzes, nicht einer einzelnen Bibliothek. Sobald der Nutzer den Vordergrund-Dialog des Hooks useLocationPermissions aus expo-maps bestätigt hat, sieht expo-location dieselbe Berechtigung, sodass getCurrentPositionAsync ohne erneute Abfrage ausgeführt wird. Der Standortzugriff im Hintergrund ist auf beiden Plattformen eine separate Berechtigung und muss über expo-location eigens angefordert werden.
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