This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

Expo 位置

一个提供访问地理位置信息、轮询当前位置或订阅设备位置更新事件的库。

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

expo-location 允许从设备读取地理位置信息。你的应用可以轮询当前位置信息，或者订阅位置更新事件。

安装

Terminal

- npx expo install expo-location

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

在 app 配置中进行配置

如果你的项目使用 config plugins（Continuous Native Generation (CNG)），你可以使用 expo-location 内置的 config plugin 来进行配置。该插件允许你配置一些无法在运行时设置、且需要构建新的应用二进制文件才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "locationAlwaysAndWhenInUsePermission": "允许 $(PRODUCT_NAME) 使用你的位置信息。"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`locationAlwaysAndWhenInUsePermission`	`"允许 $(PRODUCT_NAME) 使用你的位置信息"`	Only for: iOS 用于设置 `NSLocationAlwaysAndWhenInUseUsageDescription` 权限提示信息的字符串。
`locationAlwaysPermission`	`"允许 $(PRODUCT_NAME) 使用你的位置信息"`	Deprecated • Only for: iOS 用于设置 `NSLocationAlwaysUsageDescription` 权限提示信息的字符串。
`locationWhenInUsePermission`	`"允许 $(PRODUCT_NAME) 使用你的位置信息"`	Only for: iOS 用于设置 `NSLocationWhenInUseUsageDescription` 权限提示信息的字符串。
`isIosBackgroundLocationEnabled`	`false`	Only for: iOS 一个布尔值，用于在 Info.plist 的 `UIBackgroundModes` 中启用 `location`。
`isAndroidBackgroundLocationEnabled`	`false`	Only for: Android 一个布尔值，用于启用 `ACCESS_BACKGROUND_LOCATION` 权限。
`isAndroidForegroundServiceEnabled`	-	Only for: Android 一个布尔值，用于启用 `FOREGROUND_SERVICE` 权限和 `FOREGROUND_SERVICE_LOCATION`。如果 `isAndroidBackgroundLocationEnabled` 为 `true`，默认值为 `true`，否则为 `false`。
`androidForegroundServiceIcon`	-	Only for: Android 用于作为 `startLocationUpdatesAsync` 启动的前台服务图标的本地图片路径。要求为 96x96、全白色、带透明通道的 png 图片。如果未设置，则会回退到 `notification_icon` drawable（如果已通过 `expo-notifications` config plugin 配置），再回退到应用启动图标。启动图标是全彩色的，并且由于 Android 要求通知图标必须是单色的，因此可能会渲染成纯白色方块。

Are you using this library in an existing React Native app?

如果你没有使用 Continuous Native Generation (CNG)，或者你是手动使用原生 ios 项目，那么你需要将 NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription 和 NSLocationWhenInUseUsageDescription 键添加到项目的 ios/[app]/Info.plist 中：

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>允许 $(PRODUCT_NAME) 使用你的位置信息</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>允许 $(PRODUCT_NAME) 使用你的位置信息</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>允许 $(PRODUCT_NAME) 使用你的位置信息</string>

后台位置

后台位置允许你的应用在后台运行时接收位置更新，并且包括通过地理围栏进行的位置更新和区域监测。此功能受平台 API 限制和系统约束影响：

当用户终止应用时，后台位置会停止。
当用户重新启动应用时，后台位置会恢复。
Android
由于平台限制，终止的应用在发生位置或地理围栏事件时不会自动重启。
iOS
当新的地理围栏事件发生时，系统会重启已终止的应用。

信息在 Android 上，将应用从最近任务列表中移除的结果因设备厂商而异。例如，有些实现会将其视为杀死应用。更多关于这些差异的信息请见：https://dontkillmyapp.com。

后台位置配置
iOS

要在 iOS 上运行后台位置，你需要在应用的 Info.plist 文件中的 UIBackgroundModes 数组里添加 location 值。

如果你使用的是 CNG，所需的 UIBackgroundModes 配置会在 prebuild 过程中自动应用。

在 iOS 上手动配置 UIBackgroundModes

如果你没有使用 Continuous Native Generation (CNG)，或者你正在使用原生 iOS 项目，那么你需要将以下内容添加到 Expo.plist 文件中：

ios/project-name/Supporting/Expo.plist

<key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>

后台位置方法

要使用后台位置方法，需要满足以下要求：

