一个库,提供对 Android 上 Google 地图和 iOS 上 Apple 地图的访问。
这个库目前处于 alpha 阶段,并将频繁经历重大变化。 它在 Expo Go 应用中不可用 – 使用 开发构建 来尝试它。
安装
- npx expo install expo-mapsIf you are installing this in an existing React Native app, make sure to install expo in your project.

配置
Expo Maps 提供对 Android 和 iOS 平台本地地图 API 的访问。
- Apple 地图(仅在 iOS上可用)。在安装此包后,无需其他配置即可使用它。
- Google 地图(仅在 Android上可用)。虽然 Google 为 iOS 提供 Google Maps SDK,但 Expo Maps 仅在 Android 上支持它。如果您想在 iOS 上使用 Google 地图,可以考虑使用 替代库 或 编写您自己的。
Google Cloud API 设置
在您能够在 Android 上使用 Google 地图之前,您需要注册一个 Google Cloud API 项目,启用 Android 的 Maps SDK,并将相关配置添加到您的 Expo 项目中。
在 Android 上设置 Google 地图
如果您已经为 Android 上的其他 Google 服务(例如 Google 登录)注册了项目,请启用您的项目上的 Maps SDK for Android,然后跳到步骤 4。
1
注册 Google Cloud API 项目并启用 Android 的 Maps SDK
- 打开浏览器并前往 Google API 管理器,然后创建一个项目。
- 创建后,转到该项目并启用 Maps SDK for Android。
2
复制您的应用程序的 SHA-1 证书指纹
- 如果您将应用程序部署到 Google Play 商店,则需要至少一次 上传您的应用程序二进制文件到 Google Play 控制台。这是 Google 生成应用程序签名凭据所必需的。
- 转到 Google Play Console > (您的应用) > 测试与发布 > 应用完整性 > Play 应用签名 > 设置 > 应用签名密钥证书。
- 复制 SHA-1 certificate fingerprint 的值。
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字段中。 - 创建一个新的开发构建,您现在可以使用
expo-maps在 Android 上使用 Google Maps API。
权限
要在地图上显示用户的位置,您需要事先声明并请求位置权限。如果您在项目中使用配置插件,可以通过其内置的 配置插件 进行配置 (持续原生生成 (CNG))。该插件允许您配置在运行时无法设置的各种属性,并需要构建新的应用程序二进制文件才能生效。如果您的应用程序 不 使用 CNG,则需要手动配置库。
Example app.json with config plugin
{ "expo": { "plugins": [ [ "expo-maps", { "requestLocationPermission": true, "locationPermission": "Allow $(PRODUCT_NAME) to use your location" } ] ] } }
Configurable properties
| Name | Default | Description |
|---|---|---|
requestLocationPermission | false | A boolean to add permissions to AndroidManifest.xml and Info.plist. |
locationPermission | "Allow $(PRODUCT_NAME) to use your location" | Only for: iOS A string to set the |
使用
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>; } }
API
import { AppleMaps, GoogleMaps } from 'expo-maps'; // ApplesMaps.View 和 GoogleMaps.View 是 React 组件
Components
Type: React.Element<Omit<AppleMapsViewProps, 'ref'>>
AppleMapsAnnotation[]The array of annotations to display on the map.
(event: {
bearing: number,
coordinates: Coordinates,
tilt: number,
zoom: number
}) => voidLambda invoked when the map was moved by the user.
(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
AppleMapsPolygon[]The array of polygons to display on the map.
AppleMapsPolyline[]The array of polylines to display on the map.
Ref<AppleMapsViewType>StyleProp<ViewStyle>AppleMapsUISettingsThe MapUiSettings to be used for UI-specific settings on the map.
Type: React.Element<Omit<GoogleMapsViewProps, 'ref'>>
CameraPositionThe initial camera position of the map.
GoogleMapsCircle[]The array of circles to display on the map.
GoogleMapsColorSchemeDefines the color scheme for the map.
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
GoogleMapsMarker[]The array of markers to display on the map.
(event: {
bearing: number,
coordinates: Coordinates,
tilt: number,
zoom: number
}) => voidLambda invoked when the map was moved by the user.
(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.
GoogleMapsPolygon[]The array of polygons to display on the map.
GoogleMapsPolyline[]The array of polylines to display on the map.
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
| Parameter | Type |
|---|---|
| options(optional) | PermissionHookOptions<object> |
Check or request permissions to access the location.
This uses both requestPermissionsAsync and getPermissionsAsync to interact with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = useLocationPermissions();
Methods
Checks user's permissions for accessing location.
Promise<PermissionResponse>A promise that fulfills with an object of type PermissionResponse.
Asks the user to grant permissions for location.
Promise<PermissionResponse>A promise that fulfills with an object of type PermissionResponse.
Types
Type: AppleMapsMarker extended by:
| Property | Type | Description |
|---|---|---|
| backgroundColor(optional) | string | The background color of the annotation. |
| icon(optional) | SharedRefType<'image'> | The custom icon to display in the annotation. |
| text(optional) | string | The text to display in the annotation. |
| textColor(optional) | string | The text color of the annotation. |
| Property | Type | Description |
|---|---|---|
| center | Coordinates | The coordinates of the circle. |
| color(optional) | ProcessedColorValue | string | The color of the circle. |
| id(optional) | string | The unique identifier for the circle. This can be used to identify the clicked circle in the |
| lineColor(optional) | ProcessedColorValue | string | The color of the circle line. |
| lineWidth(optional) | number | The width of the circle line. |
| radius | number | The radius of the circle (in meters). |
| width(optional) | number | The width of the circle. |
| Property | Type | Description |
|---|---|---|
| coordinates(optional) | Coordinates | The coordinates of the marker. |
| id(optional) | string | The unique identifier for the marker. This can be used to identify the clicked marker in the |
| systemImage(optional) | string | The SF Symbol to display for the marker. |
| tintColor(optional) | string | The tint color of the marker. |
| title(optional) | string | The title of the marker, displayed in the callout when the marker is clicked. |
| Property | Type | Description |
|---|---|---|
| excluding(optional) | AppleMapPointOfInterestCategory[] | The POI categories to exclude. To show all POIs, set this to an empty array. |
| including(optional) | AppleMapPointOfInterestCategory[] | The POI categories to include. To hide all POIs, set this to an empty array. |
| Property | Type | Description |
|---|---|---|
| color(optional) | ProcessedColorValue | string | The color of the polygon. |
| coordinates | Coordinates[] | The coordinates of the circle. |
| id(optional) | string | The unique identifier for the polygon. This can be used to identify the clicked polygon in the |
| lineColor(optional) | ProcessedColorValue | string | The color of the polygon. |
| lineWidth(optional) | number | The width of the polygon. |
| Property | Type | Description |
|---|---|---|
| color(optional) | ProcessedColorValue | string | The color of the polyline. |
| contourStyle(optional) | AppleMapsContourStyle | The style of the polyline. |
| coordinates | Coordinates[] | The coordinates of the polyline. |
| id(optional) | string | The unique identifier for the polyline. This can be used to identify the clicked polyline in the |
| width(optional) | number | The width of the polyline. |
| Property | Type | Description |
|---|---|---|
| elevation(optional) | AppleMapsMapStyleElevation | Values you use to determine whether a map renders elevation. |
| emphasis(optional) | AppleMapsMapStyleEmphasis | Values that control how the framework emphasizes map features. |
| isMyLocationEnabled(optional) | boolean | Whether the user location is shown on the map. Default: false |
| isTrafficEnabled(optional) | boolean | Whether the traffic layer is enabled on the map. |
| mapType(optional) | AppleMapsMapType | Defines which map type should be used. |
| pointsOfInterest(optional) | AppleMapsPointOfInterestCategories | A structure you use to define points of interest to include or exclude on a map. |
| polylineTapThreshold(optional) | number | The maximum distance in meters from a tap of a polyline for it to be considered a hit.
If the distance is greater than the threshold, the polyline is not considered a hit.
If a hit occurs, the |
| selectionEnabled(optional) | boolean | If true, the user can select a location on the map to get more information. |
| Property | Type | Description |
|---|---|---|
| compassEnabled(optional) | boolean | Whether the compass is enabled on the map. If enabled, the compass is only visible when the map is rotated. |
| myLocationButtonEnabled(optional) | boolean | Whether the my location button is visible. |
| scaleBarEnabled(optional) | boolean | Whether the scale bar is displayed when zooming. |
| togglePitchEnabled(optional) | boolean | Whether the user is allowed to change the pitch type. |
| Property | Type | Description |
|---|---|---|
| openLookAroundAsync | (coordinates: Coordinates) => Promise<void> | Opens the look around view at specified coordinates. coordinates: CoordinatesThe coordinates of the location to open the look around view at. |
| setCameraPosition | (config: CameraPosition) => void | Update camera position. Animation duration is not supported on iOS. config: CameraPositionNew camera postion. |
| Property | Type | Description |
|---|---|---|
| coordinates(optional) | Coordinates | The middle point of the camera. |
| zoom(optional) | number | The zoom level of the camera. For some view sizes, lower zoom levels might not be available. |
| Property | Type | Description |
|---|---|---|
| latitude(optional) | number | The latitude of the coordinate. |
| longitude(optional) | number | The longitude of the coordinate. |
| Property | Type | Description |
|---|---|---|
| x | number | The normalized horizontal anchor point from 0.0 (left edge) to 1.0 (right edge). |
| y | number | The normalized vertical anchor point from 0.0 (top edge) to 1.0 (bottom edge). |
| Property | Type | Description |
|---|---|---|
| center | Coordinates | The coordinates of the circle. |
| color(optional) | ProcessedColorValue | string | The color of the circle. |
| id(optional) | string | The unique identifier for the circle. This can be used to identify the clicked circle in the |
| lineColor(optional) | ProcessedColorValue | string | The color of the circle line. |
| lineWidth(optional) | number | The width of the circle line. |
| radius | number | The radius of the circle. |
| Property | Type | Description |
|---|---|---|
| bottom(optional) | number | The padding on the bottom side of the map. |
| end(optional) | number | In LTR contexts, |
| start(optional) | number | In LTR contexts, |
| top(optional) | number | The padding on the top side of the map. |
| Property | Type | Description |
|---|---|---|
| mapId(optional) | string | A map ID is a unique identifier that represents Google Map styling and configuration settings that are stored in Google Cloud.
|
| Property | Type | Description |
|---|---|---|
| json | string | The JSON string of the map style options.
|
| Property | Type | Description |
|---|---|---|
| anchor(optional) | GoogleMapsAnchor | The anchor used to position the anchor relative to its coordinates. Default: bottom-center of the icon |
| coordinates(optional) | Coordinates | The coordinates of the marker. |
| draggable(optional) | boolean | Whether the marker is draggable. |
| icon(optional) | SharedRefType<'image'> | The custom icon to display for the marker. |
| id(optional) | string | The unique identifier for the marker. This can be used to identify the clicked marker in the |
| showCallout(optional) | boolean | Whether the callout should be shown when the marker is clicked. |
| snippet(optional) | string | The snippet of the marker, displayed in the callout when the marker is clicked. |
| title(optional) | string | The title of the marker, displayed in the callout when the marker is clicked. |
| zIndex(optional) | number | The z-index to use for the marker. Default: 0 |
| Property | Type | Description |
|---|---|---|
| color(optional) | ProcessedColorValue | string | The color of the polygon. |
| coordinates | Coordinates[] | The coordinates of the circle. |
| id(optional) | string | The unique identifier for the polygon. This can be used to identify the clicked polygon in the |
| lineColor(optional) | ProcessedColorValue | string | The color of the polygon. |
| lineWidth(optional) | number | The width of the polygon. |
| Property | Type | Description |
|---|---|---|
| color(optional) | ProcessedColorValue | string | The color of the polyline. |
| coordinates | Coordinates[] | The coordinates of the polyline. |
| geodesic(optional) | boolean | Whether the polyline is geodesic. |
| id(optional) | string | The unique identifier for the polyline. This can be used to identify the clicked polyline in the |
| width(optional) | number | The width of the polyline. |
| Property | Type | Description |
|---|---|---|
| isBuildingEnabled(optional) | boolean | Whether the building layer is enabled on the map. |
| isIndoorEnabled(optional) | boolean | Whether the indoor layer is enabled on the map. |
| isMyLocationEnabled(optional) | boolean | Whether finding the user's location is enabled on the map. |
| isTrafficEnabled(optional) | boolean | Whether the traffic layer is enabled on the map. |
| mapStyleOptions(optional) | GoogleMapsMapStyleOptions | With style options you can customize the presentation of the standard Google map styles, changing the visual display of features like roads, parks, and other points of interest. |
| mapType(optional) | GoogleMapsMapType | Defines which map type should be used. |
| maxZoomPreference(optional) | number | The maximum zoom level for the map. |
| minZoomPreference(optional) | number | The minimum zoom level for the map. |
| selectionEnabled(optional) | boolean | If true, the user can select a location on the map to get more information. |
| Property | Type | Description |
|---|---|---|
| compassEnabled(optional) | boolean | Whether the compass is enabled on the map. If enabled, the compass is only visible when the map is rotated. |
| indoorLevelPickerEnabled(optional) | boolean | Whether the indoor level picker is enabled . |
| mapToolbarEnabled(optional) | boolean | Whether the map toolbar is visible. |
| myLocationButtonEnabled(optional) | boolean | Whether the my location button is visible. |
| rotationGesturesEnabled(optional) | boolean | Whether rotate gestures are enabled. |
| scaleBarEnabled(optional) | boolean | Whether the scale bar is displayed when zooming. |
| scrollGesturesEnabled(optional) | boolean | Whether the scroll gestures are enabled. |
| scrollGesturesEnabledDuringRotateOrZoom(optional) | boolean | Whether the scroll gestures are enabled during rotation or zoom. |
| tiltGesturesEnabled(optional) | boolean | Whether the tilt gestures are enabled. |
| togglePitchEnabled(optional) | boolean | Whether the user is allowed to change the pitch type. |
| zoomControlsEnabled(optional) | boolean | Whether the zoom controls are visible. |
| zoomGesturesEnabled(optional) | boolean | Whether the zoom gestures are enabled. |
| Property | Type | Description |
|---|---|---|
| coordinates | Coordinates | User location coordinates. |
| followUserLocation | boolean | Should the camera follow the users' location. |
| Property | Type | Description |
|---|---|---|
| setCameraPosition | (config: SetCameraPositionConfig) => void | Update camera position. config: SetCameraPositionConfigNew camera position config. |
Type: CameraPosition extended by:
| Property | Type | Description |
|---|---|---|
| duration(optional) | number | The duration of the animation in milliseconds. |
| Property | Type | Description |
|---|---|---|
| bearing(optional) | number | - |
| coordinates | Coordinates | - |
| tilt(optional) | number | - |
| zoom(optional) | number | - |
Enums
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: 用于精确设备位置
| Android Permission | Description |
|---|---|
Allows an app to access approximate location.
| |
Allows an app to access precise location.
| |
Allows a regular application to use Service.startForeground.
| |
Allows a regular application to use Service.startForeground with the type "location".
| |
Allows an app to access location in the background.
|
iOS
此库使用的以下使用描述键:
Expo 地图