跳到主要内容
版本：v8

@capacitor/geolocation

地理位置定位 API 提供了简单的方法来使用 GPS 获取和跟踪设备的当前位置，以及可用的高度、航向和速度信息。

安装​

npm install @capacitor/geolocation
npx cap sync

iOS​

Apple 要求在 Info.plist 中指定位置信息的隐私描述：

  • NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description)
  • NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)

[!NOTE] 此 Capacitor 插件不直接支持后台地理定位。但是，它依赖于 ion-ios-geolocation，可以在后台报告位置。 因此，Apple 要求您在 Info.plist 中包含 NSLocationAlwaysAndWhenInUseUsageDescription 条目。由于此权限提示不会向用户显示， 您可以安全地使用与 NSLocationWhenInUseUsageDescription 相同的描述字符串。

阅读 iOS 指南中的配置 Info.plist以获取有关在 Xcode 中设置 iOS 权限的更多信息

Android​

此插件需要将以下权限添加到您的 AndroidManifest.xml 中：

<!-- Geolocation Plugin -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<feature android:name="android.hardware.location.gps" />

前两个权限请求位置数据，包括精确和粗略位置，最后一行是可选的，但如果您的应用_需要_ GPS 才能运行则是必需的。您可以省略它，但请记住，这可能意味着您的应用将安装在缺少 GPS 硬件的设备上。

阅读 Android 指南中的设置权限以获取有关设置 Android 权限的更多信息。

API​

错误代码列表，请参阅错误

getCurrentPosition(...)​

getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>

获取设备的当前 GPS 位置

ParamType
options
PositionOptions

Returns: 

Promise<Position>

Since: 1.0.0

watchPosition(...)​

watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>

设置位置变化的监视。请注意，监视位置变化可能会消耗大量能量。请明智地仅在需要时进行监听。

ParamType
options
PositionOptions
callback
WatchPositionCallback

Returns: Promise<string>

Since: 1.0.0

clearWatch(...)​

clearWatch(options: ClearWatchOptions) => Promise<void>

清除指定的监视

ParamType
options
ClearWatchOptions

Since: 1.0.0

checkPermissions()​

checkPermissions() => Promise<PermissionStatus>

检查位置权限。如果系统位置服务被禁用，将抛出异常。

Returns: 

Promise<PermissionStatus>

Since: 1.0.0

requestPermissions(...)​

requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>

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

在 Web 上不可用。

ParamType
permissions
GeolocationPluginPermissions

Returns: 

Promise<PermissionStatus>

Since: 1.0.0

Interfaces​

Position​

PropTypeDescriptionSince
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​

PropTypeDescriptionDefaultSince
enableHighAccuracyboolean高精度模式（如 GPS，如果可用）。在 Android 12+ 设备上，如果用户未授予 ACCESS_FINE_LOCATION 权限（可以通过 location 别名检查），则将被忽略。false1.0.0
timeoutnumber等待位置更新的最长时间（毫秒）。100001.0.0
maximumAgenumber可接受返回的可能缓存位置的最大年龄（毫秒）01.0.0
minimumUpdateIntervalnumberwatchPosition 的最小更新间隔。不要与 interval 混淆。如果位置更新可用的速度快于此间隔，则只有在自上次位置更新以来最小更新间隔已过期时才会发生更新。此参数仅适用于 Android。它对 iOS 或 Web 平台没有影响。50006.1.0
intervalnumber在 watchPosition 中接收位置更新的期望间隔（毫秒）。对于非常低的 interval 值（几秒或更少），平台可能无法保证及时的位置更新 - 它们可能比指定的要长。平台也可能能够以比 interval 更快的速度提供位置更新。您可以使用 minimumUpdateInterval 来控制该行为。为了与版本 7.1.x 向后兼容，如果未传递值，则此参数的默认值为 timeout 的值。此参数仅适用于 Android。它对 iOS 或 Web 平台没有影响。
timeout
8.0.0
enableLocationFallbackboolean是否在 Google Play Service 的位置设置检查失败时回退到 Android 框架的 LocationManager。这可能发生在多种原因 - 例如设备没有 Play Services 或设备没有网络连接（飞行模式）如果设置为 false，失败将被传播给调用者。请注意，LocationManager 可能不如 Google Play Services 实现有效。如果设备处于飞行模式，则仅使用 GPS 提供程序，根据 GPS 信号，返回位置可能需要更长时间。这意味着要在这种情况下接收位置，您可能需要提供更高的超时时间。此参数仅适用于 Android。它对 iOS 或 Web 平台没有影响。true8.0.0

ClearWatchOptions​

PropType
id
CallbackID

PermissionStatus​

PropTypeDescriptionSince
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​

PropType
permissionsGeolocationPermissionType[]

Type Aliases​

WatchPositionCallback​

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

CallbackID​

string

PermissionState​

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

GeolocationPermissionType​

'location' | 'coarseLocation'

错误​

插件在原生 Android 和 iOS 上返回具有特定代码的特定错误。Web 不遵循此错误标准。

下表列出了所有插件错误：

错误代码平台消息
OS-PLUG-GLOC-0002Android, iOS尝试获取位置时出错。
OS-PLUG-GLOC-0003Android, iOS位置权限请求被拒绝。
OS-PLUG-GLOC-0004iOS'getCurrentPosition' 输入参数无效。
OS-PLUG-GLOC-0005iOS'watchPosition' 输入参数无效。
OS-PLUG-GLOC-0006iOS'clearWatch' 输入参数无效。
OS-PLUG-GLOC-0007Android, iOS位置服务未启用。
OS-PLUG-GLOC-0008iOS应用对位置服务的使用受到限制。
OS-PLUG-GLOC-0009Android启用位置的请求被拒绝。
OS-PLUG-GLOC-0010Android, iOS无法及时获取位置。尝试使用更高的超时时间。
OS-PLUG-GLOC-0011Android超时时间需要为正值。
OS-PLUG-GLOC-0012Android未找到 WatchId。
OS-PLUG-GLOC-0013Android需要提供 WatchId。
OS-PLUG-GLOC-0014AndroidGoogle Play Services 错误用户可解决。
OS-PLUG-GLOC-0015AndroidGoogle Play Services 错误。
OS-PLUG-GLOC-0016Android位置设置错误。
OS-PLUG-GLOC-0017Android无法检索位置，因为设备的网络和位置都已关闭。

Contents

编辑此页