更新记录

1.0.3（2026-09-24） 下载此版本

• 插件 ID 改为当前作者名下的 zhuanz-gpslocation，同步修改目录名、示例引用和 Android 通知渠道 ID
• 完善 iOS 定位授权状态处理，支持先申请使用期间权限再升级为始终允许
• iOS 持续定位按毫秒间隔过滤回调，完善缓存位置、单次定位和停止清理
• 鸿蒙开始定位时自动分步申请前台与后台定位权限
• 鸿蒙持续后台定位启动系统定位长时任务，停止时同步释放
• 修正鸿蒙定位间隔单位，对外仍统一使用毫秒
• 补齐鸿蒙示例工程定位权限与 EntryAbility 后台定位配置

平台兼容性

uni-app x(5.0)

其他

zhuanz-gpslocation

Android、iOS、HarmonyOS 原生系统 GPS 定位插件，支持 uni-app x。提供单次定位、持续定位、后台定位、息屏定位、缓存位置、系统定位开关和权限处理。

引入

import {
  getLastLocations,
  isProviderEnabled,
  onStartLocs,
  openLocSetting,
  requestBackgroundLocPer,
  stop,
  LocData,
  LoctionData
} from '@/uni_modules/zhuanz-gpslocation'

使用

if (!isProviderEnabled()) openLocSetting()
requestBackgroundLocPer()
onStartLocs({
  backgroud: true,
  distance: 10,
  time: 5000,
  getLastFast: false,
  title: 'GPS 定位',
  content: '正在后台获取位置'
} as LocData, (location: LoctionData) => {
  console.log(location)
})

// 不再需要定位时调用
stop(true)

time: 0 或不传为单次定位；time > 0 为持续定位，三端入参单位均为毫秒。Android 在后台持续定位时启动前台服务；iOS 后台定位必须授予“始终”定位权限；鸿蒙会分步申请前台和后台定位权限，并在后台持续定位时启动系统定位长时任务。

参数与返回值

回调字段：msg、type（0 缓存、1 最新、2 失败）、lat、lng、speed、altitude、bearing、accuracy、altitudeAcuracy。

权限与平台配置

Android 已声明精确/粗略定位、后台定位、前台服务和前台服务定位权限。iOS 已声明前台/始终定位说明及 UIBackgroundModes=location。鸿蒙插件已声明定位和后台运行权限，但主应用仍需在 harmony-configs/entry/src/main/module.json5 的 EntryAbility 中添加：

Android 11 及以上不允许在普通运行时权限弹窗中直接选择“始终允许”。调用 requestBackgroundLocPer() 会先申请前台定位，再打开当前应用的权限设置页；用户需要进入“位置信息”并选择“始终允许”。Android 原生权限和前台服务配置只有在自定义基座或正式安装包中生效，修改权限后必须重新制作并安装自定义基座。

{
  "backgroundModes": ["location"]
}

实际后台能力受用户授权、系统定位开关、厂商电量策略以及系统强制结束应用行为影响。

示例工程已附带 harmony-configs/entry/src/main/module.json5，使用鸿蒙后台定位时请将其中的 EntryAbility 配置合并到主应用鸿蒙工程；修改后需要重新编译并安装运行包。