更新记录

1.0.0（2026-05-30） 下载此版本

初次提交

平台兼容性

uni-app x(4.75)

其他

laoqianjunzi-gps

laoqianjunzi-gps 是一个面向 uni-app x 的系统定位 UTS 插件，提供统一的定位权限申请、最近一次定位读取、实时监听、后台定位能力申请与运行时能力查询接口。

本文档只说明当前插件对外暴露的统一 API，适合直接在 uvue 页面或 uts 逻辑中接入。

插件定位

• 适用框架：uni-app x
• 最低 HBuilderX 版本：5.07
• 建议 uni-app x 版本：4.75 及以上
• 支持平台：Web、Android、iOS、Harmony
• Android 最低版本：minSdkVersion 21
• iOS 最低版本：12.0
• 插件类型：UTS 原生插件

能力概览

已提供的核心能力

• 统一的前台定位权限申请接口
• 统一的后台定位能力申请接口
• 读取最近一次缓存定位
• 启动实时定位监听
• 支持对象回调和 tuple 回调两种结果形式
• 查询运行时能力与平台特征
• Android 前台服务通知栏托管

平台能力矩阵

安装与导入

将插件放入项目的 uni_modules 目录后，可直接导入使用，无需额外安装 JavaScript 依赖。

import {
    askPermission,
    describeRuntime,
    hasPermission,
    isSwitchEnabled,
    openSystemSettings,
    prepare,
    readLastSnapshot,
    requestBackgroundMode,
    startWatch,
    stopWatch,
    type LqjGpsReading,
    type LqjGpsWatchOptions
} from "@/uni_modules/laoqianjunzi-gps"

快速开始

推荐接入顺序：

1. 页面加载后先调用 prepare()
2. 按平台选择定位权限名
3. 调用 askPermission() 申请前台定位权限
4. 如需后台定位，先调用 requestBackgroundMode()
5. 使用 startWatch() 或 startTuple() 开始监听
6. 页面销毁时调用 stopWatch()

最小可用示例

<script setup lang="uts">
import {
    askPermission,
    prepare,
    startWatch,
    stopWatch,
    type LqjGpsReading,
    type LqjGpsWatchOptions
} from "@/uni_modules/laoqianjunzi-gps"

let permissionName = 'location'

// #ifdef APP-ANDROID
permissionName = 'android.permission.ACCESS_FINE_LOCATION'
// #endif

// #ifdef APP-IOS
permissionName = 'location'
// #endif

// #ifdef APP-HARMONY
permissionName = 'ohos.permission.LOCATION'
// #endif

// #ifdef WEB
permissionName = 'location'
// #endif

function startDemo() : void {
    const options : LqjGpsWatchOptions = {
        intervalMs : 1000,
        distanceMeters : 0,
        backgroundMode : false,
        emitCachedFirst : true,
        notificationTitle : '定位服务运行中',
        notificationText : '应用正在持续获取位置信息',
        notificationIconName : null
    }

    startWatch(options, (reading : LqjGpsReading) => {
        console.log('定位结果', reading.stage, reading.latitude, reading.longitude, reading.message)
    })
}

onMounted(() => {
    prepare()
    askPermission(permissionName, (granted : boolean) => {
        if (granted) {
            startDemo()
        }
    })
})

onUnmounted(() => {
    stopWatch(true)
})
</script>

API 总览

导出方法

prepare() : void
describeRuntime() : LqjGpsRuntimeProfile
hasPermission(permissionName : string) : boolean
askPermission(permissionName : string, callback : (granted : boolean) => void) : void
isSwitchEnabled() : boolean
openSystemSettings() : void
requestBackgroundMode(callback : (granted : boolean) => void) : void
readLastTuple(callback : (stage : 0 | 1 | 2, latitude : number, longitude : number, speed : number, altitude : number, heading : number) => void) : void
readLastSnapshot(callback : (reading : LqjGpsReading) => void) : void
startTuple(options : LqjGpsWatchOptions, callback : (stage : 0 | 1 | 2, latitude : number, longitude : number, speed : number, altitude : number, heading : number) => void) : void
startWatch(options : LqjGpsWatchOptions, callback : (reading : LqjGpsReading) => void) : void
stopWatch(dismissNotification : boolean) : void

