更新记录

1.0.0（2026-08-15）

• 首次发布。
• 提供 Android / iOS / Harmony / Web / 微信小程序系统定位能力：权限申请、后台定位、最近一次缓存读取、实时监听（含 realtime 事件驱动模式，忽略 intervalMs 节拍，静止设备不再空转心跳）。
• 动作类 API 采用单一 options 入参，同步取值类直接返回值。
• 错误码 7 位（GPS 专属段 92 开头），错误对象为 GpsFailure 接口（含 errSubject / errCode / errMsg / details），由 GpsFailureImpl 显式实现。
• intervalMs / distanceMeters 传负数时统一报错 9201006。
• GpsLocation 提供 horizontalAccuracy 与 verticalAccuracy 成对字段（命名与 iOS CoreLocation 一致）。
• 文档包含「定位模式」章节，明确 startWatch 默认持续定位（intervalMs 默认 1000）需手动 stopWatch 停止；单次定位须显式传 intervalMs: 0。
• startWatch 内部自动申请定位权限：backgroundMode: false 时申请前台权限（拒绝则 fail 返回 9201001），backgroundMode: true 时额外申请后台定位权限（拒绝则 fail 返回 9201004）。调用方无需先调 requestPermission / requestBackgroundPermission，二者均为可选 API（仅在你需提前单独控制申请时机时使用）。Web 端由浏览器 / uni 自动处理，无需调用方额外处理。

平台兼容性

uni-app(5.12)

uni-app x(5.12)

其他

lime-gps 系统定位

为 uni-app / uni-app x 提供的系统定位 UTS API 插件，同时支持 Android / iOS / Harmony / Web / 微信小程序。UTS 原生插件。

功能特性

• 定位权限申请：前台定位权限与后台定位能力，权限名由插件按平台兜底，调用方无需处理平台差异。
• 实时定位监听：持续回调最新位置，靠 intervalMs 区分单次 / 持续两种模式。
• 最近一次定位读取：随时取回缓存中的上一次定位结果。
• 运行环境查询与设置跳转：获取当前平台能力档案，并可跳转系统定位设置页。

安装

插件市场导入，在页面引入，自定义基座

自定义基座说明：

