更新记录

1.0.4（2026-09-21）

修复ios打包问题

1.0.3（2026-08-26）

更新普通授权版接入

1.0.2（2026-08-19）

• 鸿蒙：修复 ArkTS 编译（wantAgent 改从 @kit.AbilityKit 导入；缓存读写、JSON 解析、HTTP 上报按 ArkTS 严格类型改写）
• 鸿蒙：权限声明改为 utssdk/app-harmony/module.json5 + $string:reason（仅写 config.json 不会进包，会导致 8030001）
• 鸿蒙：定位权限分步申请（先模糊+精确前台，再处理后台）；后台定位需系统设置「始终允许」
• 鸿蒙：定位订阅改为 ContinuousLocationRequest，启动前检查定位开关；intervalMs 上限放开到 60000ms
• 鸿蒙：GpsPoint 回调过 JS 桥丢字段时，Demo 用 getCachedPointsJson 兜底刷新首点展示
• Demo：默认每 60 秒出一次点；开启定位后自动申请权限

平台兼容性

uni-app(3.8.4)

keepalive-location

UTS 后台保活定位｜Android iOS 鸿蒙 Next｜外勤巡检后台持续 GPS 定位

三端 UTS 插件：后台定位启停、点位回调、权限内置、状态事件、本地环缓、可选 HTTPS 上报。普通授权 / 源码授权。

功能

• 后台定位开启 / 关闭；点位回调（经纬度、精度、速度、时间戳、高度）
• Android：前台服务 + 常驻通知，适配 8.0–14，唤醒锁；厂商自启动/白名单深链
• iOS：Background Modes location，Always 权限分步；挂起状态点位回调；附 App Store 审核文案模板
• 鸿蒙 Next：后台定位权限、长时任务自动续期、配额/取消监听
• 权限检测、申请、跳转设置（内置，不另发权限插件）
• 状态监听：权限丢失、系统限制、长时任务过期、服务异常、上报失败
• 统一错误码、demo、manifest 完整配置模板

安装

市场插件 ID 为 keepalive-location。本地目录名请与 ID 一致。

将本目录放入项目 uni_modules/keepalive-location，制作自定义调试基座后运行。

import {
    initTrack,
    startLocation,
    stopLocation,
    getStatus,
    onLocationUpdate,
    onStatusChange,
    destroy,
    requestPermissions,
    checkPermissions,
    openAppSettings,
    openVendorKeepAliveSettings,
    getCachedPoints,
    clearCachedPoints,
    flushUpload,
    getTrackCapabilities
} from '@/uni_modules/keepalive-location'

API

注意：对外初始化方法名为 initTrack（避免 iOS/Swift 保留字 init 导致云打包失败）。

坐标转换（插件点位为系统 WGS84）

返回值为 JSON 字符串（UTS 自定义对象跨 JS 桥易丢字段），需 JSON.parse。

import { toGaode, toBaidu, convertGpsPoint } from '@/uni_modules/keepalive-location'

onLocationUpdate((point) => {
  const gaode = JSON.parse(toGaode(point.latitude, point.longitude))
  const baidu = JSON.parse(toBaidu(point.latitude, point.longitude))
  // gaode.latitude / gaode.longitude
})

initTrack 选项

await initTrack({
    notificationTitle: '位置服务运行中',      // Android 通知标题
    notificationContent: '正在进行后台定位', // Android 通知内容
    enableWakeLock: true,                      // Android 唤醒锁
    enableForegroundService: true,             // Android 正式接入务必 true（后台保活）
    enableCache: true,
    cacheMaxPoints: 2000,
    upload: {                                  // 不传则不上报
        url: 'https://example.com/track',
        headers: [{ key: 'Authorization', value: 'Bearer xxx' }],
        batchSize: 20,
        intervalMs: 15000,
        includeDeviceId: false
    }
})

Android 前台服务（FGS）正式接入说明

正式接入 checklist：

1. initTrack({ enableForegroundService: true, notificationTitle, notificationContent })
2. 先 requestPermissions()（定位 + 后台定位 + 通知；Android 13+ 通知权限）
3. 制作自定义调试基座 或云打包（把 TrackForegroundService.kt + Manifest 打进包）
4. 开启定位后应出现常驻通知；没有通知却闪退 = FGS 未正确进包或权限不足
5. 建议引导用户关掉电池优化、加厂商白名单：openVendorKeepAliveSettings()

Demo 工程为避闪退可暂关 FGS；接入业务 App 时请打开。

startLocation 选项

await startLocation({
    distanceFilter: 0,    // 米；0=不按位移过滤
    desiredAccuracy: 10,  // 米
    intervalMs: 1500      // Android：即使静止也按此间隔回调并写本地缓存（默认 1500，夹到 1000–2000）
})

Android / iOS / 鸿蒙策略：系统定位只刷新内存最近点；定时器按 intervalMs 出点（有新 GPS 用新点，否则复用最近点并更新 timestamp）。

单次定位 getCurrentLocation

不启动后台跟踪，适合打卡、填表等一次性取点场景（需已授权定位）：

import { getCurrentLocation } from '@/uni_modules/keepalive-location'

const point = await getCurrentLocation({
  desiredAccuracy: 10,
  timeoutMs: 15000
})
console.log(point.latitude, point.longitude)

离线 / 无网络

