This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 地图
一个在 Android 上提供对 Google Maps、在 iOS 上提供对 Apple Maps 访问的库。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
使用 expo-maps 库将 Google Maps 和 Apple Maps 添加到你的 Expo 应用中。
配置
Expo Maps 提供对 Android 和 iOS 平台原生地图 API 的访问。
- Apple Maps（仅在 iOS上可用）。安装此包后无需额外配置即可使用。
- Google Maps（仅在 Android上可用）。虽然 Google 为 iOS 提供了 Google Maps SDK，但 Expo Maps 仅在 Android 上支持它。如果你想在 iOS 上使用 Google Maps，可以考虑使用 替代库 或 自行编写。
Google Cloud API 设置
在 Android 上使用 Google Maps 之前，你需要注册一个 Google Cloud API 项目，启用 Android 版 Maps SDK，并将相关配置添加到你的 Expo 项目中。
在 Android 上设置 Google Maps
如果你已经为 Android 上的其他 Google 服务（例如 Google 登录）注册了项目，那么只需在你的项目中启用 Android 版 Maps SDK，然后跳到第 4 步。
1
注册一个 Google Cloud API 项目并启用 Android 版 Maps SDK
- 在浏览器中打开 Google API 管理器 并创建一个项目。
- 项目创建完成后，进入该项目并启用 Android 版 Maps SDK。
2
复制你应用的 SHA-1 证书指纹
- 如果你要将应用发布到 Google Play 商店，你至少需要先 将应用二进制文件上传到 Google Play 控制台。这是 Google 生成应用签名凭据所必需的。
- 前往 Google Play 控制台 >（你的应用）> 发布 > 设置 > 应用完整性 > 应用签名。
- 复制 SHA-1 证书指纹 的值。
3
创建一个 API 密钥
- 前往 Google Cloud 凭据管理器 并点击 创建凭据，然后选择 API 密钥。
- 在弹窗中点击 编辑 API 密钥。
- 在 密钥限制 > 应用限制 下，选择 Android 应用。
- 在 将使用限制为你的 Android 应用 下，点击 添加项目。
- 将你在 app.json 中的
android.package（例如：com.company.myapp）添加到包名字段。 - 然后，添加第 2 步中 SHA-1 证书指纹 的值。
- 点击 完成，然后点击 保存。
4
将 API 密钥添加到你的项目中
- 将你的 API 密钥 复制到 app.json 中的
android.config.googleMaps.apiKey字段下。 - 创建一个新的开发构建，现在你就可以在 Android 上使用
expo-maps的 Google Maps API 了。
权限
要在地图上显示用户的位置，你需要提前声明并请求位置权限。如果你在项目中使用 config plugins（Continuous Native Generation (CNG)），可以通过其内置的 config plugin 进行配置。该插件允许你配置一些无法在运行时设置、且需要重新构建新的应用二进制文件才能生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。
Example app.json with config plugin
Configurable properties
用法
import { AppleMaps, GoogleMaps } from 'expo-maps'; import { Platform, Text } from 'react-native'; export default function App() { if (Platform.OS === 'ios') { return <AppleMaps.View style={{ flex: 1 }} />; } else if (Platform.OS === 'android') { return <GoogleMaps.View style={{ flex: 1 }} />; } else { return <Text>地图仅适用于 Android 和 iOS</Text>; } }
自定义标记图标
你可以使用 expo-image 中的 useImage 钩子来加载自定义标记和注释图标。
以下示例展示了如何在 Android 上使用 Google Maps 显示自定义标记图标。
import { useImage } from 'expo-image'; import { GoogleMaps } from 'expo-maps'; export default function Map() { const icon = useImage('https://example.com/marker.svg', { maxWidth: 48, maxHeight: 48 }); return ( <GoogleMaps.View style={{ flex: 1 }} markers={[ { coordinates: { latitude: 37.78825, longitude: -122.4324 }, icon: icon ?? undefined, anchor: { x: 0.5, y: 0.5 }, }, ]} /> ); }
GoogleMaps.Marker.icon 期望接收一个图像引用，例如 expo-image 包中 useImage 钩子返回的值。它不直接接受图像源。
加载后的图像尺寸决定标记大小，而不是某个 marker style 属性。对于 SVG 图标，请在 SVG 中设置 width、height 和 viewBox，或将 maxWidth 和 maxHeight 传递给 useImage 钩子。你可以使用 anchor 将自定义图标与其坐标对齐。
以下示例展示了如何在 iOS 上使用 Apple Maps 显示自定义注释图标。
import { useImage } from 'expo-image'; import { AppleMaps } from 'expo-maps'; export default function Map() { const icon = useImage('https://example.com/marker.svg'); return ( <AppleMaps.View style={{ flex: 1 }} annotations={[ { coordinates: { latitude: 37.78825, longitude: -122.4324 }, icon: icon ?? undefined, }, ]} /> ); }
AppleMaps.Annotation.icon 期望接收一个图像引用，例如 expo-image 库中 useImage 钩子返回的值。你可以将 AppleMaps.Annotation 用于自定义图像图标。AppleMaps.Marker 支持特定于标记的选项，例如 systemImage、monogram 和 tintColor。
API
import { AppleMaps, GoogleMaps } from 'expo-maps'; // AppleMaps.View 和 GoogleMaps.View 是 React 组件
Components
Type: React.Element<Component<Omit<AppleMapsViewProps, 'ref'>>>
AppleMapsColorScheme • Default: AppleMapsColorScheme.AUTOMATICControls the color scheme (appearance) of the map. Use this to force the map to display in light or dark mode.
(event: AppleMapsAnnotation) => voidLambda invoked when the annotation is clicked.
(event: CameraMoveEvent) => voidLambda invoked when the map was moved by the user. Also runs once on initial mount with the starting viewport.
(event: AppleMapsCircle) => voidLambda invoked when the circle is clicked.
(event: {
coordinates: Coordinates
}) => voidLambda invoked when the user clicks on the map. It won't be invoked if the user clicks on POI or a marker.
(event: AppleMapsMarker) => voidLambda invoked when the marker is clicked.
(event: AppleMapsPolygon) => voidLambda invoked when the polygon is clicked.
(event: AppleMapsPolyline) => voidLambda invoked when the polyline is clicked.
Ref<AppleMapsViewType>StyleProp<ViewStyle>AppleMapsUISettingsThe MapUiSettings to be used for UI-specific settings on the map.
Type: React.Element<Component<Omit<GoogleMapsViewProps, 'ref'>>>
GoogleMapsContentPaddingThe padding values used to signal that portions of the map around the edges may be obscured. The map will move the Google logo, etc. to avoid overlapping the padding.
GoogleMapsMapOptionsDefines configuration GoogleMapOptions for a GoogleMap
(event: CameraMoveEvent) => voidLambda invoked when the map was moved by the user. Also runs once on initial mount with the starting viewport.
(event: GoogleMapsCircle) => voidLambda invoked when the circle is clicked.
(event: {
coordinates: Coordinates
}) => voidLambda invoked when the user clicks on the map. It won't be invoked if the user clicks on POI or a marker.
(event: {
coordinates: Coordinates
}) => voidLambda invoked when the user long presses on the map.
(event: GoogleMapsMarker) => voidLambda invoked when the marker is clicked
(event: {
coordinates: Coordinates,
name: string
}) => voidLambda invoked when a POI is clicked.
(event: GoogleMapsPolygon) => voidLambda invoked when the polygon is clicked.
(event: GoogleMapsPolyline) => voidLambda invoked when the polyline is clicked.
Ref<GoogleMapsViewType>StyleProp<ViewStyle>GoogleMapsUISettingsThe MapUiSettings to be used for UI-specific settings on the map.
GoogleMapsUserLocationUser location, overrides default behavior.
Type: React.Element<GoogleStreetViewProps>
StreetViewCameraPositionStyleProp<ViewStyle>Hooks
Check or request permissions to access the location.
This uses both requestPermissionsAsync and getPermissionsAsync to interact with the permissions.
[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = useLocationPermissions();
Methods
Promise<PermissionResponse>Promise<PermissionResponse>Types
The event payload for the onCameraMove callback on AppleMaps.View and GoogleMaps.View.
Enums
Controls the color scheme (appearance) of the map.
AppleMapsColorScheme.AUTOMATIC ＝ "AUTOMATIC"The map follows the app's color scheme (light/dark mode).
The style of the polyline.
AppleMapsMapStyleElevation.AUTOMATIC ＝ "AUTOMATIC"The default elevation style, that renders a flat, 2D map.
The type of map to display.
AppleMapsMapType.HYBRID ＝ "HYBRID"A satellite image of the area with road and road name layers on top.
The type of map to display.
GoogleMapsMapType.HYBRID ＝ "HYBRID"Satellite imagery with roads and points of interest overlayed.
权限
Android
要在地图上显示用户的位置，expo-maps 库需要以下权限：
ACCESS_COARSE_LOCATION：用于设备的大致位置ACCESS_FINE_LOCATION：用于设备的精确位置
iOS
此库使用以下用途说明键：