12k
All articles

在 React Native 应用中添加原生地图

在 React Native 中配置 expo-maps,使用 Apple 地图和 Google 地图、共享标记、位置权限与相机控制,并了解 Android 密钥和 iOS 版本限制。

OpenReplay Team
OpenReplay Team
在 React Native 应用中添加原生地图

在开发构建(development build)中安装 expo-maps,然后在 iOS 上渲染 AppleMaps.View,在 Android 上渲染 GoogleMaps.View。这两个组件接收相同的相机、标记和位置数据,因此一个封装组件即可覆盖两个平台。

大多数 React Native 地图教程都是基于 react-native-maps 编写的,其 props 无法直接沿用到 Expo 的库中。如果把一段 <MapView> 代码直接复制到 expo-maps 项目里,从相机设置到其他所有属性都会报类型错误。

本指南完整介绍 expo-maps 的使用流程:选择地图库、构建应用、添加 Android API 密钥、在两个平台上渲染地图、添加标记、将地图居中到用户位置以及处理标记点击。同时还会说明 iOS 版本限制,这些限制决定了你能使用哪些功能。如果你需要 Mapbox 提供的矢量瓦片和自定义样式,请参阅使用 Mapbox 创建 React Native 地图。

核心要点

  • expo-maps 通过 AppleMaps.View 和 GoogleMaps.View 两个组件,分别在 iOS 上显示 Apple 地图、在 Android 上显示 Google 地图,不支持在 iOS 上使用 Google 地图。
  • 需在开发构建中运行 expo-maps。Apple 地图无需 API 密钥,但 Android 需要在 app.json 的 android.config.googleMaps.apiKey 中配置 Google Maps 密钥,然后重新构建。
  • cameraPosition 仅设置地图的初始位置。如需之后移动相机,请通过地图的 ref 调用 setCameraPosition。
  • Expo 文档列出 expo-maps 的最低版本要求为 iOS 17,而 onMarkerClick 等标记点击回调需要 iOS 18。

应该使用 expo-maps 还是 react-native-maps?

如果你的 Expo 项目已经在使用开发构建,请选择 expo-maps。如果你需要在 iOS 上使用 Google 地图,或需要在 Expo Go 中运行,请选择 react-native-maps。expo-maps 是 Expo 官方的地图库,在 iOS 上通过 SwiftUI 渲染,在 Android 上通过 Jetpack Compose 渲染。react-native-maps 由社区维护,提供一套统一的 MapView API,可对接多种地图服务商。

expo-mapsreact-native-maps
开发方Expo 团队社区
原生层SwiftUI(iOS)、Jetpack Compose(Android)单一 MapView 组件
iOS 地图服务商仅 Apple 地图Apple 地图或 Google 地图
iOS 最低版本Expo 文档为 iOS 17;包的 README 标注为 iOS 18.0本文不涉及
Expo Go需使用开发构建根据 Expo 文档,已内置于 Expo Go
使用 React 组件作为标记不支持(改用图片标记)支持
API 形式两个平台专属组件单一组件

在发布之初,expo-maps 的公告将该库定位为 alpha 版本:“随 SDK 53 一同,我们发布了 expo-maps 的 alpha 版本。”而 SDK 58 的参考页面并未显示任何状态标签。上线前请查阅 expo-maps 参考文档确认其当前状态。另一种方案可参阅 Expo 的 react-native-maps 页面。

安装 expo-maps 并创建开发构建

expo-maps 需要两样东西:npm 包,以及包含该包的原生二进制文件(即开发构建)。请使用 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 会将二进制文件变为开发构建。expo-maps 文档只介绍了在开发构建中运行的方式,因此请使用开发构建。你也可以通过 EAS 进行云端构建。如需开箱即用的项目,可运行 npx create-expo-app --example with-maps,该项目已预先安装并配置好 expo-maps。

添加 Android Google Maps API 密钥

Apple 地图无需密钥即可使用。Android 上的 Google 地图则需要一个启用了 Maps SDK for Android 的 Google Cloud API 密钥,将其添加到 app.json 后还需重新构建应用。

  1. 创建 Google Cloud 项目并启用 Maps SDK for Android。
  2. 创建 API 密钥,并使用你的包名和签名证书的 SHA-1 指纹将其限制为仅供 Android 应用使用。对于 EAS 构建,可通过 eas credentials 查看指纹。
  3. 在 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. 运行 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 没有跨平台组件,因此需要编写一个小型封装组件,根据 Platform.OS 选择 AppleMaps.View 或 GoogleMaps.View,并为两者传入相同的 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>;
}

最后一个分支用于处理 Web 及其他平台,这些平台上两个组件都不存在。

基于同一数据数组添加标记

AppleMaps.View 和 GoogleMaps.View 都接收 markers 数组,且两种标记类型都支持 id、title 和 coordinates。这意味着一个映射函数即可同时为两个平台提供数据。对于平台专属字段,例如 Apple 的 tintColor 或 Google 的 snippet,可通过展开运算符将其合并到共享标记上:

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 组件渲染为标记。如需自定义图钉,它支持使用 expo-image 的 useImage 加载图片图标。

如何显示用户位置并将地图居中?

