更新记录

1.0.0（2026-06-17）

首次更新

平台兼容性

uni-app(4.86)

uni-app x(4.86)

hl-gps-device-uts (工业级轨迹定位插件)

新手必读：
首次使用 UTS 插件，请优先阅读 《UTS 插件新手使用与调试指南》。

简介

hl-gps-device-uts 是一款针对外勤、物流、工业 PDA 场景设计的跨平台持续定位插件，侧重于后台常驻与异常坐标的过滤纠偏。

核心特性

• 后台常驻机制：底层整合 Android ForegroundService 与 WAKE_LOCK，保障应用在退后台及息屏状态下依然能够正常采集定位数据。
• 卡尔曼滤波平滑：内置数学滤波算法，对原生 GPS 坐标进行预测与纠偏，降低轨迹数据的毛刺现象。
• 阈值飞点过滤：支持自定义最大合理移动速度 (maxSpeedThreshold)，系统根据两点间的物理导数关系，在底层主动拦截并丢弃异常跳变点。
• 多通道无缝降级：优先采用 GPS_PROVIDER 进行高精度定位，在失去卫星信号的环境（如室内或隧道）中自动切换为 NETWORK_PROVIDER 定位通道，维持轨迹采集连贯。
• 极速缓存定位：启动时可提取系统 last_known 缓存位置，减少冷启动的等待时间。
• 向下兼容优化：通过 Java 动态代理重构底层接口调用，规避了 UTS 在部分老旧定制 Android 系统上的静态类编译兼容问题 (NoClassDefFoundError)。

快速接入

1. 初始化控制器

import * as HlGps from '@/uni_modules/hl-gps-device-uts';

const controller = HlGps.createGpsController({
  autoInitAdapt: true,               // 开启硬件自适应
  requestPermissionsIfNeeded: true   // 自动接管系统动态权限申请（含始终允许引导）
});

controller.initialize();

2. 注册数据监听

// 监听位置回传 (包含 provider 来源标识)
controller.onLocation((location) => {
  console.log(`[${location.provider}] 经纬度：${location.longitude}, ${location.latitude}`);
  console.log(`精度：${location.accuracy}m, 瞬时速度：${location.speed}m/s`);
});

// 监听卫星状态
controller.onGnssStatus((status) => {
  console.log(`可见卫星数: ${status.satelliteCount}, 参与定位数: ${status.usedInFixCount}`);
});

// 监听底层状态与日志
controller.onLog((log) => console.log(`[${log.level}] ${log.message}`));

3. 启动后台持续定位

controller.startLocation({
  title: "定位服务运行中",               // 常驻服务通知标题
  content: "正在记录移动轨迹...",         // 常驻服务通知内容
  minTime: 2000,                       // 最小定位回传间隔 (毫秒)
  minDistance: 0,                      // 最小距离变化阈值 (米)

  // 最大合理移动速度阈值 (m/s)
  // 用于过滤异常飞点，步行场景建议设为 3.0，车辆场景建议设为 35.0 及以上
  maxSpeedThreshold: 35.0 
});

4. 停止与释放

// 停止定位服务
controller.stopLocation();

// 退出页面时释放系统资源
controller.release();

参数说明与调试建议

maxSpeedThreshold 飞点过滤机制

在室内边缘等复杂环境中，GPS 信号易产生多径效应导致坐标漂移。 如果设置了较低的 maxSpeedThreshold，在室内环境测试时可能会观察到回调停止的情况。此时通过检查 onLog 日志可以确认底层是否触发了丢弃逻辑：

[WARN] GPS 异常跳点(速度 15.6m/s > 阈值 3.0)，已丢弃 [DEBUG] 被拦截：GPS精度超过 100m 阈值 (165m)，当作漂移点忽略

这代表算法拦截了无效数据。建议在排查业务流程时，至开阔室外环境中进行实际走动测试。