@capacitor/geolocation
地理位置 API 提供简单的获取和跟踪设备当前位置（使用 GPS）的方法，以及海拔、航向和速度信息（如果可用）。
安装
npm install @capacitor/geolocation
npx cap sync
iOS
Apple 要求在 Info.plist 中指定位置信息的隐私描述
NSLocationWhenInUseUsageDescription(隐私 - 使用中位置使用描述)
了解有关 配置 Info.plist 的信息，请参见 iOS 指南，以获取有关在 Xcode 中设置 iOS 权限的更多信息
Android
此 API 要求将以下权限添加到您的 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 权限的更多信息。
变量
此插件将使用以下项目变量（在您的应用程序的 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(...)
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 | coords 的创建时间戳 | 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 权限（可以使用位置别名检查），它将被忽略。 | false | 1.0.0 |
timeout | number | 位置更新的最大等待时间（以毫秒为单位）。在 Android 中，从插件的 4.0.0 版本开始，timeout 对于 getCurrentPosition 被忽略。 | 10000 | 1.0.0 |
maximumAge | number | 可接受的返回的可能缓存位置的最大年龄（以毫秒为单位） | 0 | 1.0.0 |
ClearWatchOptions
| 属性 | 类型 |
|---|---|
id | CallbackID |
PermissionStatus
| 属性 | 类型 | 描述 | 自 |
|---|---|---|---|
location | PermissionState | 位置别名的权限状态。在 Android 上，它请求/检查 ACCESS_COARSE_LOCATION 和 ACCESS_FINE_LOCATION 权限。在 iOS 和 Web 上，它请求/检查位置权限。 | 1.0.0 |
coarseLocation | PermissionState | 粗略位置别名的权限状态。在 Android 上，它请求/检查 ACCESS_COARSE_LOCATION。在 Android 12+ 上，用户可以选择近似位置（ACCESS_COARSE_LOCATION）或精确位置（ACCESS_FINE_LOCATION），因此如果应用程序不需要高精度，可以使用此别名。在 iOS 和 Web 上，它将与位置别名具有相同的值。 | 1.2.0 |
GeolocationPluginPermissions
| 属性 | 类型 |
|---|---|
permissions | GeolocationPermissionType[] |
类型别名
WatchPositionCallback
(position: Position | null, err?: any): voidCallbackID
stringPermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'GeolocationPermissionType
'location' | 'coarseLocation'