更新记录

1.1.1（2026-06-16）

• 优化 Android 前台定位与后台定位权限判断，避免前台定位被后台权限阻塞
• 优化 Android 11+ 后台定位授权流程，引导到应用设置页授予"始终允许"
• 优化 Android 前台服务启动失败和动态广播注册兼容处理
• 优化 iOS 后台定位授权判断，后台定位明确要求 Always 权限
• 曾新增后台权限检查参数，已在 1.1.3 因 iOS 桥接兼容问题回退为无参方法
• 兼容 Android 13+ getParcelableExtra(name, Class) 新签名，消除废弃 API 编译警告
• 统一 HBuilderX 最低版本声明为 4.25+
• 修复 iOS 端 checkPermission(true) 触发 UTS 桥接方法调用失败的问题
• checkPermission() 恢复为无参基础定位权限检查，后台权限由 onStartLocation({ enableBackground: true }) 启动时校验
• 优化 iOS 启动定位后的连续回调问题，按 interval 控制回调最小间隔
• iOS 增加相同定位时间戳去重，避免缓存点和实时点重复触发业务回调

1.1.5（2026-06-16）

• 修复 iOS 云打包 Swift 编译错误：resetCallbackThrottle() 缺少参数
• 调整 iOS 节流重置调用，避免 UTS 可选参数生成 Swift 后无法无参调用

1.1.0（2026-04-03）

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

平台兼容性

uni-app(4.51)

uni-app x(4.51)

jwh-dw

jwh-dw 是一个 UTS 原生 GPS 定位插件，支持 Android / iOS 双平台持续定位与后台定位。

插件适用于轨迹记录、运动健身、外勤打卡、巡检签到、配送跟踪等需要稳定获取 GPS 坐标的 App 场景。

功能特性

• Android / iOS 双平台原生定位
• 支持前台持续定位
• 支持后台持续定位
• Android 使用 Foreground Service 保持后台定位
• Android 使用 WakeLock 辅助提升后台存活稳定性
• iOS 使用 CLLocationManager 后台定位模式
• 启动时优先返回系统缓存位置，减少首次等待时间
• 内置 Android 权限、前台服务声明和 iOS 后台定位配置
• API 简单，支持 Vue2、Vue3、uni-app x

平台要求

支持范围

快速接入

1. 导入 API

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

2. 检查并申请权限

如果只需要前台定位，使用 checkPermission()。

if (!checkPermission()) {
  requestPermission()
}

后台定位也先使用 checkPermission() 检查基础定位权限。是否具备后台定位所需的“始终允许”权限，会在 onStartLocation({ enableBackground: true }) 启动时校验。

3. 启动前台定位

onStartLocation({
  interval: 2000,
  enableBackground: false,
  success(res) {
    console.log('latitude:', res.latitude)
    console.log('longitude:', res.longitude)
    console.log('accuracy:', res.accuracy)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  }
})

4. 启动后台定位

function startBackgroundLocation() {
  if (!checkPermission()) {
    requestPermission()
    return
  }

  onStartLocation({
    interval: 2000,
    enableBackground: true,
    notificationTitle: '轨迹记录中',
    notificationText: '正在为您提供高精度定位服务',
    success(res) {
      console.log('location:', res)
    },
    fail(err) {
      console.error('start location failed:', err.errCode, err.errMsg)
    },
    complete(res) {
      console.log('location complete:', res)
    }
  })
}

5. 停止定位

stopLocation()

建议在不需要定位时主动停止，例如页面销毁、轨迹结束、用户退出任务时调用。

onUnload() {
  stopLocation()
}

6. 获取缓存位置

const last = getLastKnownLocation()

if (last != null) {
  console.log(last.latitude, last.longitude)
}

缓存位置来自系统最近一次定位结果，可能为空，也可能不是当前最新坐标。

推荐使用流程

1. 页面进入时调用 checkPermission() 判断基础定位权限状态。
2. 未授权时调用 requestPermission() 触发系统授权流程。
3. 用户授权后重新调用 onStartLocation() 启动定位。
4. 后台定位场景传入 enableBackground: true。
5. 业务结束后调用 stopLocation() 释放资源。

后台定位需要用户明确授权。Android 11+ 通常需要跳转到系统设置页手动选择“始终允许”；iOS 需要用户授予“始终允许”定位权限。

API

onStartLocation(options)

启动持续定位。成功后会持续触发 success 回调。

onStartLocation(options: StartLocationOptions): void

