Expo 定位

提供读取地理位置信息、轮询当前位置或从设备订阅位置更新事件的库。

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

¥expo-location allows reading geolocation information from the device. Your app can poll for the current location or subscribe to location update events.

安装

¥Installation

If you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.

应用配置中的配置

¥Configuration in app config

如果你在项目中使用配置插件（EAS 构建 或 npx expo run:[android|ios]），则可以使用其内置的 配置插件 配置 expo-location。该插件允许你配置无法在运行时设置的各种属性，并且需要构建新的应用二进制文件才能生效。

¥You can configure expo-location using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.

Example app.json with config plugin

{
"expo": {
  "plugins": [
    [
      "expo-location",
      {
        "locationAlwaysAndWhenInUsePermission": "Allow $(PRODUCT_NAME) to use your location."
      }
    ]
  ]
}
}

Configurable properties

背景位置

¥Background location

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

¥Background location allows your app to receive location updates while it is running in the background and includes both location updates and region monitoring through geofencing. This feature is subject to platform API limitations and system constraints:

• 如果用户终止应用，后台定位将停止。

  ¥Background location will stop if the user terminates the app.

• 如果用户重新启动应用，后台定位将恢复。

  ¥Background location resumes if the user restarts the app.

• 由于平台限制，当发生位置或地理围栏事件时，已终止的应用不会自动重启。

¥

• 当发生新的地理围栏事件时，系统将重新启动已终止的应用。

¥

信息 在 Android 上，从最近的应用列表中删除应用的结果因设备供应商而异。例如，某些实现将应用从最近的应用列表中删除视为将其终止。在此处阅读有关这些差异的更多信息：https://dontkillmyapp.com。

¥On Android, the result of removing an app from the recent apps list varies by device vendor. For example, some implementations treat removing an app from the recent apps list as killing it. Read more about these differences here: https://dontkillmyapp.com.

后台位置配置

iOS

¥Background location configuration 

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

¥To be able to run background location on iOS, you need to add the location value to the UIBackgroundModes array in your app's Info.plist file.

如果你使用 CNG，所需的 UIBackgroundModes 配置将由预构建自动应用。

¥If you're using CNG, the required UIBackgroundModes configuration will be applied automatically by prebuild.

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

后台位置方法

¥Background location methods

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

¥To use Background Location methods, the following requirements apply:

• 必须授予位置权限。

  ¥Location permissions must be granted.

• 后台位置任务必须在顶层范围中使用 TaskManager.defineTask 进行定义。

  ¥Background location task must be defined in the top-level scope, using TaskManager.defineTask.

• iOS
  "location" 后台模式必须在 Info.plist 文件中指定。参见 后台位置配置。

  ¥

  iOS
  "location" background mode must be specified in Info.plist file. See Background location configuration.

• 你必须使用 开发构建 来使用后台位置，因为 Expo Go 应用不支持该功能。

¥

地理围栏方法

¥Geofencing methods

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

¥To use Geofencing methods, the following requirements apply:

• 必须授予位置权限。

  ¥Location permissions must be granted.

• 地理围栏任务必须使用 TaskManager.defineTask 在顶层范围中定义。

  ¥The Geofencing task must be defined in the top-level scope, using TaskManager.defineTask.

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

¥When using Geofencing, the following platform differences apply:

• 每个应用允许你使用 最多 100 个活动地理围栏。

¥

• Expo Location 将在应用启动时报告已注册地理围栏的初始状态。

¥

• 有一个 限制为 20 regions 可以同时监控。

¥

后台权限

¥Background permissions

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

¥To use location tracking or Geofencing in the background, you must request the appropriate permissions:

• 在 Android 上，你必须请求前台和后台权限。

  ¥On Android, you must request both foreground and background permissions.

• 在 iOS 上，必须使用 requestBackgroundPermissionsAsync 授予 Always 选项。

  ¥On iOS, it must be granted with the Always option using requestBackgroundPermissionsAsync.

用法

¥Usage

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

¥If you're using the Android Emulator or iOS Simulator, ensure that Location is enabled.

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(
        'Oops, this will not work on Snack in an Android Emulator. Try it on your device!'
      );
      return;
    }
    let { status } = await Location.requestForegroundPermissionsAsync();
    if (status !== 'granted') {
      setErrorMsg('Permission to access location was denied');
      return;
    }

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

  getCurrentLocation();
}, []);

let text = 'Waiting...';
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',
},
});

启用模拟器位置

¥Enable Emulator Location

安卓模拟器

