跳到主要内容
版本：v7

@capacitor/geolocation

Geolocation API 提供简单的方法，通过 GPS 获取和追踪设备的当前位置，如果可用的话还会包含海拔、航向和速度信息。

安装​

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

iOS​

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

  • NSLocationAlwaysAndWhenInUseUsageDescription (隐私 - 始终和在应用使用时访问位置)
  • NSLocationWhenInUseUsageDescription (隐私 - 在应用使用时访问位置)

[!注意] 此 Capacitor 插件不直接支持后台地理定位。但是，它依赖于 ion-ios-geolocation，该库可以在后台报告位置。因此，Apple 要求你必须在 Info.plist 中包含 NSLocationAlwaysAndWhenInUseUsageDescription 条目。由于此权限提示不会显示给用户，你可以安全地使用与 NSLocationWhenInUseUsageDescription 相同的描述字符串。

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

Android​

此插件需要将以下权限添加到你的 AndroidManifest.xml 中：

<!-- Geolocation 插件 -->
<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 权限的信息。

API​

关于错误代码列表，请参阅 错误

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>

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

在 Web 上不可用。

参数类型
permissions
GeolocationPluginPermissions

返回值: 

Promise<PermissionStatus>

自: 1.0.0

接口​

Position​

属性类型描述自
timestampnumber坐标的创建时间戳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
属性类型描述默认值始于版本
enableHighAccuracyboolean高精度模式（如 GPS，如果可用）。在 Android 12+ 设备上，如果用户未授予 ACCESS_FINE_LOCATION 权限（可通过 location 别名检查），此设置将被忽略。false1.0.0
timeoutnumber等待位置更新的最长时间（毫秒）。在 Android 中，从插件 7.1.0 版本开始，此参数也用于确定 watchPosition 的位置更新间隔。100001.0.0
maximumAgenumber可接受返回的缓存位置的最大时间（毫秒）01.0.0
minimumUpdateIntervalnumber位置更新的最小时间间隔。如果位置更新速度快于此间隔，则仅在上次位置更新后经过此最小更新间隔时才会进行更新。此参数仅适用于 Android，在 iOS 或 Web 平台上无效。50006.1.0

清除监听选项​

属性类型
id
CallbackID

权限状态​

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

地理位置插件权限​

属性类型
permissionsGeolocationPermissionType[]

类型别名​

监听位置回调​

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

回调 ID​

string

权限状态​

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

地理位置权限类型​

'location' | 'coarseLocation'

错误​

插件在原生 Android 和 iOS 平台上会返回带有特定代码的错误。Web 平台不遵循此错误标准。

下表列出了所有插件错误：

错误代码平台消息
OS-PLUG-GLOC-0002Android, iOS尝试获取位置时发生错误。
OS-PLUG-GLOC-0003Android, iOS位置权限请求被拒绝。
OS-PLUG-GLOC-0004iOS'getCurrentPosition' 输入参数无效。
OS-PLUG-GLOC-0005iOS'watchPosition' 输入参数无效。
OS-PLUG-GLOC-0006iOS'clearWatch' 输入参数无效。
OS-PLUG-GLOC-0007Android, iOS位置服务未启用。
OS-PLUG-GLOC-0008iOS应用对位置服务的使用受到限制。
OS-PLUG-GLOC-0009Android启用位置的请求被拒绝。
OS-PLUG-GLOC-0010Android无法在指定时间内获取位置。尝试设置更长的超时时间。
OS-PLUG-GLOC-0011Android超时时间必须为正值。
OS-PLUG-GLOC-0012Android未找到 WatchId。
OS-PLUG-GLOC-0013Android必须提供 WatchId。
OS-PLUG-GLOC-0014AndroidGoogle Play 服务错误，用户可解决。
OS-PLUG-GLOC-0015AndroidGoogle Play 服务错误。
OS-PLUG-GLOC-0016Android位置设置错误。

Contents

编辑此页