跳到主要内容
版本：v6

@capacitor/geolocation

Geolocation API 提供了一系列简单方法来获取和追踪设备当前位置（使用GPS），包括海拔、朝向和速度等信息（如果可用）。

安装​

npm install @capacitor/geolocation
npx cap sync

iOS​

苹果公司要求必须在 Info.plist 中声明位置信息使用的隐私描述：

  • NSLocationWhenInUseUsageDescription (隐私 - 使用期间的位置访问说明)

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

Android​

此API需要在 AndroidManifest.xml 中添加以下权限：

<!-- 地理位置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

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等待位置更新的最长时间（毫秒）。在Android平台上，从插件4.0.0版本开始，getCurrentPosition方法将忽略此超时设置。100001.0.0
maximumAgenumber可接受的缓存位置的最大年龄（毫秒）01.0.0
minimumUpdateIntervalnumber位置更新的最小间隔时间（毫秒）。如果位置更新比此间隔更快，则只有在上次更新超过最小间隔后才会触发更新。此参数仅适用于Android平台，对iOS和Web平台无效。50006.1.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

编辑此页