必须授予位置权限。
必须在顶层作用域中使用 TaskManager.defineTask 定义后台位置任务。
iOS
必须在 Info.plist 文件中指定 "location" 后台模式。请参阅后台位置配置。
iOS
由于 Expo Go 应用不支持后台位置，因此你必须使用开发构建来使用后台位置。

地理围栏方法

要使用地理围栏方法，需要满足以下要求：

必须授予位置权限。
必须在顶层作用域中使用 TaskManager.defineTask 定义地理围栏任务。

使用地理围栏时，适用以下平台差异：

Android
每个应用最多允许100 个活动地理围栏。
iOS
Expo Location 会在应用启动时报告已注册地理围栏的初始状态。
iOS
可同时监测的 regions 数量上限为 20。

后台权限

要在后台使用位置跟踪或地理围栏，你必须请求相应的权限：

在 Android 上，你必须同时请求前台和后台权限。
在 iOS 上，必须使用 requestBackgroundPermissionsAsync 以 Always 选项授予权限。

Expo 和 iOS 权限

iOS 权限分为 When In Use 和 Always 两类，并映射到 Expo 请求的前台和后台位置权限：

requestForegroundPermissionsAsync 对应 When In Use
requestBackgroundPermissionsAsync 对应 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 授权时，会显示 Always 授权提示。

请记住，用户也可以选择仅授予你的应用 When In Use 授权。你必须始终准备好在 When In Use 权限下运行。

延迟位置

在使用后台位置时，你可以配置位置管理器以延迟更新。这通过降低更新频率有助于节省电量。你可以将更新设置为仅在设备移动了某个距离后，或在经过指定时间间隔后触发。

延迟更新通过 LocationTaskOptions 进行配置，使用 deferredUpdatesDistance、deferredUpdatesInterval 和 deferredTimeout 属性。

延迟位置仅在应用处于后台时适用。

用法

如果你正在使用 Android 模拟器或 iOS 模拟器，请确保已启用位置。

位置

import { useState, useEffect } from 'react';
import { Platform, Text, View, StyleSheet } from 'react-native';
%%placeholder-start%%%%placeholder-end%%import * as Device from 'expo-device';
import * as Location from 'expo-location';

export default function App() {
  const [location, setLocation] = useState<Location.LocationObject | null>(null);
  const [errorMsg, setErrorMsg] = useState<string | null>(null);

  useEffect(() => {
    async function getCurrentLocation() {
      %%placeholder-start%%%%placeholder-end%%if (Platform.OS === 'android' && !Device.isDevice) {
        setErrorMsg(
          '糟糕，这在 Android 模拟器中的 Snack 上无法运行。请在你的设备上尝试！'
        );
        return;
      }
      let { status } = await Location.requestForegroundPermissionsAsync();
      if (status !== 'granted') {
        setErrorMsg('访问位置的权限被拒绝');
        return;
      }

      let location = await Location.getCurrentPositionAsync({});
      setLocation(location);
    }

    getCurrentLocation();
  }, []);

  let text = '等待中...';
  if (errorMsg) {
    text = errorMsg;
  } else if (location) {
    text = JSON.stringify(location);
  }

  return (
    <View style={styles.container}>
      <Text style={styles.paragraph}>{text}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 20,
  },
  paragraph: {
    fontSize: 18,
    textAlign: 'center',
  },
});

启用模拟器位置

Android 模拟器

打开 Android Studio，并启动 Android 模拟器。在其中，进入设置 > 位置，并启用使用位置。

如果你没有在模拟器中接收到位置，你可能需要关闭提高位置精度设置。这将关闭 Wi-Fi 定位并且仅使用 GPS。然后你可以通过模拟器使用 GPS 数据来操控位置。

对于 Android 12 及更高版本，进入设置 > 位置 > 位置服务 > Google 位置精度，并关闭提高位置精度。对于 Android 11 及更低版本，进入设置 > 位置 > 高级 > Google 位置精度，并关闭 Google 位置精度。

iOS 模拟器

在模拟器打开的情况下，进入功能 > 位置，并选择除无之外的任意选项。

API

import * as Location from 'expo-location';

Hooks

`useBackgroundPermissions(options)`

Android

iOS

Web

Parameter	Type
options(optional)	`PermissionHookOptions<object>`

Check or request permissions for the background location. This uses both requestBackgroundPermissionsAsync and getBackgroundPermissionsAsync to interact with the permissions.

Returns:

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

Example

const [status, requestPermission] = Location.useBackgroundPermissions();

`useForegroundPermissions(options)`

Android

iOS

Web

Parameter	Type
options(optional)	`PermissionHookOptions<object>`

Check or request permissions for the foreground location. This uses both requestForegroundPermissionsAsync and getForegroundPermissionsAsync to interact with the permissions.

Returns:

[LocationPermissionResponse | null, RequestPermissionMethod<LocationPermissionResponse>, GetPermissionMethod<LocationPermissionResponse>]

Example

const [status, requestPermission] = Location.useForegroundPermissions();

Methods

`Location.enableNetworkProviderAsync()`

Android

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.

Returns:

Promise<void>

A promise resolving as soon as the user accepts the dialog. Rejects if denied.

`Location.geocodeAsync(address)`

Android

iOS

Parameter	Type	Description
address	`string`	A string representing address, eg. `"Baker Street London"`.

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.

Returns:

Promise<LocationGeocodedLocation[]>

A promise which fulfills with an array (in most cases its size is 1) of LocationGeocodedLocation objects.

`Location.getBackgroundPermissionsAsync()`

Android

iOS

Web

Checks user's permissions for accessing location while the app is in the background.

Returns:

Promise<PermissionResponse>

A promise that fulfills with an object of type PermissionResponse.

`Location.getCurrentPositionAsync(options)`

Android

iOS

Web

Parameter	Type
options(optional)	`LocationOptions`

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 getLastKnownPositionAsync if you expect to get a quick response and high accuracy is not required.

Returns:

Promise<LocationObject>

A promise which fulfills with an object of type LocationObject.

`Location.getForegroundPermissionsAsync()`

Android

iOS

Web

Checks user's permissions for accessing location while the app is in the foreground.

Returns:

Promise<LocationPermissionResponse>

A promise that fulfills with an object of type LocationPermissionResponse.

`Location.getHeadingAsync()`

Android

iOS

Web

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.

Returns:

Promise<LocationHeadingObject>

A promise which fulfills with an object of type LocationHeadingObject.

`Location.getLastKnownPositionAsync(options)`

Android

iOS

Web

Parameter	Type
options(optional)	`LocationLastKnownOptions`

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.

Returns:

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.

`Location.getProviderStatusAsync()`

Android

iOS

Web

Check status of location providers.

Returns:

Promise<LocationProviderStatus>

A promise which fulfills with an object of type LocationProviderStatus.

`Location.hasServicesEnabledAsync()`

Android

iOS

Web

Checks whether location services are enabled by the user.

Returns:

Promise<boolean>

A promise which fulfills to true if location services are enabled on the device, or false if not.

`Location.hasStartedGeofencingAsync(taskName)`

Android

iOS

Web

Parameter	Type	Description
taskName	`string`	Name of the geofencing task to check.

Returns:

Promise<boolean>

A promise which fulfills with boolean value indicating whether the geofencing task is started or not.

`Location.hasStartedLocationUpdatesAsync(taskName)`

Android

iOS

Web

Parameter	Type	Description
taskName	`string`	Name of the location task to check.

Returns:

Promise<boolean>

A promise which fulfills with boolean value indicating whether the location task is started or not.

`Location.installWebGeolocationPolyfill()`

Android

iOS

Web

Polyfills navigator.geolocation for interop with the core React Native and Web API approach to geolocation.

Returns:

void

`Location.isBackgroundLocationAvailableAsync()`

Android

iOS

Web

Returns:

Promise<boolean>

`Location.requestBackgroundPermissionsAsync()`

Android

iOS

Web

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

Returns:

Promise<PermissionResponse>

A promise that fulfills with an object of type PermissionResponse.

`Location.requestForegroundPermissionsAsync()`

Android

iOS

Web

Asks the user to grant permissions for location while the app is in the foreground.

Returns:

Promise<LocationPermissionResponse>

A promise that fulfills with an object of type LocationPermissionResponse.

`Location.reverseGeocodeAsync(location)`

Android

iOS

Parameter	Type	Description
location	`Pick<LocationGeocodedLocation, 'latitude' \| 'longitude'>`	An object representing a location.

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.

Returns:

Promise<LocationGeocodedAddress[]>

A promise which fulfills with an array (in most cases its size is 1) of LocationGeocodedAddress objects.

`Location.startGeofencingAsync(taskName, regions)`

Android

iOS

Web

Parameter	Type	Description
taskName	`string`	Name of the task that will be called when the device enters or exits from specified regions.
regions(optional)	`LocationRegion[]`	Array of region objects to be geofenced. Default:`[]`

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. See GeofencingEventType.
region - Object containing details about updated region. See LocationRegion for more details.

Returns:

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

`Location.startLocationUpdatesAsync(taskName, options)`

Android

iOS

Web

Parameter	Type	Description
taskName	`string`	Name of the task receiving location updates.
options(optional)	`LocationTaskOptions`	An object of options passed to the location manager.

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.

Returns:

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

`Location.stopGeofencingAsync(taskName)`

Android

iOS

Web

Parameter	Type	Description
taskName	`string`	Name of the task to unregister.

Stops geofencing for specified task. It unregisters the background task so the app will not be receiving any updates, especially in the background.

Returns:

Promise<void>

A promise resolving as soon as the task is unregistered.

`Location.stopLocationUpdatesAsync(taskName)`

Android

iOS

Web

Parameter	Type	Description
taskName	`string`	Name of the background location task to stop.

Stops location updates for specified task.

Returns:

Promise<void>

A promise resolving as soon as the task is unregistered.

`Location.watchHeadingAsync(callback, errorHandler)`

Android

iOS

Parameter	Type	Description
callback	`LocationHeadingCallback`	This function is called on each compass update. It receives an object of type LocationHeadingObject as the first argument.
errorHandler(optional)	`LocationErrorCallback`	This function is called when an error occurs. It receives a string with the error message as the first argument.

Subscribe to compass updates from the device.

Returns:

Promise<LocationSubscription>

A promise which fulfills with a LocationSubscription object.

`Location.watchPositionAsync(options, callback, errorHandler)`

Android

iOS

Web

Parameter	Type	Description
options	`LocationOptions`	-
callback	`LocationCallback`	This function is called on each location update. It receives an object of type `LocationObject` as the first argument.
errorHandler(optional)	`LocationErrorCallback`	This function is called when an error occurs. It receives a string with the error message as the first argument.

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.

Returns:

Promise<LocationSubscription>

A promise which fulfills with a LocationSubscription object.

Types

`LocationCallback(location)`

Android

iOS

Web

Represents watchPositionAsync callback.

Parameter	Type
location	`LocationObject`

Returns:

any

`LocationErrorCallback(reason)`

Android

iOS

Web

Error callback for location methods.

Parameter	Type
reason	`string`

Returns:

void

`LocationGeocodedAddress`

Android

iOS

Web

Type representing a result of reverseGeocodeAsync.

Property	Type	Description
city	`string \| null`	City name of the address.
country	`string \| null`	Localized country name of the address.
district	`string \| null`	Additional city-level information like district name.
formattedAddress	`string \| null`	Only for: Android Composed string of the address components, for example, "111 8th Avenue, New York, NY".
isoCountryCode	`string \| null`	Localized (ISO) country code of the address, if available.
name	`string \| null`	The name of the placemark, for example, "Tower Bridge".
postalCode	`string \| null`	Postal code of the address.
region	`string \| null`	The state or province associated with the address.
street	`string \| null`	Street name of the address.
streetNumber	`string \| null`	Street number of the address.
subregion	`string \| null`	Additional information about administrative area.
timezone	`string \| null`	Only for: iOS The timezone identifier associated with the address.

`LocationGeocodedLocation`

Android

iOS

Web

Type representing a result of geocodeAsync.

Property	Type	Description
accuracy(optional)	`number`	The radius of uncertainty for the location, measured in meters.
altitude(optional)	`number`	The altitude in meters above the WGS 84 reference ellipsoid.
latitude	`number`	The latitude in degrees.
longitude	`number`	The longitude in degrees.

`LocationHeadingCallback(location)`

Android

iOS

Web

Represents watchHeadingAsync callback.

Parameter	Type
location	`LocationHeadingObject`

Returns:

any

`LocationHeadingObject`

Android

iOS

Web

Type of the object containing heading details and provided by watchHeadingAsync callback.

Property	Type	Description
accuracy	`number`	Level of calibration of compass: `3`: high accuracy `2`: medium accuracy `1`: low accuracy `0`: none Reference for iOS: `3`: < 20 degrees uncertainty `2`: < 35 degrees `1`: < 50 degrees `0`: > 50 degrees
magHeading	`number`	Measure of magnetic north in degrees.
trueHeading	`number`	Measure of true north in degrees (needs location permissions, will return `-1` if not given).

`LocationLastKnownOptions`

Android

iOS

Web

Type representing options object that can be passed to getLastKnownPositionAsync.

Property	Type	Description
maxAge(optional)	`number`	A number of milliseconds after which the last known location starts to be invalid and thus `null` is returned.
requiredAccuracy(optional)	`number`	The maximum radius of uncertainty for the location, measured in meters. If the last known location's accuracy radius is bigger (less accurate) then `null` is returned.

`LocationObject`

Android

iOS

Web

Type representing the location object.

Property	Type	Description
coords	`LocationObjectCoords`	The coordinates of the position.
mocked(optional)	`boolean`	Only for: Android Whether the location coordinates is mocked or not.
timestamp	`number`	The time at which this position information was obtained, in milliseconds since epoch.

`LocationObjectCoords`

Android

iOS

Web

Type representing the location GPS related data.

Property	Type	Description
accuracy	`number \| null`	The radius of uncertainty for the location, measured in meters. Can be `null` on Web if it's not available.
altitude	`number \| null`	The altitude in meters above the WGS 84 reference ellipsoid. Can be `null` on Web if it's not available.
altitudeAccuracy	`number \| null`	The accuracy of the altitude value, in meters. Can be `null` on Web if it's not available.
heading	`number \| null`	Horizontal direction of travel of this device, measured in degrees starting at due north and continuing clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on. Can be `null` on Web if it's not available.
latitude	`number`	The latitude in degrees.
longitude	`number`	The longitude in degrees.
speed	`number \| null`	The instantaneous speed of the device in meters per second. Can be `null` on Web if it's not available.

`LocationOptions`

Android

iOS

Web

Type representing options argument in getCurrentPositionAsync.

Property	Type	Description
accuracy(optional)	`Accuracy`	Location manager accuracy. Pass one of `Accuracy` enum values. For low-accuracies the implementation can avoid geolocation providers that consume a significant amount of power (such as GPS). Default:`LocationAccuracy.Balanced`
distanceInterval(optional)	`number`	Receive updates only when the location has changed by at least this distance in meters. Default value may depend on `accuracy` option.
mayShowUserSettingsDialog(optional)	`boolean`	Only for: Android Specifies whether to ask the user to turn on improved accuracy location mode which uses Wi-Fi, cell networks and GPS sensor. Default:`true`
timeInterval(optional)	`number`	Only for: Android Minimum time to wait between each update in milliseconds. Default value may depend on `accuracy` option.

`LocationPermissionResponse`

Android

iOS

Web

LocationPermissionResponse extends PermissionResponse type exported by expo-modules-core and contains additional platform-specific fields.

Type: PermissionResponse extended by:

Property	Type	Description
android(optional)	`PermissionDetailsLocationAndroid`	-
ios(optional)	`PermissionDetailsLocationIOS`	-

`LocationProviderStatus`

Android

iOS

Web

Represents the object containing details about location provider.

Property	Type	Description
backgroundModeEnabled	`boolean`	-
gpsAvailable(optional)	`boolean`	Only for: Android Whether the GPS provider is available. If `true` the location data will come from GPS, especially for requests with high accuracy.
locationServicesEnabled	`boolean`	Whether location services are enabled. See Location.hasServicesEnabledAsync for a more convenient solution to get this value.
networkAvailable(optional)	`boolean`	Only for: Android Whether the network provider is available. If `true` the location data will come from cellular network, especially for requests with low accuracy.
passiveAvailable(optional)	`boolean`	Only for: Android Whether the passive provider is available. If `true` the location data will be determined passively.

`LocationRegion`

Android

iOS

Web

Type representing geofencing region object.

Property	Type	Description
identifier(optional)	`string`	The identifier of the region object. Defaults to auto-generated UUID hash.
latitude	`number`	The latitude in degrees of region's center point.
longitude	`number`	The longitude in degrees of region's center point.
notifyOnEnter(optional)	`boolean`	Boolean value whether to call the task if the device enters the region. Default:`true`
notifyOnExit(optional)	`boolean`	Boolean value whether to call the task if the device exits the region. Default:`true`
radius	`number`	The radius measured in meters that defines the region's outer boundary.
state(optional)	`GeofencingRegionState`	One of GeofencingRegionState region state. Determines whether the device is inside or outside a region.

`LocationSubscription`

Android

iOS

Web

Represents subscription object returned by methods watching for new locations or headings.

Property	Type	Description
remove	`() => void`	Call this function with no arguments to remove this subscription. The callback will no longer be called for location updates.

`LocationTaskOptions`

Android

iOS

Web

Type representing background location task options.

Type: LocationOptions extended by:

Property	Type	Description
activityType(optional)	`ActivityType`	Only for: iOS The type of user activity associated with the location updates. Default:`ActivityType.Other` See: See Apple docs for more details.
deferredUpdatesDistance(optional)	`number`	The distance in meters that must occur between last reported location and the current location before deferred locations are reported. Default:`0`
deferredUpdatesInterval(optional)	`number`	Minimum time interval in milliseconds that must pass since last reported location before all later locations are reported in a batched update Default:`0`
deferredUpdatesTimeout(optional)	`number`	-
foregroundService(optional)	`LocationTaskServiceOptions`	-
pausesUpdatesAutomatically(optional)	`boolean`	Only for: iOS A boolean value indicating whether the location manager can pause location updates to improve battery life without sacrificing location data. When this option is set to `true`, the location manager pauses updates (and powers down the appropriate hardware) at times when the location data is unlikely to change. You can help the determination of when to pause location updates by assigning a value to the `activityType` property. Default:`false`
showsBackgroundLocationIndicator(optional)	`boolean`	Only for: iOS A boolean indicating whether the status bar changes its appearance when location services are used in the background. Default:`false`

`LocationTaskServiceOptions`

Android

iOS

Web

Property	Type	Description
killServiceOnDestroy(optional)	`boolean`	Boolean value whether to destroy the foreground service if the app is killed.
notificationBody	`string`	Subtitle of the foreground service notification.
notificationColor(optional)	`string`	Color of the foreground service notification. Accepts `#RRGGBB` and `#AARRGGBB` hex formats.
notificationTitle	`string`	Title of the foreground service notification.

`PermissionDetailsLocationAndroid`

Android

iOS

Web

Property	Type	Description
accuracy	`'fine' \| 'coarse' \| 'none'`	Indicates the type of location provider.

`PermissionDetailsLocationIOS`

Android

iOS

Web

Property	Type	Description
accuracy	`'full' \| 'reduced'`	Only for: iOS 14+ The accuracy authorization granted by the user. `'full'` means the user has granted precise location access, `'reduced'` means the app can only access approximate location. Below iOS 14 always returns `'full'`.
scope	`'whenInUse' \| 'always' \| 'none'`	The scope of granted permission. Indicates when it's possible to use location.

`PermissionExpiration`

Android

iOS

Web

Literal Type: union

Permission expiration time. Currently, all permissions are granted permanently.

Acceptable values are: 'never' | number

`PermissionHookOptions`

Android

iOS

Web

Literal Type: union

Acceptable values are: PermissionHookBehavior | Options

`PermissionResponse`

Android

iOS

Web

An object obtained by permissions get and request functions.

Property	Type	Description
canAskAgain	`boolean`	Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission.
expires	`PermissionExpiration`	Determines time when the permission expires.
granted	`boolean`	A convenience boolean that indicates if the permission is granted.
status	`PermissionStatus`	Determines the status of the permission.

Enums

`Accuracy`

Android

iOS

Web

Enum with available location accuracies.

`Lowest`

Accuracy.Lowest ＝ 1

Accurate to the nearest three kilometers.

`Low`

Accuracy.Low ＝ 2

Accurate to the nearest kilometer.

`Balanced`

Accuracy.Balanced ＝ 3

Accurate to within one hundred meters.

`High`

Accuracy.High ＝ 4

Accurate to within ten meters of the desired target.

`Highest`

Accuracy.Highest ＝ 5

The best level of accuracy available.

`BestForNavigation`

Accuracy.BestForNavigation ＝ 6

The highest possible accuracy that uses additional sensor data to facilitate navigation apps.

`ActivityType`

Android

iOS

Web

Enum with available activity types of background location tracking.

`Other`

