更新记录

1.1.0（2026-04-03）

• 新增 iOS 端实现（CLLocationManager 后台定位）
• Android 端改用 Foreground Service 替代普通通知，修复切后台定位丢失
• WakeLock 增加 4 小时超时保护
• 补全异常日志，移除空 catch
• 前端页面优化：提取工具函数、CSS 兼容性改进、按钮状态管理

1.0.0（2026-03-03）

专为 uni-app 打造的原生高精度 GPS 插件，支持息屏后台持续追踪、卫星信号监控，极致稳定，零配置接入。

平台兼容性

uni-app(4.51)

uni-app x(4.51)

jwh-dw

uni-app x 原生 GPS 定位 UTS 插件，支持 Android / iOS 双平台后台持续定位。

适用于轨迹记录、运动健身、外勤打卡等需要后台定位的场景。

特性

• 直接调用系统 GPS API，无 JS 桥接开销
• Android：Foreground Service + WakeLock 保活
• iOS：CLLocationManager 后台定位模式
• 启动时返回缓存位置，无需等待搜星
• 权限和清单文件已内置，导入即用

平台支持

快速上手

开始定位

import { onStartLocation } from '@/uni_modules/jwh-dw'

onStartLocation({
  interval: 2000,             // 定位间隔，毫秒（仅 Android）
  enableBackground: true,     // 后台定位（双平台）
  notificationTitle: "定位中", // 通知标题（仅 Android）
  notificationText: "正在记录轨迹",
  success(res) {
    console.log(res.latitude, res.longitude, res.accuracy)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  }
})

停止定位

import { stopLocation } from '@/uni_modules/jwh-dw'
stopLocation()

权限处理

首次使用需要先申请权限，建议在 onShow 中检测：

import { checkPermission, requestPermission, onStartLocation } from '@/uni_modules/jwh-dw'

function start() {
  if (!checkPermission()) {
    requestPermission()
    return
  }
  onStartLocation({
    interval: 2000,
    enableBackground: true,
    success(res) { console.log(res) },
    fail(err) { console.error(err) }
  })
}

获取缓存位置

import { getLastKnownLocation } from '@/uni_modules/jwh-dw'

const pos = getLastKnownLocation()
if (pos) {
  console.log(pos.latitude, pos.longitude)
}

API

onStartLocation(options)

启动持续定位。

options 参数：

stopLocation()

停止定位，释放资源。

checkPermission(): boolean

检查是否已获得定位权限。

requestPermission()

请求系统定位权限弹窗。Android 上会按 前台权限 -> 后台权限 的顺序串行申请。

getLastKnownLocation(): LocationResult | null

获取系统缓存的最近一次位置，可能为 null。

数据结构

LocationResult

provider 取值：

错误码

注意事项

1. GPS 定位需要在室外开阔环境，室内/地库/隧道可能无法定位
2. 持续定位较耗电，不用时请调用 stopLocation()
3. Android 10+：后台定位需要用户授予"始终允许"权限
4. Android：后台定位通过前台服务实现，状态栏会显示通知图标
5. iOS：后台定位需要"始终允许"权限；首次可能只拿到"使用时允许"，再调一次 requestPermission() 即可升级
6. iOS：后台定位时状态栏会显示蓝色指示条，这是系统行为

内置配置

插件已自动配置以下内容，无需手动修改：

• Android：ACCESS_FINE_LOCATION、ACCESS_BACKGROUND_LOCATION、FOREGROUND_SERVICE、FOREGROUND_SERVICE_LOCATION、POST_NOTIFICATIONS 等权限 + 前台服务组件声明
• iOS：UIBackgroundModes: location + 定位隐私描述（NSLocationWhenInUseUsageDescription 等）