@capacitor/geolocation

Geolocation API 提供简单的方法来获取和跟踪设备当前的位置（使用 GPS），以及海拔、方向和速度信息（如果可用）。

安装

npm install @capacitor/geolocation@latest-6
npx cap sync

iOS

Apple 要求在 Info.plist 中为位置信息指定隐私描述：

• NSLocationWhenInUseUsageDescription（Privacy - Location When In Use Usage Description）

阅读 iOS 指南 中关于 配置 Info.plist 的内容，了解更多关于在 Xcode 中设置 iOS 权限的信息。

Android

此 API 需要在您的 AndroidManifest.xml 中添加以下权限：

<!-- Geolocation API -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location.gps" />

前两个权限请求位置数据（精确和粗略），最后一行是可选的，但如果您的应用需要 GPS 功能，则必须添加。您可以省略它，但请注意这可能导致您的应用安装在缺乏 GPS 硬件的设备上。

阅读 Android 指南 中关于 设置权限 的内容，了解更多关于设置 Android 权限的信息。

变量

此插件将使用以下项目变量（在应用的 variables.gradle 文件中定义）：

• playServicesLocationVersion：com.google.android.gms:play-services-location 的版本（默认值：21.1.0）

示例

import { Geolocation } from '@capacitor/geolocation';

const printCurrentPosition = async () => {
  const coordinates = await Geolocation.getCurrentPosition();

  console.log('Current position:', coordinates);
};

API

• getCurrentPosition(...)
• watchPosition(...)
• clearWatch(...)
• checkPermissions()
• requestPermissions(...)
• Interfaces
• Type Aliases

getCurrentPosition(...)

getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>

获取设备的当前 GPS 位置。

参数	类型
options	PositionOptions

返回：

Promise<Position>

始于： 1.0.0

---

watchPosition(...)

watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>

设置位置变化监听。请注意，监听位置变化会消耗大量电量。请仅在需要时进行监听。

参数	类型
options	PositionOptions
callback	WatchPositionCallback

返回： Promise<string>

始于： 1.0.0

---

clearWatch(...)

clearWatch(options: ClearWatchOptions) => Promise<void>

清除指定的位置监听。

参数	类型
options	ClearWatchOptions

始于： 1.0.0

---

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

检查位置权限。如果系统定位服务被禁用，将抛出错误。

返回：

Promise<PermissionStatus>

始于： 1.0.0

---

requestPermissions(...)

requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>

请求位置权限。如果系统定位服务被禁用，将抛出错误。

参数	类型
permissions	GeolocationPluginPermissions

返回：

Promise<PermissionStatus>

始于： 1.0.0

---

接口

Position

属性	类型	描述	始于
timestamp	number	坐标的创建时间戳。	1.0.0
coords	{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number | null; altitude: number | null; speed: number | null; heading: number | null; }	GPS 坐标及数据精度。	1.0.0

PositionOptions

属性	类型	描述	默认值	始于
enableHighAccuracy	boolean	高精度模式（例如 GPS，如果可用）。在 Android 12+ 设备上，如果用户未授予 ACCESS_FINE_LOCATION 权限（可通过 location 别名检查），将被忽略。	false	1.0.0
timeout	number	位置更新的最大等待时间（毫秒）。在 Android 上，自插件 4.0.0 版本起，getCurrentPosition 中忽略 timeout。	10000	1.0.0
maximumAge	number	可接受的缓存位置的最大时间（毫秒）。	0	1.0.0
minimumUpdateInterval	number	位置更新的最小间隔时间。如果位置更新可用频率高于此间隔，则仅在上次位置更新后此最小间隔已过时才会触发更新。此参数仅适用于 Android。对 iOS 或 Web 平台无影响。	5000	6.1.0

ClearWatchOptions

属性	类型
id	CallbackID

PermissionStatus

属性	类型	描述	始于
location	PermissionState	location 别名的权限状态。在 Android 上，同时请求/检查 ACCESS_COARSE_LOCATION 和 ACCESS_FINE_LOCATION 权限。在 iOS 和 Web 上，请求/检查位置权限。	1.0.0
coarseLocation	PermissionState	coarseLocation 别名的权限状态。在 Android 上，请求/检查 ACCESS_COARSE_LOCATION。在 Android 12+ 上，用户可以选择"大致位置"（ACCESS_COARSE_LOCATION）或"精确位置"（ACCESS_FINE_LOCATION），因此如果应用不需要高精度，可以使用此别名。在 iOS 和 Web 上，其值与 location 别名相同。	1.2.0

GeolocationPluginPermissions

属性	类型
permissions	GeolocationPermissionType[]

类型别名

WatchPositionCallback

(position: Position | null, err?: any): void

CallbackID

string

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

GeolocationPermissionType

'location' | 'coarseLocation'