This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Maps
一个提供在 Android 上访问 Google Maps 和在 iOS 上访问 Apple Maps 的库。
在 iOS 上，Expo Maps 使用 Apple Maps，且要求 iOS 17 或更高版本。部分功能要求 iOS 18 或更高版本，包括标记、注释和覆盖层的点击回调（例如
onMarkerClick和onPolylineClick）以及程序化选择（selectMarker和selectAnnotation）。
安装
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 项目、启用 Maps SDK for Android，并将相关配置添加到 Expo 项目中。
在 Android 上设置 Google Maps
如果你已经为其他 Android 上的 Google 服务（例如 Google Sign In）注册过项目，可以在项目中启用 Maps SDK for Android，然后直接跳到第 4 步。
1
注册 Google Cloud API 项目并启用 Maps SDK for Android
- 在浏览器中打开 Google API Manager 并创建一个项目。
- 创建完成后，前往该项目并启用 Maps SDK for Android。
2
复制应用的 SHA-1 证书指纹
- 如果要将应用部署到 Google Play Store，你需要至少将应用二进制文件上传到 Google Play 控制台一次。这是 Google 生成应用签名凭据的必要步骤。
- 前往 Google Play Console >（你的应用）> Release > Setup > App integrity > App Signing。
- 复制 SHA-1 certificate fingerprint 的值。
3
创建 API 密钥
- 前往 Google Cloud Credential manager，点击 Create Credentials，然后点击 API Key。
- 在弹窗中，点击 Edit API key。
- 在 Key restrictions > Application restrictions 下，选择 Android apps。
- 在 Restrict usage to your Android apps 下，点击 Add an item。
- 将 app.json 中的
android.package（例如：com.company.myapp）添加到包名字段中。 - 然后，添加第 2 步中的 SHA-1 certificate fingerprint 值。
- 点击 Done，然后点击 Save。
4
将 API 密钥添加到项目中
- 将你的 API Key 复制到 app.json 中的
android.config.googleMaps.apiKey字段。 - 创建新的开发版本后，即可通过
expo-maps在 Android 上使用 Google Maps API。
权限
要在地图上显示用户的位置，你需要事先声明并请求位置权限。如果项目使用配置插件（Continuous Native Generation (CNG)），可以通过内置的配置插件进行配置。该插件允许你配置各种无法在运行时设置、且需要重新构建应用二进制文件才能生效的属性。如果你的应用不使用 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>Maps are only available on Android and 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 钩子返回的值。它不接受直接传入图像源。
加载的图像尺寸决定标记大小，而非标记样式属性。对于 SVG 图标，请在 SVG 中设置 width、height 和 viewBox，或向 useImage 钩子传入 maxWidth 和 maxHeight。你可以使用 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 and GoogleMaps.View are the React components
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
此库使用以下用途说明键：