• GPS 采集：Android / iOS / 鸿蒙在无移动网络时仍可通过 GPS 卫星定位（室内或弱信号时精度下降）
• 本地环缓：initTrack({ enableCache: true }) 后断网仍持续写缓存，getCachedPoints() 可读历史点
• 上报：仅在有网且配置 upload.url 时 HTTPS 上报；断网触发 8033001，恢复网络后 flushUpload()
• 不含离线地图 / 离线导航能力

权限变更后自动恢复

若在定位运行中将系统定位权限改为「禁止」，再改回「始终允许」：

1. 插件会发 permission_lost 状态事件并挂起原生会话（running 仍为 true）
2. 定时器 / resumeLocation() 检测到权限恢复后，自动重建 Android FGS 通知、iOS CL 会话、鸿蒙长时任务
3. 建议在 App onShow 中调用 resumeLocation()，从设置页返回时更快恢复

GpsPoint

上报 JSON

{
    "deviceId": "optional",
    "platform": "android|ios|harmony",
    "points": [{ "latitude": 0, "longitude": 0, "accuracy": 0, "speed": 0, "altitude": 0, "timestamp": 0, "provider": "gps" }]
}

仅支持 HTTPS POST。

错误码 803xxxx

Android manifest 模板

在 manifest.json → app-plus → distribute → android 中确保权限（插件 AndroidManifest.xml 也会合并）：

• ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION
• ACCESS_BACKGROUND_LOCATION
• FOREGROUND_SERVICE / FOREGROUND_SERVICE_LOCATION
• POST_NOTIFICATIONS
• WAKE_LOCK
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
• INTERNET（仅当使用上报）

Android 14 需声明前台服务类型 location（本插件已带 Service）。

厂商白名单：调用 openVendorKeepAliveSettings()，覆盖小米 / 华为荣耀 / OPPO / vivo / 三星常见页；失败回落应用设置。深链因系统版本可能失效。

iOS 配置模板

manifest.json：

"app-plus": {
    "ios": {
        "capabilities": {
            "UIBackgroundModes": ["location"]
        },
        "privacyDescription": {
            "NSLocationWhenInUseUsageDescription": "需要在使用期间获取您的位置，用于外勤巡检与轨迹记录",
            "NSLocationAlwaysAndWhenInUseUsageDescription": "需要在后台持续获取您的位置，用于外勤巡检、轨迹记录与现场任务核验",
            "NSLocationAlwaysUsageDescription": "需要在后台持续获取您的位置，用于外勤巡检、轨迹记录与现场任务核验"
        }
    }
}

App Store 审核文案模板（可直接改写提交）

用途说明（App Review Notes）：

本应用为外勤巡检 / 现场作业类工具。开启「始终」定位后，员工在巡检途中将 App 置于后台或锁屏时，仍需持续记录 GPS 轨迹，用于任务核验、路线留痕与异常位移告警。我们仅在用户主动开始巡检任务后采集位置，任务结束后立即停止；位置数据用于业务方自有服务器（可选上报），不用于广告追踪。

权限弹窗文案建议： 与上方 privacyDescription 保持一致，强调「外勤巡检 / 轨迹记录」。

鸿蒙 Next 配置

权限必须写在插件 utssdk/app-harmony/module.json5（并配套 resources/.../string.json 的 $string:reason），仅写 config.json 不会打进鸿蒙包，会导致 requestPermissions 永远 location:false / 8030001。

插件已声明：

• ohos.permission.LOCATION / APPROXIMATELY_LOCATION
• ohos.permission.LOCATION_IN_BACKGROUND
• ohos.permission.KEEP_BACKGROUND_RUNNING
• ohos.permission.INTERNET（上报时）

主工程 EntryAbility 需配置 backgroundModes: ["location"]（可用项目根目录 harmony-configs/entry/src/main/module.json5 覆盖）。长时任务类型为 LOCATION；插件会定时续期并监听取消事件（long_task_expired / 8031004）。

操作顺序：先 requestPermissions() 弹窗授权，再 startLocation()。若曾拒绝，需到系统设置里打开定位权限。

普通授权版接入

1. 从插件市场导入 keepalive-location，制作自定义调试基座
2. 在项目根目录创建/编辑 harmony-configs/entry/src/main/module.json5：
   • deviceTypes 增加 tablet、2in1
   • EntryAbility 配置 backgroundModes: ["location"]
3. 业务代码 import 插件 API，先 requestPermissions() 再 startLocation()
4. 重新运行到鸿蒙（改 harmony-configs 必须重新编译）

插件内的鸿蒙权限与平板 deviceTypes 已内置，无需修改 uni_modules 目录。

最小示例

import {
    initTrack,
    requestPermissions,
    onLocationUpdate,
    onStatusChange,
    startLocation,
    stopLocation,
    resumeLocation,
    getCurrentLocation,
    destroy
} from '@/uni_modules/keepalive-location'

onLocationUpdate((p) => console.log('point', p))
onStatusChange((s) => console.log('status', s))

await initTrack({ enableCache: true })
await requestPermissions()
await startLocation({ distanceFilter: 10, desiredAccuracy: 50 })
// ...
await stopLocation()
destroy()

隐私声明

1. 本插件申请定位、后台定位、前台服务、通知、唤醒锁、电池优化、鸿蒙长时任务等权限，详见上文。
2. 点位可本地环缓；仅当业务配置 upload.url 时向该地址 HTTPS 上报。插件不默认上传至第三方。
3. 不含广告 SDK。