在 expo-maps 中显示用户位置需要三个步骤:请求位置权限、在获得授权后显示定位圆点,以及在获取到坐标后移动相机。定位圆点要显示出来,权限必须既在构建时声明,又在运行时请求。expo-maps 提供的 useLocationPermissions hook 会返回当前权限状态以及一个用于请求权限的函数。

任务AppleMaps.ViewGoogleMaps.View
定位圆点properties.isMyLocationEnabledproperties.isMyLocationEnabled 加 userLocation
跟随用户调用 setCameraPositionuserLocation.followUserLocation
动画时长不支持duration(毫秒)

请仅在获得授权后再启用定位圆点。一个已报告的 Android 问题显示,在未获得权限的情况下开启 isMyLocationEnabled 会导致 Android 应用崩溃,而 iOS 则会直接忽略该设置。相关修复已于 2026 年 11 月 4 日合并到 Expo 的主分支,但较早版本的 expo-maps 并不包含此修复,而基于权限状态控制定位圆点的做法适用于所有版本。该 issue 还指出,配置插件的 requestLocationPermission 选项只会在构建时声明权限,而不会在运行时发起任何请求。

在 expo-maps 中,cameraPosition prop 的文档定义是地图的初始相机位置,因此通过修改 state 来改变它并不是官方文档推荐的移动相机方式。请改为通过 ref 调用 setCameraPosition。在 iOS 上不支持设置动画时长,且返回的 Promise 会在相机更新被调度后即 resolve,而不是在动画完成时。

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 会让相机始终跟随用户,因此代码只在 iOS 上调用 setCameraPosition。如果权限被永久拒绝,地图将停留在 START 位置,并在下方显示一条不阻断操作的提示信息。

使用 onMarkerClick 响应标记点击

要在 expo-maps 中处理标记点击,请向 AppleMaps.View 或 GoogleMaps.View 传入 onMarkerClick。该回调会接收被点击的标记,因此你可以读取其 id 并在数据中查找对应的记录。在 Android 上,它适用于所有受支持的版本。在 iOS 上,Expo 文档将其标注为 iOS 18.0+,同样的限制也适用于其他点击回调,以及通过 selectMarker 和 selectAnnotation 进行的编程式选中。

在 iOS 17 设备上,地图仍可正常渲染,但点击标记不会在 JavaScript 中触发任何响应。如果你的 UI 必须依赖点击交互,可通过 expo-build-properties 将 ios.deploymentTarget 设置为 18.0。否则,可在地图下方添加一个列表来驱动相同的选中状态,让 iOS 17 用户也能访问每个地点。

总结

expo-maps 能以原生组件满足常见的地图页面需求:iOS 上使用 Apple 地图,Android 上使用 Google 地图,共享同一个数据数组,只需一小段 Platform.OS 分支判断。下一步,请使用你的 Android 密钥重新构建,并分别在真实的 iOS 17 和 iOS 18 设备上进行测试,点击和权限方面的差异正是在这些设备上显现出来的。应用上线后,React Native 会话回放可以帮你发现日志中看不到的问题,例如用户来回拖动地图寻找图钉,或直接关闭了位置权限弹窗。观察这些会话,你就能判断地图流程对真实用户是否行之有效。

常见问题

为什么 Google 地图在开发环境中正常,但在 Play 商店版本中却是一片空白?

这通常是因为 API 密钥被限制到了错误的 SHA-1 指纹。启用 Play 应用签名后,Google 会对发布版本重新签名,因此用户安装的应用使用的是 Google 的应用签名证书,而不是你的上传密钥或调试密钥。请在 Play 管理中心的“应用完整性”页面复制应用签名 SHA-1,并将其添加到该密钥的 Android 应用限制中。同时请保留密钥上的开发环境指纹。

expo-maps 能否绘制路线、区域或半径圆?

可以。AppleMaps.View 和 GoogleMaps.View 都支持 polylines、polygons 和 circles 这三个 props。每个 prop 接收一个由坐标构成的图形数组,圆形则需要提供圆心和以米为单位的半径。expo-maps 只负责绘制图形,不负责计算路线。如需驾车或步行路径,请从路线规划服务获取路线几何数据,并将解码后的坐标作为 polyline 传入。

如何将 expo-maps 切换为卫星视图?

在 properties prop 中设置 mapType。在 AppleMaps.View 上,使用 AppleMapsMapType 枚举:STANDARD、IMAGERY(仅卫星图)或 HYBRID(卫星图叠加道路和标注)。在 GoogleMaps.View 上,使用 GoogleMapsMapType:NORMAL、SATELLITE、HYBRID 或 TERRAIN。由于两个平台的取值名称不同,共享的封装组件应将统一的设置(例如 'satellite')在 iOS 上映射为 IMAGERY,在 Android 上映射为 SATELLITE。

通过 expo-maps 获得的位置权限是否同样适用于 expo-location?

是的。Android 和 iOS 是将位置权限授予整个应用,而不是授予某个单独的库。一旦用户在 expo-maps 的 useLocationPermissions hook 弹出的前台权限提示中同意授权,expo-location 也能获得相同的权限,因此 getCurrentPositionAsync 运行时不会再次弹出提示。后台定位在两个平台上都是单独的授权,需要通过 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.