prepare()

用于初始化插件运行上下文。

• 建议调用时机：页面 onMounted、组件初始化、首次定位前
• Android：绑定当前 Activity 并准备原生定位引擎
• iOS：初始化 CLLocationManager
• Harmony：清理上一次残留监听状态
• Web：空实现，可直接调用

describeRuntime()

返回当前平台的运行时能力。

返回值类型：LqjGpsRuntimeProfile

hasPermission(permissionName)

检查当前平台下某个定位权限是否已经授权。

推荐传入的权限名见下文“权限参数说明”。

注意事项：

• Web 端的结果基于当前运行期内是否成功获取过定位，并不是浏览器权限面板的完整映射
• iOS 端如果传入带有 background 或 always 含义的字符串，会按后台定位权限判断
• Harmony 端会按传入的原生权限名精确判断

askPermission(permissionName, callback)

申请前台定位权限。

• callback(true)：权限已授予
• callback(false)：权限被拒绝、当前环境不可申请或系统服务不可用

建议：

• Android 使用 android.permission.ACCESS_FINE_LOCATION
• iOS 使用 location
• Harmony 使用 ohos.permission.LOCATION
• Web 使用 location

isSwitchEnabled()

检查系统定位总开关是否可用。

• Android：检查 GPS 或网络定位是否启用
• iOS：检查系统定位服务是否开启
• Harmony：检查系统定位服务是否开启
• Web：固定返回 true

openSystemSettings()

尝试打开系统定位设置相关页面。

• Android：打开系统定位开关页面
• iOS：打开当前应用的系统设置页
• Harmony：触发系统定位开关请求
• Web：空实现

requestBackgroundMode(callback)

申请后台定位能力。

• Android：必要时请求 ACCESS_BACKGROUND_LOCATION
• iOS：申请 Always 定位授权
• Harmony：申请 LOCATION_IN_BACKGROUND 与 KEEP_BACKGROUND_RUNNING
• Web：固定返回 false

建议仅在业务明确需要后台持续定位时调用。

readLastTuple(callback)

读取最近一次定位结果，使用 tuple 结构回调。

参数说明：

说明：

• 本方法优先返回最近一次已有结果，部分平台在没有缓存时会主动补读一次定位
• 若当前没有缓存定位、权限未授予或系统服务不可用，会回调错误阶段

readLastSnapshot(callback)

读取最近一次定位结果，使用对象结构回调。

返回类型：LqjGpsReading

推荐优先使用本方法，便于保留错误信息与精度字段。

startTuple(options, callback)

启动定位监听，回调为 tuple 结构。

• 适合只关心经纬度和少量基础数值的场景
• 遇到错误时 stage 为 2
• intervalMs 为 0 时按单次实时定位处理

startWatch(options, callback)

启动定位监听，回调为 LqjGpsReading 对象。

• 适合业务页面、日志展示、状态机判断
• emitCachedFirst 为 true 时，可能先收到一条 cached 结果
• 后续实时结果的 stage 为 live
• 失败时会收到 stage = 'error' 的对象

stopWatch(dismissNotification)

停止当前定位监听。

• Android：dismissNotification = true 时会同时关闭前台定位通知
• iOS：停止系统定位更新，忽略通知参数
• Harmony：停止定位监听并结束后台运行状态
• Web：取消浏览器侧位置更新监听

建议页面退出时始终调用一次。

监听参数说明

startTuple() 与 startWatch() 共用 LqjGpsWatchOptions。

参数行为说明

• intervalMs = 0：触发单次实时定位，拿到一条实时结果后自动停止
• distanceMeters > 0：App 端会按位移阈值过滤回调，Web 端不依赖该参数做严格距离过滤
• backgroundMode = true：启动前应先调用 requestBackgroundMode()
• emitCachedFirst = true：适合先展示最近位置，再等待实时结果

