更新记录

1.0.0（2026-02-03）

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

平台兼容性

uni-app(4.51)

uni-app x(4.51)

jwh-dw 高精度 GPS 定位 & 后台追踪 UTS 插件

jwh-dw 是一款专为 uni-app x 打造的高性能 UTS 原生插件。它深度封装了 Android 和 iOS 系统的底层定位能力，旨在为开发者提供稳定、高精度、低功耗的定位服务，特别适用于轨迹记录、运动健身、外勤打卡等对后台定位稳定性要求极高的场景。

🚀 核心优势

• 原生 UTS 开发：零性能损耗，直接调用系统级 API，响应速度远超 JS 层模拟。
• 高精度 GPS 优先：强制请求硬件级 GPS 卫星数据，提供经纬度、海拔、速度、精度等全量信息。
• 智能心跳补发：解决原地不动时系统不回调的问题。当设备静止且系统停止推送位置时，插件会自动按设定间隔补发最后一次位置，确保业务逻辑（如心跳上传）持续触发。
• 强大的后台生命力：
  • Android：内置前台服务（Foreground Service）与唤醒锁（WakeLock），有效对抗系统休眠和杀进程。
  • iOS：完美支持 allowsBackgroundLocationUpdates，支持息屏持续更新。
• 卓越的用户体验：
  • 秒开定位：iOS 端启动即返回缓存位置，随后平滑过渡到精准定位。
  • 信号实时监控：提供可见卫星数、参与定位卫星数及平均信噪比（SNR）。
• 零配置接入：插件已内置双平台权限自动配置，开发者无需手动修改 AndroidManifest.xml 或 Info.plist。

🛠️ 平台兼容性

📦 自动配置说明

本插件已在 utssdk 目录中完成以下自动配置，您只需导入插件即可直接使用：

• Android：自动注入 ACCESS_FINE_LOCATION、ACCESS_BACKGROUND_LOCATION、FOREGROUND_SERVICE、POST_NOTIFICATIONS 等 8 项必要权限。
• iOS：自动配置 UIBackgroundModes 包含 location，并预设了专业的中文权限申请描述语。

📖 API 使用手册

1. 开启定位 onStartLocation

启动持续定位服务，支持配置后台运行。

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

onStartLocation({
  interval: 2000, // 定位间隔（毫秒，Android 用于 requestLocationUpdates；iOS 用于心跳补发）
  enableBackground: true, // 是否开启后台定位更新
  notificationTitle: "轨迹记录中", // 前台通知标题（仅 Android 生效）
  notificationText: "正在为您提供高精度定位服务", // 前台通知内容（仅 Android 生效）
  success: (res) => {
    console.log(`位置更新: ${res.longitude}, ${res.latitude}`);
    console.log(`当前精度: ${res.accuracy}米, 来源: ${res.provider}`);
  },
  fail: (err) => {
    console.error(`启动失败: [${err.errCode}] ${err.errMsg}`);
  },
  complete: (msg) => {
    console.log("定位状态:", msg);
  }
})

2. 首次授权建议流程（Android）

Android 第一次申请权限时，本插件会弹出系统授权框，但不会在用户点击“允许”后自动续接启动。推荐流程如下：

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

function start() {
  if (!checkPermission()) {
    requestPermission()
    return
  }
  onStartLocation({
    interval: 2000,
    success: (res) => console.log("定位:", res),
    fail: (err) => console.error(err),
  })
}

// 可以在页面 onShow / App 回到前台后再次调用 start()

3. 获取最近位置 getLastKnownLocation

无需等待搜星，立即获取系统最后缓存的位置，实现“启动即显示”。

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

const lastPos = getLastKnownLocation();
if (lastPos) {
  console.log("缓存位置:", lastPos.latitude, lastPos.longitude);
}

4. 获取卫星状态 getGnssStatus

获取当前 GPS 信号的详细状态（iOS 端基于定位精度模拟显示）。

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

const status = getGnssStatus();
console.log(`搜星情况: 可见卫星 ${status.satelliteCount}, 参与定位 ${status.usedInFixCount}`);
console.log(`平均信噪比: ${status.averageSnr} dBHz`);

5. 停止定位 stopLocation

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

6. 权限手动检查

• checkPermission(): 检查当前是否已获得定位授权。
• requestPermission(): 引导用户触发系统授权弹窗。

📊 数据结构

LocationResult (定位结果)

⚠️ 注意事项

1. 搜星环境：由于本插件强制使用 GPS 硬件，在室内、地库、隧道等遮挡严重区域可能无法获取定位。测试时请务必前往室外开阔地带。
2. Android 10+ 后台定位：用户必须在系统设置中手动选择“始终允许”位置权限，插件才能在应用完全退出后保持运行。
3. iOS 精确定位：iOS 14+ 用户可以关闭“精确定位”开关，此时插件获取的精度会大幅下降（约 5km 范围）。
4. iOS 通知设置：notificationTitle 和 notificationText 参数在 iOS 上无效。iOS 系统在后台定位时会自动在状态栏显示蓝色指示器，开发者无法自定义其文字内容。
5. 电量消耗：高精度持续定位会消耗更多电量，请在业务不需要时及时调用 stopLocation 以节省能耗。
6. 卫星状态差异：Android 通过 GnssStatus 获取真实卫星数据；iOS 不开放同等 API，本插件返回的是基于精度的模拟值。

📩 反馈与支持

如果您在使用过程中遇到任何问题，欢迎在插件市场评价区留言或联系开发者。