This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo 地图 iconExpo 地图

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

Android
iOS
Recommended version:
~58.0.8

安装

🌐 Installation

Terminal
- npx expo install expo-maps
- yarn expo install expo-maps
- pnpm expo install expo-maps
- bun expo install expo-maps

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


观看:Expo 地图深度解析
观看:Expo 地图深度解析

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

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

app.json
{ "expo": { "plugins": [ [ "expo-maps", { "requestLocationPermission": true, "locationPermission": "Allow $(PRODUCT_NAME) to use your location" } ] ] } }

Configurable properties

NameDefaultDescription
requestLocationPermissionfalse

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 NSLocationWhenInUseUsageDescription permission message.

用法

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

应用接口

🌐 API

import { AppleMaps, GoogleMaps } from 'expo-maps'; // AppleMaps.View and GoogleMaps.View are the React components

No API data file found, sorry!

权限

🌐 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:用于精确定位设备
Android permissionDescription

ACCESS_COARSE_LOCATION

Allows an app to access approximate location.

ACCESS_FINE_LOCATION

Allows an app to access precise location.

FOREGROUND_SERVICE

Allows a regular application to use Service.startForeground.

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

iOS

该库使用以下用法描述键:

🌐 The following usage description keys are used by this library:

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.