Docs
博客更新日志GitHub简中文档
首页指南EAS参考学习

Reference version

存档Expo SnackDiscord 和论坛新闻邮件

Expo 地图 iconExpo 地图

一个在 Android 上提供 Google 地图访问、在 iOS 上提供 Apple 地图访问的库。

Android
iOS

GitHub

npm

更新日志

Bundled version:
~0.11.0

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

重要 该库目前处于 alpha 阶段，并且会频繁出现破坏性变更。 它无法在 Expo Go 应用中使用 – 请使用开发构建来试用。

安装

Terminal
- npx expo install expo-maps

If you are installing this in an existing React Native app, make sure to install expo in your project.


观看：Expo Maps 深度解析
观看：Expo Maps 深度解析

使用 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 证书指纹

  • 如果你已经创建了一个开发构建，你的项目将使用 debug keystore 进行签名。
  • 构建完成后，进入你的项目仪表板，然后在 Project settings 下点击 Credentials。
  • 在 Application Identifiers 下，点击你项目的包名，然后在 Android Keystore 下复制 SHA-1 Certificate Fingerprint 的值。

3

创建一个 API key

  • 前往 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）添加到 package name 字段。
  • 然后，添加第 2 步中的 SHA-1 certificate fingerprint 的值。
  • 点击 Done，然后点击 Save。

4

将 API key 添加到你的项目中

  • 将你的 API Key 复制到 app.json 中的 android.config.googleMaps.apiKey 字段下。
  • 创建一个新的开发构建，现在你就可以在 Android 上使用 expo-maps 的 Google Maps API 了。

权限

要在地图上显示用户位置，你需要提前声明并请求位置权限。如果你在项目中使用 config plugins，可以通过其内置的配置插件来进行配置（Continuous Native Generation (CNG)）。该插件允许你配置一些无法在运行时设置、且需要重新构建新的应用二进制文件才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json
{
  "expo": {
    "plugins": [
      [
        "expo-maps",
        {
          "requestLocationPermission": true,
          "locationPermission": "允许 $(PRODUCT_NAME) 使用你的位置"
        }
      ]
    ]
  }
}

Configurable properties

NameDefaultDescription
requestLocationPermissionfalse

一个布尔值，用于向 AndroidManifest.xml 和 Info.plist 添加权限。

locationPermission"允许 $(PRODUCT_NAME) 使用你的位置"
Only for: 
iOS

一个字符串，用于设置 NSLocationWhenInUseUsageDescription 权限消息。

用法

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>;
  }
}

API

import { AppleMaps, GoogleMaps } from 'expo-maps';

// ApplesMaps.View 和 GoogleMaps.View 是 React 组件

Components

AppleMapsView

iOS

Type: React.Element<Omit<AppleMapsViewProps, 'ref'>>

AppleMapsViewProps

annotations

iOS
Optional • Type: AppleMapsAnnotation[]

The array of annotations to display on the map.

cameraPosition

iOS
Optional • Type: CameraPosition

The initial camera position of the map.

markers

iOS
Optional • Type: AppleMapsMarker[]

The array of markers to display on the map.

onCameraMove

iOS
Optional • Type: (event: { bearing: number, coordinates: Coordinates, tilt: number, zoom: number }) => void

Lambda invoked when the map was moved by the user.

onMapClick

iOS
Optional • Type: (event: { coordinates: Coordinates }) => void

Lambda invoked when the user clicks on the map. It won't be invoked if the user clicks on POI or a marker.

onMarkerClick

iOS 18.0+
Optional • Type: (event: AppleMapsMarker) => void

Lambda invoked when the marker is clicked

onPolylineClick

iOS 18.0+
Optional • Type: (event: AppleMapsPolyline) => void

Lambda invoked when the polyline is clicked

polylines

iOS
Optional • Type: AppleMapsPolyline[]

The array of polylines to display on the map.

properties

iOS
Optional • Type: AppleMapsProperties

The properties for the map.

ref

iOS
Optional • Type: Ref<AppleMapsViewType>

style

iOS
Optional • Type: StyleProp<ViewStyle>

uiSettings

iOS
Optional • Type: AppleMapsUISettings

The MapUiSettings to be used for UI-specific settings on the map.

GoogleMapsView

Android

Type: React.Element<Omit<GoogleMapsViewProps, 'ref'>>

GoogleMapsViewProps

cameraPosition

Android
Optional • Type: CameraPosition