权限参数说明

推荐按平台使用以下权限名。

插件已包含的原生权限声明

Android 已声明：

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

iOS 已声明：

• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription
• UIBackgroundModes -> location

Harmony 已声明：

• ohos.permission.LOCATION
• ohos.permission.APPROXIMATELY_LOCATION
• ohos.permission.LOCATION_IN_BACKGROUND
• ohos.permission.KEEP_BACKGROUND_RUNNING

后台定位说明

Android

• 使用后台定位时会启动前台服务
• notificationTitle、notificationText、notificationIconName 会体现在系统通知栏
• Android 10 及以上需要后台定位权限
• Android 13 及以上如果系统通知权限被禁用，前台服务通知展示可能受到系统限制

iOS

• 后台定位依赖 Always 授权与 location 后台模式
• 通知栏参数不会生效
• 建议在用户明确知情的业务场景中再申请后台能力

Harmony

• 后台定位依赖 LOCATION_IN_BACKGROUND 与 KEEP_BACKGROUND_RUNNING
• 插件会进入后台运行状态保持持续定位
• 通知栏参数不会生效

Web

• 不支持后台定位模式
• requestBackgroundMode() 固定回调 false

阶段值与错误码

阶段值

错误码语义

说明：

• 对象回调会通过 message 返回错误文本
• tuple 回调只用 stage = 2 表示失败，不携带详细错误文本
• 需要精确区分失败原因时，优先使用 readLastSnapshot() 与 startWatch()

使用示例

查询运行时能力

const runtime = describeRuntime()

console.log(runtime.platformName)
console.log(runtime.supportsBackgroundMode)
console.log(runtime.supportsOpenSettings)
console.log(runtime.usesNativeEngine)

读取最近一次定位

readLastSnapshot((reading) => {
    if (reading.stage == 'error') {
        console.log('读取失败', reading.message)
        return
    }
    console.log('最近定位', reading.latitude, reading.longitude)
})

启动后台定位

requestBackgroundMode((granted : boolean) => {
    if (granted == false) {
        console.log('后台定位能力未授予')
        return
    }

    startWatch({
        intervalMs : 3000,
        distanceMeters : 10,
        backgroundMode : true,
        emitCachedFirst : true,
        notificationTitle : '后台定位中',
        notificationText : '正在持续获取位置信息',
        notificationIconName : null
    }, (reading) => {
        console.log(reading.stage, reading.latitude, reading.longitude)
    })
})

示例页面

插件内置了一个完整演示页，可用于直接验证权限、缓存定位、实时监听与后台能力：

• 页面路径：uni_modules/laoqianjunzi-gps/pages/index

演示页包含：

• 运行时能力展示
• 权限状态展示
• 系统定位开关状态展示
• 最近一次定位读取
• tuple 监听与对象监听
• 后台模式申请
• 日志输出与参数面板

平台差异说明

• Web 端的 hasPermission() 仅反映当前运行期内是否成功获取过定位结果
• Web 端不支持后台定位，也不提供系统设置跳转
• Android 后台模式依赖前台服务，通知栏参数只在 Android 有效果
• iOS 后台定位由系统授权流程决定，建议配合业务提示文案使用
• Harmony 连续监听的时间粒度会按秒级请求系统能力
• distanceMeters 在 Harmony 端由插件层按位移阈值过滤回调

接入建议

• 首次进入页面时先调用 prepare()
• 先申请前台定位权限，再启动定位监听
• 需要后台持续定位时，单独调用 requestBackgroundMode()
• 页面离开、页面隐藏或业务结束时及时调用 stopWatch()
• 需要保留错误细节、精度字段时，优先使用对象回调接口
• 需要最简数值结果时，可使用 tuple 回调接口

隐私与数据说明

• 插件只负责读取系统定位结果
• 插件本身不内置远程上传、账号绑定、轨迹存储与服务端同步逻辑
• 若业务需要上传轨迹或保存历史位置，应由业务侧自行实现并补充隐私说明