stopLocation()

停止持续定位，并释放定位监听、广播接收器、前台服务、WakeLock 等资源。

stopLocation(): void

checkPermission()

检查定位权限。

checkPermission(): boolean

返回值说明：

后台定位权限会在 onStartLocation({ enableBackground: true }) 时进一步校验。如果缺少后台定位权限，fail 会返回 9010001。

requestPermission()

请求系统定位权限。

requestPermission(): void

平台差异：

如果用户选择拒绝，后续可能需要用户手动到系统设置中重新开启权限。

getLastKnownLocation()

获取系统缓存的最近一次位置。

getLastKnownLocation(): LocationResult | null

返回 null 表示当前系统没有可用缓存位置。

数据结构

StartLocationOptions

type StartLocationOptions = {
  interval?: number
  enableBackground?: boolean
  notificationTitle?: string
  notificationText?: string
  success: (res: LocationResult) => void
  complete?: (res: any) => void
  fail?: (err: MyApiFail) => void
}

LocationResult

type LocationResult = {
  latitude: number
  longitude: number
  altitude: number
  speed: number
  accuracy: number
  time: number
  provider: string
}

provider 取值：

MyApiFail

type MyApiFail = {
  errSubject: string
  errCode: 9010001 | 9010002 | 9010003 | 9010004
  errMsg: string
}

错误码

权限说明

插件已内置以下原生配置，正常情况下导入插件后无需手动添加。

Android

内置权限：

• android.permission.ACCESS_FINE_LOCATION
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_BACKGROUND_LOCATION
• android.permission.WAKE_LOCK
• android.permission.FOREGROUND_SERVICE
• android.permission.FOREGROUND_SERVICE_LOCATION
• android.permission.POST_NOTIFICATIONS
• android.permission.INTERNET

内置组件：

• LocationForegroundService
• foregroundServiceType="location"

iOS

内置配置：

• UIBackgroundModes: location
• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription

平台注意事项

Android

• 后台定位依赖前台服务，系统通知栏会显示常驻定位通知。
• Android 10+ 后台定位需要“始终允许”权限。
• Android 11+ 后台定位权限通常无法直接弹窗授予，需要用户进入系统设置页手动开启。
• Android 13+ 后台定位时还需要通知权限，否则前台服务通知无法正常显示。
• 部分国产 ROM 会限制后台运行，建议提示用户关闭电池优化或允许后台运行。
• 室内、地库、隧道等 GPS 信号弱的环境可能无法及时返回高精度坐标。

iOS

• 后台定位需要“始终允许”权限。
• iOS 首次授权可能只能获得“使用 App 期间允许”，再次调用 requestPermission() 可尝试升级为“始终允许”。
• 后台定位时系统可能显示蓝色定位指示条或定位图标，这是 iOS 系统行为。
• iOS 对后台定位有系统级策略限制，长时间定位建议结合真实运动或业务场景使用。

常见问题

1. 调用后返回 9010001

表示定位权限不足。前台定位请确认已经授予定位权限；后台定位请确认已经授予“始终允许”。

2. Android 返回 9010004

表示通知权限未授权。后台定位需要启动前台服务，前台服务必须显示通知，因此需要用户允许通知权限。

3. 为什么 checkPermission() 是 true，但后台定位启动失败？

checkPermission() 只检查基础定位权限。后台定位还需要“始终允许”权限，插件会在 onStartLocation({ enableBackground: true }) 时进一步校验；如果权限不足，会通过 fail 返回 9010001。

4. 为什么第一次启动定位没有实时坐标？

GPS 首次定位需要等待系统搜星。插件会优先返回系统缓存位置，但缓存可能为空。建议在室外开阔环境测试。

5. 为什么 Android 11+ 申请后台定位会打开设置页？

这是系统权限策略。Android 11+ 对后台定位权限限制更严格，很多设备不允许应用直接弹窗授予“始终允许”，需要用户在应用设置中手动选择。

6. 小程序或 H5 可以用吗？

不可以。该插件是 UTS 原生 App 插件，仅支持 App Android 和 App iOS。

调试建议

• 使用真机测试，不建议只依赖模拟器。
• GPS 定位建议在室外开阔环境测试。
• Android 后台定位测试时确认通知权限、定位权限、电池优化状态。
• iOS 后台定位测试时确认权限为“始终允许”。
• 每次修改原生配置后建议重新打包自定义基座或正式包。

版本

当前版本：1.1.5

更新记录请查看 changelog.md。