The initial camera position of the map.

colorScheme

Android
Optional • Type: GoogleMapsColorScheme

Defines the color scheme for the map.

markers

Android
Optional • Type: GoogleMapsMarker[]

The array of markers to display on the map.

onCameraMove

Android
Optional • Type: (event: { bearing: number, coordinates: Coordinates, tilt: number, zoom: number }) => void

Lambda invoked when the map was moved by the user.

onMapClick

Android
Optional • Type: (event: { coordinates: Coordinates }) => void

Lambda invoked when the user clicks on the map. It won't be invoked if the user clicks on POI or a marker.

onMapLoaded

Android
Optional • Type: () => void

Lambda invoked when the map is loaded.

onMapLongClick

Android
Optional • Type: (event: { coordinates: Coordinates }) => void

Lambda invoked when the user long presses on the map.

onMarkerClick

Android
Optional • Type: (event: GoogleMapsMarker) => void

Lambda invoked when the marker is clicked

onPOIClick

Android
Optional • Type: (event: { coordinates: Coordinates, name: string }) => void

Lambda invoked when a POI is clicked.

onPolylineClick

Android
Optional • Type: (event: GoogleMapsPolyline) => void

Lambda invoked when the polyline is clicked.

polylines

Android
Optional • Type: GoogleMapsPolyline[]

The array of polylines to display on the map.

properties

Android
Optional • Type: GoogleMapsProperties

The properties for the map.

ref

Android
Optional • Type: Ref<GoogleMapsViewType>

style

Android
Optional • Type: StyleProp<ViewStyle>

uiSettings

Android
Optional • Type: GoogleMapsUISettings

The MapUiSettings to be used for UI-specific settings on the map.

userLocation

Android
Optional • Type: GoogleMapsUserLocation

User location, overrides default behavior.

GoogleStreetView

Android

Type: React.Element<GoogleStreetViewProps>

GoogleStreetViewProps

isPanningGesturesEnabled

Android
Optional • Type: boolean

isStreetNamesEnabled

Android
Optional • Type: boolean

isUserNavigationEnabled

Android
Optional • Type: boolean

isZoomGesturesEnabled

Android
Optional • Type: boolean

position

Android
Type: StreetViewCameraPosition

style

Android
Optional • Type: StyleProp<ViewStyle>

Hooks

useLocationPermissions(options)

Android
iOS
ParameterType
options(optional)PermissionHookOptions<object>

Check or request permissions to access the location. This uses both requestPermissionsAsync and getPermissionsAsync to interact with the permissions.

Returns:
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Example

const [status, requestPermission] = useLocationPermissions();

Methods

Maps.getPermissionsAsync()

Android
iOS

Checks user's permissions for accessing location.

Returns:
Promise<PermissionResponse>

A promise that fulfills with an object of type PermissionResponse.

Maps.requestPermissionsAsync()

Android
iOS

Asks the user to grant permissions for location.

Returns:
Promise<PermissionResponse>

A promise that fulfills with an object of type PermissionResponse.

Types

AppleMapsAnnotation

iOS

Type: AppleMapsMarker extended by:

PropertyTypeDescription
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.

AppleMapsMarker

iOS
PropertyTypeDescription
coordinates(optional)Coordinates

The coordinates of the marker.

id(optional)string

The unique identifier for the marker. This can be used to e.g. identify the clicked marker in the onMarkerClick event.

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.

AppleMapsPolyline

Android
iOS
PropertyTypeDescription
color(optional)ProcessedColorValue | string

The color of the polyline.

contourStyle(optional)AppleMapsContourStyle

The style of the polyline.

coordinatesCoordinates[]

The coordinates of the polyline.

id(optional)string

The unique identifier for the polyline. This can be used to e.g. identify the clicked polyline in the onPolylineClick event.

width(optional)number

The width of the polyline.

AppleMapsProperties

iOS
PropertyTypeDescription
isTrafficEnabled(optional)boolean

Whether the traffic layer is enabled on the map.

mapType(optional)AppleMapsMapType

Defines which map type should be used.

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 onPolylineClick event will be triggered. Defaults to 20 meters.

selectionEnabled(optional)boolean

If true, the user can select a location on the map to get more information.

AppleMapsUISettings

iOS
PropertyTypeDescription
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.

AppleMapsViewType

iOS
PropertyTypeDescription
setCameraPosition(config: CameraPosition) => void

Update camera position. Animation duration is not supported on iOS.

config: CameraPosition

New camera postion.

CameraPosition

Android
iOS
PropertyTypeDescription
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.

Coordinates

Android
iOS
PropertyTypeDescription
latitude(optional)number

The latitude of the coordinate.

longitude(optional)number

The longitude of the coordinate.

GoogleMapsMarker

Android
PropertyTypeDescription
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 e.g. identify the clicked marker in the onMarkerClick event.

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.

GoogleMapsPolyline

Android
PropertyTypeDescription
color(optional)ProcessedColorValue | string

The color of the polyline.

coordinatesCoordinates[]

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 e.g. identify the clicked polyline in the onPolylineClick event.

width(optional)number

The width of the polyline.

GoogleMapsProperties

Android
PropertyTypeDescription
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.

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.

GoogleMapsUISettings

Android
PropertyTypeDescription
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.

GoogleMapsUserLocation

Android
PropertyTypeDescription
coordinatesCoordinates

User location coordinates.

followUserLocationboolean

Should the camera follow the users' location.

GoogleMapsViewType

Android
PropertyTypeDescription
setCameraPosition(config: SetCameraPositionConfig) => void

Update camera position.

config: SetCameraPositionConfig

New camera position config.

SetCameraPositionConfig

Android

Type: CameraPosition extended by:

PropertyTypeDescription
duration(optional)number

The duration of the animation in milliseconds.

StreetViewCameraPosition

Android
PropertyTypeDescription
bearing(optional)number
-
coordinatesCoordinates
-
tilt(optional)number
-
zoom(optional)number
-

Enums

AppleMapsContourStyle

iOS

The style of the polyline.

GEODESIC

AppleMapsContourStyle.GEODESIC ＝ "GEODESIC"

A geodesic line.

STRAIGHT

AppleMapsContourStyle.STRAIGHT ＝ "STRAIGHT"

A straight line.

AppleMapsMapType

iOS

The type of map to display.

HYBRID

AppleMapsMapType.HYBRID ＝ "HYBRID"

A satellite image of the area with road and road name layers on top.

IMAGERY

AppleMapsMapType.IMAGERY ＝ "IMAGERY"

A satellite image of the area.

STANDARD

AppleMapsMapType.STANDARD ＝ "STANDARD"

A street map that shows the position of all roads and some road names.

GoogleMapsColorScheme

Android

DARK

GoogleMapsColorScheme.DARK ＝ "DARK"

FOLLOW_SYSTEM

GoogleMapsColorScheme.FOLLOW_SYSTEM ＝ "FOLLOW_SYSTEM"

LIGHT

GoogleMapsColorScheme.LIGHT ＝ "LIGHT"

GoogleMapsMapType

Android

The type of map to display.

HYBRID

GoogleMapsMapType.HYBRID ＝ "HYBRID"

Satellite imagery with roads and points of interest overlayed.

NORMAL

GoogleMapsMapType.NORMAL ＝ "NORMAL"

Standard road map.

SATELLITE

GoogleMapsMapType.SATELLITE ＝ "SATELLITE"

Satellite imagery.

TERRAIN

GoogleMapsMapType.TERRAIN ＝ "TERRAIN"

Topographic data.

权限

Android

要在地图上显示用户位置，expo-maps 库需要以下权限：

  • ACCESS_COARSE_LOCATION：用于获取设备的大致位置
  • ACCESS_FINE_LOCATION：用于获取设备的精确位置
Android PermissionDescription

ACCESS_COARSE_LOCATION

Allows an app to access approximate location.

Alternatively, you might want ACCESS_FINE_LOCATION.

ACCESS_FINE_LOCATION

Allows an app to access precise location.

Alternatively, you might want ACCESS_COARSE_LOCATION.

FOREGROUND_SERVICE

Allows a regular application to use Service.startForeground.

Allows a regular application to use Service.startForeground.

FOREGROUND_SERVICE_LOCATION

Allows a regular application to use Service.startForeground with the type "location".

Allows a regular application to use Service.startForeground with the type "location".

ACCESS_BACKGROUND_LOCATION

Allows an app to access location in the background.

If you're requesting this permission, you must also request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION. Requesting this permission by itself doesn't give you location access.

iOS

该库使用以下用途说明键：

Info.plist KeyDescription

NSLocationWhenInUseUsageDescription

A message that tells the user why the app is requesting access to the user’s location information while the app is running in the foreground.