跳到主要内容
版本：v3

@capacitor/geolocation

Geolocation API 提供了一套简单的方法，用于通过 GPS 获取和追踪设备的当前位置，在可用情况下还能获取海拔、朝向和速度信息。

安装​

npm install @capacitor/geolocation
npx cap sync

iOS​

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

  • NSLocationAlwaysUsageDescription (隐私 - 始终使用位置描述)
  • NSLocationWhenInUseUsageDescription (隐私 - 使用时使用位置描述)

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

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（默认值：17.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

Interfaces​

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

PositionOptions​

属性类型描述默认值自
enableHighAccuracyboolean高精度模式（如启用GPS，如果可用）在 Android 12+ 设备上，如果用户未授予 ACCESS_FINE_LOCATION 权限（可通过 location 别名检查），此设置将被忽略false1.0.0
timeoutnumber获取位置更新的最大等待时间（毫秒）100001.0.0
maximumAgenumber可接受的缓存位置的最大存活时间（毫秒）01.0.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​

属性类型
permissionsGeolocationPermissionType[]

Type Aliases​

WatchPositionCallback​


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

CallbackID​

string

PermissionState​

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

GeolocationPermissionType​

'location' | 'coarseLocation'

Contents

编辑此页