ActivityType.Other ＝ 1

Default activity type. Use it if there is no other type that matches the activity you track.

`AutomotiveNavigation`

ActivityType.AutomotiveNavigation ＝ 2

Location updates are being used specifically during vehicular navigation to track location changes to the automobile.

`Fitness`

ActivityType.Fitness ＝ 3

Use this activity type if you track fitness activities such as walking, running, cycling, and so on.

`OtherNavigation`

ActivityType.OtherNavigation ＝ 4

Activity type for movements for other types of vehicular navigation that are not automobile related.

`Airborne`

iOS

ActivityType.Airborne ＝ 5

Intended for airborne activities. Fall backs to ActivityType.Other if unsupported.

`GeofencingEventType`

Android

iOS

Web

A type of the event that geofencing task can receive.

`Enter`

GeofencingEventType.Enter ＝ 1

Emitted when the device entered observed region.

`Exit`

GeofencingEventType.Exit ＝ 2

Occurs as soon as the device left observed region

`GeofencingRegionState`

Android

iOS

Web

State of the geofencing region that you receive through the geofencing task.

`Unknown`

GeofencingRegionState.Unknown ＝ 0

Indicates that the device position related to the region is unknown.

`Inside`

GeofencingRegionState.Inside ＝ 1

Indicates that the device is inside the region.

`Outside`

GeofencingRegionState.Outside ＝ 2

Inverse of inside state.

`PermissionStatus`

Android

iOS

Web

`DENIED`

PermissionStatus.DENIED ＝ "denied"

User has denied the permission.

`GRANTED`

PermissionStatus.GRANTED ＝ "granted"

User has granted the permission.

`UNDETERMINED`

PermissionStatus.UNDETERMINED ＝ "undetermined"

User hasn't granted or denied the permission yet.

权限

Android

警告 Expo Go for Android 中不提供前台和后台服务。作为替代，我们建议使用开发构建以避免限制。

当你安装 expo-location 模块时，它会自动添加以下权限：

ACCESS_COARSE_LOCATION：用于近似设备位置
ACCESS_FINE_LOCATION：用于精确设备位置

以下权限是可选的：

FOREGROUND_SERVICE 和 FOREGROUND_SERVICE_LOCATION：用于在应用打开但处于后台时访问位置。FOREGROUND_SERVICE_LOCATION 仅从 Android 14 开始需要。当你在新构建中启用此项时，你需要提交应用进行审核并申请使用前台服务权限。
ACCESS_BACKGROUND_LOCATION：用于在应用处于后台或关闭时访问位置。当你在新构建中启用此项时，你需要提交应用进行审核并申请使用后台位置权限。

Android Permission	Description
`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.

排除权限

注意：在你的应用中从某个模块排除一个必需权限可能会破坏该权限对应的功能。请始终确保包含模块所依赖的所有权限。

当你的 Expo 项目从包含某些特定权限中无法获益时，你可以省略它。例如，如果你的应用不需要访问精确位置，你可以排除 ACCESS_FINE_LOCATION 权限。

另一个示例可以使用可用的位置精度来说明。Android 将近似位置精度估计定义为约 3 平方公里，将精确位置精度估计定义为约 50 米。例如，如果位置精度值为 Low，你可以排除 ACCESS_FINE_LOCATION 权限。要了解有关位置精度级别的更多信息，请参阅Android 文档。

要进一步了解如何排除权限，请参阅排除 Android 权限。

iOS

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

Info.plist Key	Description
`NSLocationAlwaysAndWhenInUseUsageDescription`	A message that tells the user why the app is requesting access to the user’s location information at all times.
`NSLocationAlwaysUsageDescription`	A message that tells the user why the app is requesting access to the user's location at all times.DeprecatedFor apps deployed to targets in iOS 11 and later, use NSLocationAlwaysAndWhenInUseUsageDescription instead.
`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.

自 iOS 11 起，NSLocationAlwaysUsageDescription 已被弃用，推荐使用 NSLocationAlwaysAndWhenInUseUsageDescription。

Expo 位置

安装

在 app 配置中进行配置

Example app.json with config plugin

Configurable properties

后台位置

后台位置配置 iOS

后台位置方法

地理围栏方法

后台权限

延迟位置

用法

启用模拟器位置

Android 模拟器

iOS 模拟器

API

Hooks

useBackgroundPermissions(options)

