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 地图和 iOS 上的 Apple 地图的访问的库。
安装
🌐 Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
The with-maps example comes with expo-maps already installed and configured:
使用 expo-maps 库将 Google 地图和 Apple 地图添加到你的 Expo 应用中。
配置
🌐 Configuration
Expo Maps 提供对 Android 和 iOS 上平台原生地图 API 的访问。
🌐 Expo Maps provides access to the platform native map APIs on Android and iOS.
- Apple 地图（仅在 iOS上可用）。安装此软件包后，无需额外配置即可使用。
- Google 地图（仅在 Android可用）。虽然 Google 为 iOS 提供了 Google Maps SDK，但 Expo Maps 仅在 Android 上支持它。如果你想在 iOS 上使用 Google 地图，你可以考虑使用替代库或自己编写。
Google Cloud API 设置
🌐 Google Cloud API setup
在你可以在 Android 上使用 Google 地图之前，你需要注册一个 Google Cloud API 项目，启用适用于 Android 的 Maps SDK，并将相关配置添加到你的 Expo 项目中。
在安卓上设置谷歌地图
如果你已经为 Android 上的其他 Google 服务（例如 Google 登录）注册了项目，请在你的项目上启用 Android 版 Maps SDK，然后跳到步骤 4。
1
注册一个 Google Cloud API 项目并启用 Android 的 Maps SDK
- 打开你的浏览器访问 Google API 管理器 并创建一个项目。
- 创建完成后，进入项目并启用Android 地图 SDK。
2
复制你应用的 SHA-1 证书指纹
- 如果你要将应用发布到 Google Play 商店，你至少需要将应用二进制文件上传到 Google Play 控制台。这是 Google 生成应用签名凭证所必需的。
- 前往 Google Play 控制台 > (你的应用) > 发布 > 设置 > 应用完整性 > 应用签名。
- 复制 SHA-1 证书指纹 的值。
3
创建 API 密钥
- 前往 Google Cloud 凭据管理器，点击 创建凭据，然后选择 API 密钥。
- 在弹出窗口中，点击 编辑 API 密钥。
- 在 关键限制 > 应用限制 下，选择 Android 应用。
- 在 限制使用于你的 Android 应用 下，点击 添加项目。
- 将你的
android.package从 app.json（例如：com.company.myapp）添加到包名字段中。 - 然后，添加步骤 2 中 SHA-1 证书指纹 的值。
- 点击 完成，然后点击 保存。
4
将 API 密钥添加到你的项目中
- 将你的 API 密钥 复制到 app.json 的
android.config.googleMaps.apiKey字段中。 - 创建一个新的开发版本，现在你可以在 Android 上使用
expo-maps的 Google 地图 API。
权限
🌐 Permissions
要在地图上显示用户的位置，你需要事先声明并请求位置权限。如果你的项目中使用了配置插件（Continuous Native Generation (CNG)），可以通过其内置的配置插件进行配置。该插件允许你配置一些无法在运行时设置、需要生成新的应用二进制文件才能生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。
🌐 To display the user's location on the map, you need to declare and request location permission beforehand. You can configure this using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.
Example app.json with config plugin
Configurable properties
用法
🌐 Usage
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>; } }
自定义标记图标
🌐 Custom marker icons
你可以使用 expo-image 的 useImage 钩子来加载自定义标记和注解图标。
🌐 You can use the useImage hook from expo-image to load custom marker and annotation icons.
以下示例显示了如何在 Android 上使用 Google 地图显示自定义标记图标。
🌐 The following example shows how to display a custom marker icon with Google Maps on Android.
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 hook 返回的值。它不直接接受图片源。
加载的图片尺寸决定标记大小，而不是标记样式属性。对于 SVG 图标，请在 SVG 中设置 width、height 和 viewBox，或将 maxWidth 和 maxHeight 传递给 useImage 钩子。你可以使用 anchor 将自定义图标与其坐标对齐。
🌐 The loaded image dimensions determine the marker size, not a marker style prop. For SVG icons, set width, height, and viewBox in the SVG, or pass maxWidth and maxHeight to the useImage hook. You can use anchor to align custom icons with their coordinates.
以下示例显示了如何在 iOS 上使用 Apple 地图显示自定义标注图标。
🌐 The following example shows how to display a custom annotation icon with Apple Maps on iOS.
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.
权限
🌐 Permissions
安卓
🌐 Android
要在地图上显示用户的位置，expo-maps 库需要以下权限：
🌐 To show the user's location on the map, the expo-maps library requires the following permissions:
ACCESS_COARSE_LOCATION：用于近似设备位置ACCESS_FINE_LOCATION：用于精确定位设备
iOS
该库使用以下用法描述键：
🌐 The following usage description keys are used by this library: