This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 位置
一个库，可用于读取地理位置信息、轮询当前位置，或订阅设备的位置更新事件。
expo-location 可读取设备的地理位置信息。应用可以轮询当前位置，也可以订阅位置更新事件。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
在应用配置中进行配置
如果项目中使用了配置插件（持续原生生成（CNG）），则可以使用内置的配置插件配置 expo-location。该插件允许配置各种无法在运行时设置、且需要重新构建应用二进制文件才能生效的属性。如果应用不使用 CNG，则需要手动配置此库。
Example app.json with config plugin
Configurable properties
Are you using this library in an existing React Native app?
如果未使用持续原生生成（CNG），或手动使用原生 ios 项目，则需要将 NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription 和 NSLocationWhenInUseUsageDescription 键添加到项目的 ios/[app]/Info.plist 中：
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key> <string>Allow $(PRODUCT_NAME) to use your location</string> <key>NSLocationAlwaysUsageDescription</key> <string>Allow $(PRODUCT_NAME) to use your location</string> <key>NSLocationWhenInUseUsageDescription</key> <string>Allow $(PRODUCT_NAME) to use your location</string>
后台位置
后台位置功能允许应用在后台运行时接收位置更新，其中包括位置更新以及通过地理围栏进行的区域监控。此功能受平台 API 限制和系统约束：
- 用户终止应用后，后台位置功能将停止。
- 用户重新启动应用后，后台位置功能会恢复。
- Android由于平台限制，当发生位置或地理围栏事件时，已终止的应用不会自动重启。
- iOS发生新的地理围栏事件时，系统会重新启动已终止的应用。
信息 在 Android 上，从最近使用的应用列表中移除应用的结果因设备厂商而异。例如，某些实现会将从最近使用的应用列表中移除应用视为终止应用。点击此处了解更多相关差异：https://dontkillmyapp.com。
后台位置配置 iOS
若要在 iOS 上运行后台位置功能，需要将 location 值添加到应用 Info.plist 文件的 UIBackgroundModes 数组中。
如果使用 CNG，则预构建过程会自动应用所需的 UIBackgroundModes 配置。
在 iOS 上手动配置 UIBackgroundModes
如果未使用持续原生生成（CNG），或使用原生 iOS 项目，则需要将以下内容添加到 Expo.plist 文件中：
后台位置方法
使用后台位置方法需要满足以下要求：
- 必须已授予位置权限。
- 必须在顶层作用域中使用
TaskManager.defineTask定义后台位置任务。 - iOS必须在 Info.plist 文件中指定
"location"后台模式。请参阅后台位置配置。 - iOS由于 Expo Go 应用不支持后台位置功能，因此必须使用开发构建。
地理围栏方法
使用地理围栏方法需要满足以下要求：
- 必须已授予位置权限。
- 必须在顶层作用域中使用
TaskManager.defineTask定义地理围栏任务。
使用地理围栏时，以下平台差异适用：
- Android每个应用最多允许100 个活动地理围栏。
- iOSExpo Location 会在应用启动时报告已注册地理围栏的初始状态。
- iOS可同时监控的
regions数量上限为 20 个。
后台权限
若要在后台使用位置跟踪或地理围栏，必须请求相应权限：
- 在 Android 上，必须同时请求前台和后台权限。
- 在 iOS 上，必须通过
requestBackgroundPermissionsAsync并选择Always选项授予权限。
Expo 和 iOS 权限
iOS 权限分为 When In Use 和 Always 两类，分别对应 Expo 的前台和后台位置权限，通过以下方法请求：
requestForegroundPermissionsAsync对应When In UserequestBackgroundPermissionsAsync对应Always
注意： 请求
When In Use授权时，用户可以在系统权限对话框中选择Allow Once，授予临时访问权限。此授权仅在当前应用会话期间有效，并会在应用关闭时自动撤销。
检测“Allow Once”与“Allow While Using the App”
遗憾的是，iOS 无法检测用户选择的是 Allow Once 还是 Allow While Using the App。这两种选择都会授予 When In Use 授权。
如果用户选择了 Allow Once，并且随后在同一会话中调用 requestBackgroundPermissionsAsync，系统不会再次显示提示。相反，该请求会静默失败，返回的后台权限状态将为拒绝。
处理“Allow Once”场景
如果你认为用户选择了 Allow Once，并且需要请求后台权限，则用户必须在“设置”应用中手动启用后台位置。可以在应用中使用 Linking 打开“设置”应用：
import { Linking } from 'react-native'; function openSettings() { Linking.openURL('app-settings:'); }
分步请求权限
可以先请求前台位置访问权限，稍后再请求后台位置访问权限。这样可以仅在必要时请求权限，从而改善用户体验。
直接请求后台权限
如果在未先请求前台权限的情况下调用 requestBackgroundPermissionsAsync，iOS 会将其视为同时请求 When In Use 和 Always 授权。系统会先提示用户授予 When In Use 访问权限，并在系统判断需要 Always 授权时显示相应提示。
请记住，用户也可以选择只授予应用 When In Use 授权。你必须始终做好在仅有 When In Use 权限时运行的准备。
延迟位置更新
使用后台位置功能时，可以将位置管理器配置为延迟更新。这样可以降低更新频率，从而节省电量。你可以设置仅在设备移动特定距离或经过指定时间间隔后才触发更新。
可以通过 LocationTaskOptions 中的 deferredUpdatesDistance、deferredUpdatesInterval 和 deferredTimeout 属性配置延迟更新。
延迟位置更新仅在应用处于后台时生效。
用法
如果使用 Android Emulator 或 iOS Simulator，请确保已启用位置功能。
启用模拟器位置功能
Android Emulator
打开 Android Studio 并启动 Android Emulator。在模拟器中，前往 设置 > 位置，然后启用 使用位置信息。
如果模拟器未收到位置信息，可能需要关闭 提高位置精确度 设置。这样会关闭 Wi-Fi 定位，仅使用 GPS。然后，你便可以通过模拟器使用 GPS 数据调整位置。
对于 Android 12 及更高版本，前往 设置 > 位置 > 位置服务 > Google 位置精确度，然后关闭 提高位置精确度。对于 Android 11 及更低版本，前往 设置 > 位置 > 高级 > Google 位置精确度，然后关闭 Google 位置精确度。
iOS Simulator
打开 Device Hub 后，前往 设备 > 位置，并选择 无 以外的任一选项。
API
import * as Location from 'expo-location';
Hooks
Check or request permissions for the background location.
This uses both requestBackgroundPermissionsAsync and getBackgroundPermissionsAsync to
interact with the permissions.
[LocationPermissionResponse | null, RequestPermissionMethod<LocationPermissionResponse>, GetPermissionMethod<LocationPermissionResponse>]Example
const [status, requestPermission] = Location.useBackgroundPermissions();
Check or request permissions for the foreground location.
This uses both requestForegroundPermissionsAsync and getForegroundPermissionsAsync to interact with the permissions.
[LocationPermissionResponse | null, RequestPermissionMethod<LocationPermissionResponse>, GetPermissionMethod<LocationPermissionResponse>]Example
const [status, requestPermission] = Location.useForegroundPermissions();
Checks or requests permissions for motion activity detection.
This uses both requestMotionActivityPermissionsAsync and getMotionActivityPermissionsAsync
to interact with the permissions.
[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = Location.useMotionActivityPermissions();
Methods
Asks the user to turn on high accuracy location mode which enables network provider that uses Google Play services to improve location accuracy and location-based services.
Promise<void>A promise resolving as soon as the user accepts the dialog. Rejects if denied.
Geocode an address string to latitude-longitude location.
On Android, you must request location permissions with requestForegroundPermissionsAsync
before geocoding can be used.
Note: Geocoding is resource consuming and has to be used reasonably. Creating too many requests at a time can result in an error, so they have to be managed properly. It's also discouraged to use geocoding while the app is in the background and its results won't be shown to the user immediately.
Promise<LocationGeocodedLocation[]>A promise which fulfills with an array (in most cases its size is 1) of LocationGeocodedLocation
objects.
Checks user's permissions for accessing location while the app is in the background.
Promise<LocationPermissionResponse>A promise that fulfills with an object of type LocationPermissionResponse.
Requests for one-time delivery of the user's current location.
Depending on given accuracy option it may take some time to resolve,
especially when you're inside a building.
Note: Calling it causes the location manager to obtain a location fix which may take several seconds. Consider using
getLastKnownPositionAsyncif you expect to get a quick response and high accuracy is not required.
Promise<LocationObject>A promise which fulfills with an object of type LocationObject.
Checks user's permissions for accessing location while the app is in the foreground.
Promise<LocationPermissionResponse>A promise that fulfills with an object of type LocationPermissionResponse.
Gets the current heading information from the device. To simplify, it calls watchHeadingAsync
and waits for a couple of updates, and then returns the one that is accurate enough.
Promise<LocationHeadingObject>A promise which fulfills with an object of type LocationHeadingObject.
Gets the last known position of the device or null if it's not available or doesn't match given
requirements such as maximum age or required accuracy.
It's considered to be faster than getCurrentPositionAsync as it doesn't request for the current
location, but keep in mind the returned location may not be up-to-date.
Promise<LocationObject | null>A promise which fulfills with an object of type LocationObject or
null if it's not available or doesn't match given requirements such as maximum age or required
accuracy.
Fetches the current motion activity status of the device by subscribing to the first available
activity update and immediately unsubscribing afterwards.
The returned promise fulfills with the same object shape as the watchMotionActivityAsync
callback.
The method uses the Google Play Services activity
recognition (Android) or platform's motion coprocessor (iOS) and does not require location permissions.
On Android 10+, the ACTIVITY_RECOGNITION runtime permission must be granted beforehand.
On iOS, the system will prompt the user for Motion and Fitness access the first time this method is called.
Promise<MotionActivityObject>a promise which fulfills with a MotionActivityObject.
Checks user's permissions for accessing motion activity data.
Promise<PermissionResponse>A promise that fulfills with an object of type PermissionResponse.
Check status of location providers.
Promise<LocationProviderStatus>A promise which fulfills with an object of type LocationProviderStatus.
Checks whether location services are enabled by the user.
Promise<boolean>A promise which fulfills to true if location services are enabled on the device,
or false if not.
Promise<boolean>A promise which fulfills with boolean value indicating whether the geofencing task is started or not.
Promise<boolean>A promise which fulfills with boolean value indicating whether the location task is started or not.
Polyfills navigator.geolocation for interop with the core React Native and Web API approach to geolocation.
voidPromise<boolean>Asks the user to grant permissions for location while the app is in the background.
On Android 11 or higher: this method will open the system settings page - before that happens
you should explain to the user why your application needs background location permission.
For example, you can use Modal component from react-native to do that.
Note: Foreground permissions should be granted before asking for the background permissions (your app can't obtain background permission without foreground permission).
Promise<LocationPermissionResponse>A promise that fulfills with an object of type LocationPermissionResponse.
Asks the user to grant permissions for location while the app is in the foreground.
Promise<LocationPermissionResponse>A promise that fulfills with an object of type LocationPermissionResponse.
Asks the user to grant permissions for motion activity detection.
On Android 10+, this requests the ACTIVITY_RECOGNITION runtime permission.
On iOS, this triggers the system prompt for Motion and Fitness access the first time it is called.
Promise<PermissionResponse>a promise that fulfills with an object of type PermissionResponse.
Reverse geocode a location to postal address.
On Android, you must request location permissions with requestForegroundPermissionsAsync
before geocoding can be used.
Note: Geocoding is resource consuming and has to be used reasonably. Creating too many requests at a time can result in an error, so they have to be managed properly. It's also discouraged to use geocoding while the app is in the background and its results won't be shown to the user immediately.
Promise<LocationGeocodedAddress[]>A promise which fulfills with an array (in most cases its size is 1) of LocationGeocodedAddress objects.
Starts geofencing for given regions. When the new event comes, the task with specified name will
be called with the region that the device enter to or exit from.
If you want to add or remove regions from already running geofencing task, you can just call
startGeofencingAsync again with the new array of regions.
Task parameters
Geofencing task will be receiving following data:
eventType- Indicates the reason for calling the task, which can be triggered by entering or exiting the region. SeeGeofencingEventType.region- Object containing details about updated region. SeeLocationRegionfor more details.
Promise<void>A promise resolving as soon as the task is registered.
Example
import { GeofencingEventType } from 'expo-location'; import * as TaskManager from 'expo-task-manager'; TaskManager.defineTask(YOUR_TASK_NAME, ({ data: { eventType, region }, error }) => { if (error) { // check `error.message` for more details. return; } if (eventType === GeofencingEventType.Enter) { console.log("You've entered region:", region); } else if (eventType === GeofencingEventType.Exit) { console.log("You've left region:", region); } });
Registers for receiving location updates that can also come when the app is in the background.
Task parameters
Background location task will be receiving following data:
locations- An array of the new locations.
Promise<void>A promise resolving once the task with location updates is registered.
Example
import * as TaskManager from 'expo-task-manager'; TaskManager.defineTask(YOUR_TASK_NAME, ({ data: { locations }, error }) => { if (error) { // check `error.message` for more details. return; } console.log('Received new locations', locations); });
Stops geofencing for specified task. It unregisters the background task so the app will not be receiving any updates, especially in the background.
Promise<void>A promise resolving as soon as the task is unregistered.
Stops location updates for specified task.
Promise<void>A promise resolving as soon as the task is unregistered.
Subscribe to compass updates from the device.
Promise<LocationSubscription>A promise which fulfills with a LocationSubscription object.
Subscribes to motion activity updates from the device. The callback fires whenever the platform's motion coprocessor detects a change in the user's activity. Only foreground use is supported - updates pause when the app is backgrounded and resume when it returns to the foreground.
Promise<LocationSubscription>a promise which fulfills with a LocationSubscription object.
Subscribe to location updates from the device. Updates will only occur while the application is in
the foreground. To get location updates while in background you'll need to use
startLocationUpdatesAsync.
Promise<LocationSubscription>A promise which fulfills with a LocationSubscription object.
Types
Type of the object containing heading details and provided by watchHeadingAsync callback.
Type representing options object that can be passed to getLastKnownPositionAsync.
LocationPermissionResponse extends PermissionResponse
type exported by expo-modules-core and contains additional platform-specific fields.
Type: PermissionResponse extended by:
Represents the object containing details about location provider.
Represents subscription object returned by methods watching for new locations or headings.
Represents the watchMotionActivityAsync callback.
any
Type returned by getMotionActivityAsync and the watchMotionActivityAsync callback.
Contains one entry per MotionActivityType so callers can inspect each activity
independently without searching through an array.
Example
const { activities } = await Location.getMotionActivityAsync(); if (activities.automotive.detected) { console.log('driving, confidence:', activities.automotive.confidence); }
Detection state for a single activity type.
When detected is false, confidence is always Low.
Literal type: union
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never' | number
Literal type: union
Acceptable values are: PermissionHookBehavior | Options
Enums
Enum with available location accuracies.
Enum with available activity types of background location tracking.
ActivityType.Other ＝ 1Default activity type. Use it if there is no other type that matches the activity you track.
ActivityType.AutomotiveNavigation ＝ 2Location updates are being used specifically during vehicular navigation to track location changes to the automobile.
ActivityType.Fitness ＝ 3Use this activity type if you track fitness activities such as walking, running, cycling, and so on.
ActivityType.OtherNavigation ＝ 4Activity type for movements for other types of vehicular navigation that are not automobile related.
A type of the event that geofencing task can receive.
State of the geofencing region that you receive through the geofencing task.
GeofencingRegionState.Unknown ＝ 0Indicates that the device position related to the region is unknown.
Confidence level for motion activity detection. On Android, the raw DetectedActivity confidence (0-
100) is bucketed into these three levels. On iOS, maps directly to CMMotionActivityConfidence.
The type of physical activity the user is currently performing.
On Android it maps to DetectedActivity constants from Google Play Services.
On iOS this maps to the boolean properties of CMMotionActivity (the highest-priority
truthy property wins).
MotionActivityType.Automotive ＝ "automotive"The device is in a motorized vehicle (car, bus, train, and so on).
权限
Android
警告 Expo Go for Android 不支持前台和后台服务。为避免受到限制，我们建议使用开发构建。
安装 expo-location 模块时，它会自动添加以下权限：
ACCESS_COARSE_LOCATION：用于获取设备的大致位置ACCESS_FINE_LOCATION：用于获取设备的精确位置
以下权限是可选的：
FOREGROUND_SERVICE和FOREGROUND_SERVICE_LOCATION：用于在应用打开但处于后台时访问位置。Android 14 起才需要FOREGROUND_SERVICE_LOCATION。在新构建中启用此权限后，需要提交应用以供审核，并申请使用前台服务权限。ACCESS_BACKGROUND_LOCATION：用于在应用处于后台或关闭时访问位置。在新构建中启用此权限后，需要提交应用以供审核，并申请使用后台位置权限。
排除权限
注意：从应用中的模块排除必需权限可能会破坏与该权限对应的功能。请始终确保包含模块所依赖的所有权限。
如果 Expo 项目不需要某项权限，可以将其省略。例如，如果应用不需要访问精确位置，则可以排除 ACCESS_FINE_LOCATION 权限。
另一个例子是使用可用的位置精度等级。Android 将大致位置精度估算为约 3 平方公里范围，将精确位置精度估算为约 50 米范围。例如，如果位置精度值为低，则可以排除 ACCESS_FINE_LOCATION 权限。若要详细了解位置精度等级，请参阅 Android 文档。
若要详细了解如何排除权限，请参阅排除 Android 权限。
iOS
此库使用以下用法描述键：
从 iOS 11 开始，NSLocationAlwaysUsageDescription 已被 NSLocationAlwaysAndWhenInUseUsageDescription 取代。