useForegroundPermissions(options)

Methods

Location.enableNetworkProviderAsync()

Location.geocodeAsync(address)

Location.getBackgroundPermissionsAsync()

Location.getCurrentPositionAsync(options)

Location.getForegroundPermissionsAsync()

Location.getHeadingAsync()

Location.getLastKnownPositionAsync(options)

Location.getProviderStatusAsync()

Location.hasServicesEnabledAsync()

Location.hasStartedGeofencingAsync(taskName)

Location.hasStartedLocationUpdatesAsync(taskName)

Location.installWebGeolocationPolyfill()

Location.isBackgroundLocationAvailableAsync()

Location.requestBackgroundPermissionsAsync()

Location.requestForegroundPermissionsAsync()

Location.reverseGeocodeAsync(location)

Location.startGeofencingAsync(taskName, regions)

Task parameters

Location.startLocationUpdatesAsync(taskName, options)

Task parameters

Location.stopGeofencingAsync(taskName)

Location.stopLocationUpdatesAsync(taskName)

Location.watchHeadingAsync(callback, errorHandler)

Location.watchPositionAsync(options, callback, errorHandler)

Types

LocationCallback(location)

LocationErrorCallback(reason)

LocationGeocodedAddress

LocationGeocodedLocation

LocationHeadingCallback(location)

LocationHeadingObject

LocationLastKnownOptions

LocationObject

LocationObjectCoords

LocationOptions

LocationPermissionResponse

LocationProviderStatus

LocationRegion

LocationSubscription

LocationTaskOptions

LocationTaskServiceOptions

PermissionDetailsLocationAndroid

PermissionDetailsLocationIOS

PermissionExpiration

PermissionHookOptions

PermissionResponse

Enums

Accuracy

Lowest

Low

Balanced

High

Highest

BestForNavigation

ActivityType

Other

AutomotiveNavigation

Fitness

OtherNavigation

Airborne

后台位置配置
iOS

`useBackgroundPermissions(options)`

`useForegroundPermissions(options)`

`Location.enableNetworkProviderAsync()`

`Location.geocodeAsync(address)`

`Location.getBackgroundPermissionsAsync()`

`Location.getCurrentPositionAsync(options)`

`Location.getForegroundPermissionsAsync()`

`Location.getHeadingAsync()`

`Location.getLastKnownPositionAsync(options)`

`Location.getProviderStatusAsync()`

`Location.hasServicesEnabledAsync()`

`Location.hasStartedGeofencingAsync(taskName)`

`Location.hasStartedLocationUpdatesAsync(taskName)`

`Location.installWebGeolocationPolyfill()`

`Location.isBackgroundLocationAvailableAsync()`

`Location.requestBackgroundPermissionsAsync()`

`Location.requestForegroundPermissionsAsync()`

`Location.reverseGeocodeAsync(location)`

`Location.startGeofencingAsync(taskName, regions)`

`Location.startLocationUpdatesAsync(taskName, options)`

`Location.stopGeofencingAsync(taskName)`

`Location.stopLocationUpdatesAsync(taskName)`

`Location.watchHeadingAsync(callback, errorHandler)`

`Location.watchPositionAsync(options, callback, errorHandler)`

`LocationCallback(location)`

`LocationErrorCallback(reason)`

`LocationGeocodedAddress`

`LocationGeocodedLocation`

`LocationHeadingCallback(location)`

`LocationHeadingObject`

`LocationLastKnownOptions`

`LocationObject`

`LocationObjectCoords`

`LocationOptions`

`LocationPermissionResponse`

`LocationProviderStatus`

`LocationRegion`

`LocationSubscription`

`LocationTaskOptions`

`LocationTaskServiceOptions`

`PermissionDetailsLocationAndroid`

`PermissionDetailsLocationIOS`

`PermissionExpiration`

`PermissionHookOptions`

`PermissionResponse`

`Accuracy`

`Lowest`

`Low`

`Balanced`

`High`

`Highest`

`BestForNavigation`

`ActivityType`

`Other`

`AutomotiveNavigation`

`Fitness`

`OtherNavigation`

`Airborne`

`GeofencingEventType`

`Enter`

`Exit`

`GeofencingRegionState`

`Unknown`

`Inside`

`Outside`

`PermissionStatus`

`DENIED`

`GRANTED`

`UNDETERMINED`