跳到主要内容
版本：v5

@capacitor/geolocation

Geolocation API 提供了一系列简单方法，用于通过GPS获取和追踪设备当前位置（若设备支持还可获取海拔、朝向和速度信息）。

安装​

npm install @capacitor/geolocation@latest-5
npx cap sync

iOS​

苹果公司要求在 Info.plist 中声明位置信息的使用说明：

  • NSLocationAlwaysUsageDescription (隐私 - 始终访问位置使用说明)
  • NSLocationWhenInUseUsageDescription (隐私 - 使用时访问位置使用说明)

在 iOS指南 中阅读 配置 Info.plist 了解如何在Xcode中设置iOS权限的更多信息

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.0.1）

示例​

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>

请求位置权限。如果系统定位服务被禁用将会抛出异常。

参数Type
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

ClearWatchOptions​

属性类型
id
CallbackID

PermissionStatus​

属性类型描述版本
location
PermissionState
位置别名的权限状态。在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​

Position​

Position 是坐标数组。 遵循RFC 7946标准第3.1.1节 https://tools.ietf.org/html/rfc7946#section-3.1.1 数组应包含2-3个元素。 之前的GeoJSON规范允许更多元素（例如可用来表示M值）， 但现行规范只允许定义X、Y和（可选的）Z坐标。

number[]

WatchPositionCallback​


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

CallbackID​

string

PermissionState​

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

GeolocationPermissionType​

'location' | 'coarseLocation'

Contents

编辑此页