Добавление нативных карт в приложение React Native
Настройте expo-maps в React Native: Apple Maps и Google Maps, общие маркеры, разрешения геолокации, управление камерой, ключ Android и ограничения iOS.
Установите expo-maps в development build, а затем рендерите AppleMaps.View на iOS и GoogleMaps.View на Android. Оба компонента принимают одинаковые данные о камере, маркерах и местоположении, поэтому одна обёртка покрывает обе платформы.
Большинство руководств по картам для React Native написаны для react-native-maps, и их пропсы не подходят для библиотеки Expo. Скопируйте фрагмент с <MapView> в проект на expo-maps, и вы получите ошибки типов буквально на всём, включая камеру.
В этом руководстве описан весь процесс работы с expo-maps: выбор библиотеки, сборка приложения, добавление API-ключа для Android, отображение карты на обеих платформах, добавление маркеров, центрирование карты на пользователе и обработка нажатий на маркеры. Также рассмотрены ограничения по версиям iOS, от которых зависит, какие возможности вам доступны. Если вместо этого вам нужны векторные тайлы и пользовательские стили от Mapbox, см. статью создание карты в React Native с помощью Mapbox.
Ключевые выводы
- expo-maps отображает Apple Maps на iOS и Google Maps на Android через два компонента —
AppleMaps.ViewиGoogleMaps.View— и не поддерживает Google Maps на iOS. - Запускайте expo-maps в development build. Apple Maps не требует API-ключа, а для Android нужен ключ Google Maps в
android.config.googleMaps.apiKeyв app.json с последующей пересборкой. cameraPositionзадаёт только начальное положение карты. Чтобы переместить камеру позже, вызовитеsetCameraPositionчерез ref на карту.- В документации Expo минимальной версией для expo-maps указана iOS 17, а колбэки нажатий на маркеры, такие как
onMarkerClick, требуют iOS 18.
Что выбрать: expo-maps или react-native-maps?
Для проекта на Expo, который уже использует development builds, выбирайте expo-maps. Выбирайте react-native-maps, если вам нужны Google Maps на iOS или запуск в Expo Go. expo-maps — собственная библиотека карт от Expo, которая рендерит карты через SwiftUI на iOS и Jetpack Compose на Android. react-native-maps поддерживается сообществом и предоставляет единый API MapView, работающий с несколькими провайдерами карт.
| expo-maps | react-native-maps | |
|---|---|---|
| Разработчик | Команда Expo | Сообщество |
| Нативный слой | SwiftUI (iOS), Jetpack Compose (Android) | Единый компонент MapView |
| Провайдер на iOS | Только Apple Maps | Apple Maps или Google Maps |
| Минимальная версия iOS | iOS 17 согласно документации Expo; в README пакета указана iOS 18.0 | Здесь не рассматривается |
| Expo Go | Используйте development build | Входит в Expo Go согласно документации Expo |
| React-компоненты в качестве маркеров | Не поддерживаются (вместо них — маркеры-изображения) | Поддерживаются |
| Структура API | Два платформенных компонента | Один компонент |
На момент выхода в анонсе expo-maps библиотека была описана как альфа-версия: «With SDK 53, we are releasing our alpha version of expo-maps» («Вместе с SDK 53 мы выпускаем альфа-версию expo-maps»). На справочной странице для SDK 58 метка статуса отсутствует. Перед релизом проверьте актуальный статус в справочнике по expo-maps. Альтернативный вариант описан на странице react-native-maps в документации Expo.
Установка expo-maps и создание development build
Для работы expo-maps нужны две вещи: сам пакет и нативный бинарник (development build), который его включает. Устанавливайте пакет через Expo CLI, чтобы версия соответствовала вашему SDK:
npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios # or: npx expo run:android
expo-location будет использоваться далее в руководстве для получения координат пользователя. expo-dev-client превращает бинарник в development build. Документация expo-maps описывает запуск только в development build, поэтому используйте именно его. Собрать приложение также можно в облаке с помощью EAS. Для готового проекта выполните npx create-expo-app --example with-maps — в нём expo-maps уже установлен и настроен.
Добавление API-ключа Google Maps для Android
Apple Maps работает без ключа. Для Google Maps на Android нужен API-ключ Google Cloud с включённым Maps SDK for Android, добавленный в app.json, после чего приложение необходимо пересобрать.
- Создайте проект в Google Cloud и включите Maps SDK for Android.
- Создайте API-ключ и ограничьте его использование Android-приложениями по имени пакета и SHA-1-отпечатку вашего сертификата подписи. Для сборок EAS отпечаток можно посмотреть командой
eas credentials. - Добавьте ключ и плагин разрешений на геолокацию в 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"
}
]
]
}
}
- Пересоберите приложение командой
npx expo run:android. Перезагрузка JavaScript не подхватывает изменения в нативной конфигурации.
В параметрах плагина requestLocationPermission — булево значение, которое добавляет разрешения в AndroidManifest.xml и Info.plist, а locationPermission задаёт текст запроса разрешения, используемый только на iOS. app.json не умеет читать переменные окружения. Чтобы не хранить ключ в системе контроля версий, перенесите тот же путь android.config.googleMaps.apiKey в app.config.js и считывайте ключ там из process.env.
Отображение карты на обеих платформах
В expo-maps нет кроссплатформенного компонента, поэтому напишите небольшую обёртку, которая выбирает AppleMaps.View или GoogleMaps.View в зависимости от Platform.OS и передаёт обоим одинаковый cameraPosition. CameraPosition — это объект с полями coordinates и 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>;
}
Последняя ветка обрабатывает веб и любые другие платформы, где ни один из компонентов не существует.
Добавление маркеров из единого массива данных
И AppleMaps.View, и GoogleMaps.View принимают массив markers, а оба типа маркеров поддерживают поля id, title и coordinates. Это значит, что одна функция преобразования может обслуживать обе платформы. Платформенно-специфичные поля — например, tintColor для Apple или snippet для Google — добавляйте, разворачивая (spread) их поверх общего маркера:
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 не умеет рендерить React-компоненты в качестве маркеров. Для пользовательских пинов поддерживаются иконки-изображения, загруженные с помощью useImage из expo-image.
Как показать местоположение пользователя и отцентрировать на нём карту?
Отображение местоположения пользователя в expo-maps состоит из трёх шагов: запросить разрешение на геолокацию, показать точку местоположения после получения разрешения и переместить камеру, когда придут координаты. Чтобы точка появилась, разрешение должно быть как объявлено в сборке, так и запрошено во время выполнения. Хук useLocationPermissions из expo-maps возвращает текущий статус и функцию для запроса разрешения.
| Задача | AppleMaps.View | GoogleMaps.View |
|---|---|---|
| Точка местоположения | properties.isMyLocationEnabled | properties.isMyLocationEnabled плюс userLocation |
| Следование за пользователем | Вызов setCameraPosition | userLocation.followUserLocation |
| Длительность анимации | Не поддерживается | duration в мс |
Включайте точку только после получения разрешения. В задокументированной проблеме на Android было показано, что включение isMyLocationEnabled без разрешения приводило к падению приложения на Android, тогда как iOS это просто игнорировала. Исправление было влито в основную ветку Expo 4 ноября 2026 года, но в более старых релизах expo-maps его нет, а привязка точки к наличию разрешения работает в любой версии. В том же обсуждении отмечается, что параметр requestLocationPermission в config-плагине лишь объявляет разрешения на этапе сборки и ничего не запрашивает во время выполнения.
В expo-maps проп cameraPosition задокументирован как начальное положение камеры, поэтому изменение его через состояние не является документированным способом перемещения камеры. Вместо этого вызывайте setCameraPosition через ref. На iOS длительность анимации не поддерживается, а возвращаемый промис разрешается после того, как обновление камеры запланировано, а не после завершения анимации.
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. На Android followUserLocation удерживает камеру на пользователе, поэтому код вызывает setCameraPosition только на iOS. Если в разрешении отказано окончательно, карта остаётся в позиции START, а под ней появляется неблокирующее сообщение.
Обработка нажатий на маркеры с помощью onMarkerClick
Чтобы обрабатывать нажатия на маркеры в expo-maps, передайте onMarkerClick в AppleMaps.View или GoogleMaps.View. Колбэк получает маркер, на который нажали, поэтому можно прочитать его id и найти соответствующую запись в данных. На Android это работает во всех поддерживаемых версиях. На iOS в документации Expo колбэк помечен как iOS 18.0+, и то же ограничение распространяется на другие колбэки нажатий и на программный выбор с помощью selectMarker и selectAnnotation.
На устройствах с iOS 17 карта по-прежнему отображается, но нажатие на маркер никак не отражается в JavaScript. Если интерфейс, управляемый нажатиями, обязателен, установите ios.deploymentTarget равным 18.0 через expo-build-properties. В противном случае добавьте под картой список, который управляет тем же состоянием выбора, чтобы пользователи iOS 17 тоже могли перейти к каждому месту.
Заключение
expo-maps покрывает типичный экран с картой с помощью нативных компонентов: Apple Maps на iOS, Google Maps на Android, один общий массив данных и короткое ветвление по Platform.OS. Следующий шаг — пересобрать приложение с ключом для Android и протестировать его на реальных устройствах с iOS 17 и iOS 18. Именно там проявляются различия в обработке нажатий и разрешений. После релиза session replay для React Native покажет сбои, которые не видны в логах, — например, когда пользователи двигают карту в поисках пина или закрывают запрос на доступ к геолокации. Просмотр таких сессий покажет, работает ли сценарий с картой для реальных пользователей.
Часто задаваемые вопросы
Почему карта Google работает при разработке, но остаётся пустой в сборке из Play Store?
Обычно API-ключ ограничен не тем SHA-1-отпечатком. При использовании Play App Signing Google повторно подписывает релиз, поэтому установленное приложение несёт сертификат подписи приложения от Google, а не ваш ключ загрузки или отладочный ключ. Скопируйте SHA-1 сертификата подписи приложения со страницы App integrity в Play Console и добавьте его в ограничения ключа для Android-приложений. Отпечаток для разработки на ключе тоже оставьте.
Может ли expo-maps рисовать маршруты, области или окружности заданного радиуса?
Да. И AppleMaps.View, и GoogleMaps.View принимают пропсы polylines, polygons и circles. Каждый проп принимает массив фигур, построенных из координат, а окружность задаётся центром и радиусом в метрах. expo-maps рисует фигуры, но не рассчитывает маршруты. Для автомобильного или пешеходного маршрута получите геометрию маршрута из сервиса построения маршрутов и передайте декодированные координаты в виде polyline.
Как переключить expo-maps в режим спутниковой карты?
Задайте mapType внутри пропа properties. В AppleMaps.View используйте перечисление AppleMapsMapType: STANDARD, IMAGERY (только спутниковый снимок) или HYBRID (спутниковый снимок с дорогами и подписями). В GoogleMaps.View используйте GoogleMapsMapType: NORMAL, SATELLITE, HYBRID или TERRAIN. Названия значений различаются в зависимости от платформы, поэтому общая обёртка должна сопоставлять одну настройку, например 'satellite', с IMAGERY на iOS и SATELLITE на Android.
Распространяется ли разрешение на геолокацию, полученное через expo-maps, на expo-location?
Да. Android и iOS предоставляют доступ к геолокации приложению в целом, а не отдельной библиотеке. После того как пользователь примет запрос на доступ в активном режиме из хука useLocationPermissions в expo-maps, expo-location видит то же разрешение, поэтому getCurrentPositionAsync выполняется без повторного запроса. Фоновый доступ к геолокации на обеих платформах предоставляется отдельно и требует собственного запроса через expo-location.
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