@capacitor/geolocation
Geolocation API 提供了获取和跟踪设备当前位置的简单方法，包括海拔、方向和速度信息（如果可用）。
安装
npm install @capacitor/geolocation@latest-7
npx cap sync
iOS
Apple 要求在 Info.plist 中为位置信息指定隐私描述：
NSLocationAlwaysAndWhenInUseUsageDescription（Privacy - Location Always and When In Use Usage Description）NSLocationWhenInUseUsageDescription（Privacy - Location When In Use Usage Description）
[!注意] 此 Capacitor 插件不直接支持后台定位。然而，它依赖于
ion-ios-geolocation，后者可以在 后台报告位置。因此，Apple 要求您在Info.plist中包含NSLocationAlwaysAndWhenInUseUsageDescription条目。由于此权限 提示不会显示给用户，您可以安全地使用与NSLocationWhenInUseUsageDescription相同的描述字符串。
阅读有关配置 Info.plist 的 iOS 指南 以获取有关在 Xcode 中设置 iOS 权限 的更多信息。
Android
此插件需要将以下权限添加到您的 AndroidManifest.xml 中：
<!-- 地理位置插件 -->
<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 | |
返回：
Promise<Position>自从： 1.0.0
watchPosition(...)
watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>
设置位置更改的监听。请注意，监听位置更改 会消耗大量电量。请仅在需要时进行监听。
| 参数 | 类型 |
|---|---|
options | |
callback | |
返回： Promise<string>
自从： 1.0.0
clearWatch(...)
clearWatch(options: ClearWatchOptions) => Promise<void>
清除指定的监听
| 参数 | 类型 |
|---|---|
options | |
自从： 1.0.0
checkPermissions()
checkPermissions() => Promise<PermissionStatus>
检查位置权限。如果系统定位服务被禁用，将抛出错误。
返回：
Promise<PermissionStatus>自从： 1.0.0
requestPermissions(...)
requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>
请求位置权限。如果系统定位服务被禁用，将抛出错误。
在 Web 端不可用。
| 参数 | 类型 |
|---|---|
permissions | |
返回：
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 上，自插件 7.1.0 版本起，它也用于确定 watchPosition 的位置更新间隔。 | 10000 | 1.0.0 |
maximumAge | number | 可接受的缓存位置的最大年龄（毫秒） | 0 | 1.0.0 |
minimumUpdateInterval | number | 位置更新的最小间隔。如果位置更新可用频率快于此间隔，则仅当自上次位置更新以来最小更新间隔已过时才会触发更新。此参数仅适用于 Android。在 iOS 或 Web 平台上无效。 | 5000 | 6.1.0 |
ClearWatchOptions
| 属性 | 类型 |
|---|---|
id | |
PermissionStatus
| 属性 | 类型 | 描述 | 自从 |
|---|---|---|---|
location | | location 别名的权限状态。在 Android 上，它会请求/检查 ACCESS_COARSE_LOCATION 和 ACCESS_FINE_LOCATION 权限。在 iOS 和 Web 上，它会请求/检查位置权限。 | 1.0.0 |
coarseLocation | | 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): voidCallbackID
string
PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
GeolocationPermissionType
'location' | 'coarseLocation'
错误
该插件在原生 Android 和 iOS 上返回带有特定代码的特定错误。Web 端不遵循此错误标准。
下表列出了所有插件错误：
| 错误代码 | 平台 | 消息 |
|---|---|---|
| OS-PLUG-GLOC-0002 | Android, iOS | 尝试获取位置时发生错误。 |
| OS-PLUG-GLOC-0003 | Android, iOS | 位置权限请求被拒绝。 |
| OS-PLUG-GLOC-0004 | iOS | 'getCurrentPosition' 输入参数无效。 |
| OS-PLUG-GLOC-0005 | iOS | 'watchPosition' 输入参数无效。 |
| OS-PLUG-GLOC-0006 | iOS | 'clearWatch' 输入参数无效。 |
| OS-PLUG-GLOC-0007 | Android, iOS | 定位服务未启用。 |
| OS-PLUG-GLOC-0008 | iOS | 应用使用定位服务受到限制。 |
| OS-PLUG-GLOC-0009 | Android | 启用位置的请求被拒绝。 |
| OS-PLUG-GLOC-0010 | Android | 无法及时获取位置。请尝试使用更长的超时时间。 |
| OS-PLUG-GLOC-0011 | Android | 超时时间必须是正数。 |
| OS-PLUG-GLOC-0012 | Android | 未找到 WatchId。 |
| OS-PLUG-GLOC-0013 | Android | 需要提供 WatchId。 |
| OS-PLUG-GLOC-0014 | Android | Google Play 服务错误，用户可解决。 |
| OS-PLUG-GLOC-0015 | Android | Google Play 服务错误。 |
| OS-PLUG-GLOC-0016 | Android | 位置设置错误。 |