• 本插件使用 UTS 原生能力，APP必须在自定义基座中运行，标准基座无法使用
• CLI 项目特别注意：请检查根目录 package.json，确保所有 @dcloudio/* 相关包的版本号一致，且与当前 HBuilderX 版本对齐。版本不一致会导致自定义基座编译失败或运行异常

快速示例

import * as gps from '@/uni_modules/lime-gps'
import type {
    GpsLocation,
    GpsReadOptions,
    GpsWatchOptions
} from '@/uni_modules/lime-gps'

// startWatch 内部会自动申请定位权限，无需先调用 requestPermission
gps.startWatch({
    backgroundMode: true,
    cachedFirst: true,
    success: (location: GpsLocation) => {
        console.log(location.latitude, location.longitude)
    },
    fail: (err) => {
        console.error(err.errCode, err.errMsg)
    },
    complete: () => {}
} as GpsWatchOptions)

// 任意时刻读取最近一次定位
gps.readLastLocation({
    success: (location: GpsLocation) => {
        console.log(location.stage, location.latitude, location.longitude)
    },
    fail: (err) => console.error(err.errMsg)
} as GpsReadOptions)

类型导入与 as 标注：非 TS 环境（uni-app Vue / uni-app x vapor）下无需 import type 导入类型、也无需 as 标注，照示例去掉类型部分即可；只有 uni-app x 非 vapor 模式（默认 UTS 编译）这种强类型环境，才建议保留 import type 与 as GpsWatchOptions 以拿到准确提示。

定位模式：单次 vs 持续（必读）

startWatch 是同一个函数，靠 intervalMs 的值决定是「单次」还是「持续」。

单次定位示例

gps.startWatch({
  intervalMs: 0,                 // 关键：0 = 单次
  success: (location: GpsLocation) => {
    console.log('单次结果', location.latitude, location.longitude)
    // 这里 success 通常只进来一次（cachedFirst: true 时会有 cached + live 两次），之后引擎自动停止，无需 stopWatch
  },
  fail: (err: GpsFailure) => {
    console.error(err.errCode, err.errMsg)
  }
  // 注意：单次模式不要依赖 complete 做收尾
} as GpsWatchOptions)

持续定位示例

gps.startWatch({
  intervalMs: 1000,             // 关键：> 0 = 持续，默认就是 1000
  backgroundMode: true,
  cachedFirst: true,
  success: (location: GpsLocation) => {
    console.log('实时', location.latitude, location.longitude)
  },
  fail: (err: GpsFailure) => {
    console.error(err.errCode, err.errMsg)
  },
  complete: () => {
    console.log('监听已停止（stopWatch 或出错）')
  }
} as GpsWatchOptions)

// 不再需要时务必停止，否则引擎持续持有监听、后台也会耗电
gps.stopWatch()

realtime 事件驱动示例

gps.startWatch({
  realtime: true,            // 忽略 intervalMs 节拍，完全由系统定位事件驱动（静止设备/模拟器可能不再回吐）
  success: (location: GpsLocation) => {
    console.log('实时事件', location.latitude, location.longitude)
  },
  fail: (err: GpsFailure) => {
    console.error(err.errCode, err.errMsg)
  }
} as GpsWatchOptions)

对照表

想从单次切到持续：直接再调一次 startWatch({ intervalMs: 1000 }) 即可，引擎会先清掉上一次监听再重新注册。

API 参考

同步取值类（直接返回值）

动作类（options 入参）

类型与返回值

GpsLocation（startWatch 回调 / readLastLocation 返回值）

GpsRuntimeProfile（getRuntimeProfile 返回值）

各 Options 入参字段

startWatch 的 options（GpsWatchOptions）：

其余 options（readLastLocation / requestPermission / requestBackgroundPermission / stopWatch）仅含上述对应的 success / fail / complete 或 dismissNotification?（stopWatch，是否移除通知），语义相同。

GpsFailure（fail 回调入参）

错误码

fail 回调收到 GpsFailure（即 IUniError）：{ errSubject: 'lime-gps', errCode, errMsg, ... }。

注意事项

• permissionName 不传时各平台使用默认定位权限（Android ACCESS_FINE_LOCATION / iOS location / Harmony ohos.permission.LOCATION），无需调用方写平台分支。
• iOS 连续定位模式同样按 intervalMs 节拍回吐（因 iOS 的 CLLocationManager 原生不支持时间节流，内部用定时器模拟，对齐 Android 的系统级原生支持）；distanceMeters 映射为 iOS 的 distanceFilter；单次定位仍用 intervalMs: 0。若需要极致跟手、完全由系统定位事件驱动（无视 intervalMs 节拍），传 realtime: true 即可，代价是静止设备不再回吐心跳。
• Android 11+（API 30+）后台定位：系统要求 ACCESS_BACKGROUND_LOCATION 必须在前台定位权限已授予后单独申请，且会引导用户去系统设置选择「始终允许」。requestBackgroundPermission 已按此顺序串联调用，但最终是否授权仍取决于用户在系统设置中的选择。
• Harmony 后台定位：Harmony 要求 APPROXIMATELY_LOCATION 必须先于 LOCATION 申请，插件内部已处理；openSystemSettings 通过系统弹窗请求开启定位总开关，与其它端「跳转设置页」略有不同。
• readLastLocation 在 Android / iOS 优先返回应用内最近一次定位缓存，若从未启动过监听则回退到系统最近一次定位；Harmony 直接读取系统最近一次定位。
• 连续定位具备容错：监听过程中偶发的瞬时错误（如信号短暂丢失）不会中断监听，会继续等待下次可用定位；只有定位权限被收回（9201001）或确有错误时才回调 fail。

支持平台

坐标系说明（type 取值）

底层 uni 定位 API 的 type 参数用于指定坐标系，取值如下：

本插件所有平台统一返回 wgs84（系统原生 GPS 坐标，未做任何偏移加密）。 我们刻意不暴露 type 入参、固定为 wgs84，以避免引入地图厂商 key 依赖。若业务需叠加国内地图，请自行做 wgs84 → gcj02 / bd09 转换。

各平台原生配置

除标准基座外，各平台还有以下前置配置：

Android

• 所需权限已在插件 utssdk/app-android/AndroidManifest.xml 声明：ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、ACCESS_BACKGROUND_LOCATION、FOREGROUND_SERVICE、FOREGROUND_SERVICE_LOCATION、POST_NOTIFICATIONS。
• minSdk 需 ≥ 21（见 package.json）。
• 后台定位需用户在系统设置中将定位权限设为「始终允许」。

iOS

• 插件 utssdk/app-ios/info.plist 已声明 NSLocationWhenInUseUsageDescription、NSLocationAlwaysAndWhenInUseUsageDescription 与 UIBackgroundModes → location。
• 后台持续定位前，用户需在系统设置中授予应用「始终」定位权限。

Harmony

• 持续定位（含后台持续）：在宿主 EntryAbility 声明 backgroundModes: ["location"]，否则应用退到后台后无法持续获取定位。
• 后台定位权限：Harmony 的后台定位权限无法靠弹窗授予，需用户在系统设置把本应用定位设为「始终允许」（路径：设置 → 隐私与安全 → 位置 → 具体应用）。未设置时 startWatch({ backgroundMode: true }) 会返回 9201004；插件会通过 openAppSettings 拉起应用设置详情页引导用户跳转。

注意：插件已声明定位相关权限并会自动合并进宿主 entry，无需手动补齐；但插件无法声明 backgroundModes，需在宿主 harmony-configs/entry/src/main/module.json5 的 EntryAbility 上手动加上（也可直接取构建产物 unpackage/dist/dev/app-harmony/entry/src/main/module.json5 覆盖该目录）：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        // 需要持续 / 后台定位时加上
        "backgroundModes": ["location"]
      }
    ]
  }
}

修改 harmony-configs 后必须重新制作自定义基座并重新安装运行包——清单变更不会热更新。本工程已内置该文件，可直接运行。

隐私与权限声明

1. 所需系统权限：ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、ACCESS_BACKGROUND_LOCATION（Android）；定位相关权限（iOS / Harmony 见各平台原生配置）。
2. 数据采集与用途：仅在设备本地读取系统定位结果，不上传任何远程服务器，无远程采集与上报逻辑。

后台定位完整示例

后台定位只需在 startWatch 传入 backgroundMode: true，所需的后台权限会由插件内部自动申请（无需先调 requestBackgroundPermission）：

import * as gps from '@/uni_modules/lime-gps'
import type {
    GpsLocation,
    GpsWatchOptions
} from '@/uni_modules/lime-gps'

gps.startWatch({
    backgroundMode: true,
    cachedFirst: true,
    success: (location: GpsLocation) => {
        console.log(location.latitude, location.longitude)
    },
    fail: (err) => console.error(err.errCode, err.errMsg),
    complete: () => {}
} as GpsWatchOptions)

后台定位生效的前置条件：① 用户在系统设置授予「始终」定位权限（插件会弹框申请，拒绝则 fail 返回 9201004）；② 宿主应用完成上方「各平台原生配置」（尤其鸿蒙 EntryAbility 的 backgroundModes 与 iOS 的 info.plist）。两者缺一不可。若需提前单独控制申请时机，仍可显式调用 requestBackgroundPermission。

常见问题（FAQ）

• Q：返回的坐标系是什么？ A：统一为 wgs84（系统原生 GPS 坐标，未加密偏移）。需要叠加国内地图时请自行做 wgs84 → gcj02 / bd09 转换，详见上方「坐标系说明」。

• Q：退出页面再进入，回调不再触发？ A：连续定位是引擎级长连接。页面销毁前务必调用 stopWatch() 释放监听；否则引擎仍在后台持有监听，再次进入可能因实例未复位而不触发回调。

• Q：室内 / 工业设备定位失败或偏差很大？ A：本插件依赖系统 GPS，需开阔天空环境。室内、地下、金属遮挡场景下 GPS 信号弱属正常现象，定位精度由设备 GPS 模块决定。

• Q：Web 端能用吗？需要配 key 吗？ A：Web（Safari / Chrome）与微信小程序可用，走 uni 定位 API 兜底；但仅支持 wgs84，gcj02 需配地图厂商 key。Web 端不支持后台定位与跳转系统设置。

• Q：需要第三方地图 Key 吗？ A：不需要。本插件直接调用系统原生定位，不依赖高德 / 腾讯 / 百度等三方 Key，也不产生地图服务费用。