¥Android Emulator

打开 Android Studio，然后启动 Android 模拟器。在其中，转到“设置”>“位置”并启用“使用位置”。

¥Open Android Studio, and launch the Android Emulator. Inside it, go to Settings > Location and enable Use location.

如果你没有在模拟器中收到位置，则可能需要关闭“提高位置准确性”设置。这将关闭 Wi-Fi 定位并仅使用 GPS。然后你可以通过模拟器使用 GPS 数据操纵位置。

¥If you don't receive the locations in the emulator, you may have to turn off the Improve Location Accuracy setting. This will turn off Wi-Fi location and only use GPS. Then you can manipulate the location with GPS data through the emulator.

对于 Android 12 及更高版本，请转到“设置”>“位置”>“位置服务”>“Google 位置精度”，然后关闭“提高位置精度”。对于 Android 11 及更低版本，请转到“设置”>“位置”>“高级”>“Google 位置精度”，然后关闭“Google 位置精度”。

¥For Android 12 and higher, go to Settings > Location > Location Services > Google Location Accuracy, and turn off Improve Location Accuracy. For Android 11 and lower, go to Settings > Location > Advanced > Google Location Accuracy, and turn off Google Location Accuracy.

iOS 模拟器

¥iOS Simulator

打开模拟器后，转到“功能”>“位置”，然后选择除“无”之外的任何选项。

¥With Simulator open, go to Features > Location and choose any option besides None.

API

import * as Location from 'expo-location';

Hooks

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

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

Methods

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

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

Interfaces

Types

Enums

权限

¥Permissions

安卓

¥Android

Android 版 Expo Go 中不提供前台和后台服务。相反，我们建议使用 开发构建 来避免限制。

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

¥When you install the expo-location module, it automatically adds the following permissions:

• ACCESS_COARSE_LOCATION：获取设备的大概位置

  ¥ACCESS_COARSE_LOCATION: for approximate device location

• ACCESS_FINE_LOCATION：用于精确的设备定位

  ¥ACCESS_FINE_LOCATION: for precise device location

以下权限是可选的：

¥The following permissions are optional:

• FOREGROUND_SERVICE 和 FOREGROUND_SERVICE_LOCATION：能够在应用打开但处于后台状态时访问位置。仅从 Android 14 开始需要 FOREGROUND_SERVICE_LOCATION。当你在新版本中启用此功能时，你将需要 提交你的应用以供审核并请求访问使用前台服务的权限。

  ¥FOREGROUND_SERVICE and FOREGROUND_SERVICE_LOCATION: to be able to access location while the app is open but backgrounded. FOREGROUND_SERVICE_LOCATION is only required as of Android 14. When you enable this in a new build, you will need to submit your app for review and request access to use the foreground service permission.

• ACCESS_BACKGROUND_LOCATION：能够在应用处于后台或关闭时访问位置。当你在新版本中启用此功能时，你将需要 提交你的应用以供审核并请求访问权限以使用后台位置权限。

  ¥ACCESS_BACKGROUND_LOCATION: to be able to access location while the app is backgrounded or closed. When you enable this in a new build, you will need to submit your app for review and request access to use the background location permission.

排除许可

¥Excluding a permission

注意：从应用中的模块中排除所需的权限可能会破坏与该权限相对应的功能。始终确保包含模块依赖的所有权限。

¥Note: Excluding a required permission from a module in your app can break the functionality corresponding to that permission. Always make sure to include all permissions a module is dependent on.

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

¥When your Expo project doesn't benefit from having particular permission included, you can omit it. For example, if your application doesn't need access to the precise location, you can exclude the ACCESS_FINE_LOCATION permission.

另一个例子可以用 可用的位置精度 来说明。Android 定义了 3 平方公里左右的粗略定位精度估计，以及 50 米左右的精确定位精度估计。例如，如果位置精度值为 低的，则可以排除 ACCESS_FINE_LOCATION 权限。要了解有关定位精度级别的更多信息，请参阅 安卓文档。

¥Another example can be stated using available location accuracies. Android defines the approximate location accuracy estimation within about 3 square kilometers, and the precise location accuracy estimation within about 50 meters. For example, if the location accuracy value is Low, you can exclude ACCESS_FINE_LOCATION permission. To learn more about levels of location accuracies, see Android documentation.

要了解有关如何排除权限的更多信息，请参阅 排除 Android 权限。

¥To learn more on how to exclude permission, see Excluding Android permissions.

iOS 系统

¥iOS

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

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