跳到主要内容
版本：v6

@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('当前坐标：', 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​

属性类型描述自
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 权限（可通过位置别名检查），则此设置将被忽略。false1.0.0
timeoutnumber等待位置更新的最长时间，单位为毫秒。在 Android 上，自插件 4.0.0 版本起，getCurrentPosition 方法会忽略超时设置。100001.0.0
maximumAgenumber可接受的缓存位置的最大年龄，单位为毫秒01.0.0
minimumUpdateIntervalnumber位置更新的最小时间间隔。如果位置更新的速度快于此间隔，则只有在上次位置更新后经过了最小更新间隔，才会进行新的更新。此参数仅适用于 Android 平台，对 iOS 或 Web 平台没有影响。50006.1.0

清除监听选项​

属性类型
id
CallbackID

权限状态​

属性类型描述起始版本
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 上，其值与 location 别名相同。1.2.0

地理位置插件权限​

属性类型
permissionsGeolocationPermissionType[]

类型别名​

监听位置回调​

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

回调标识​

string

权限状态类型​

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

地理位置权限类型​

'location' | 'coarseLocation'

Contents

编辑此页