更新记录

1.1.23（2026-07-29）

修复鸿蒙端配置

1.1.22（2026-05-22）

优化 ios gps定位

1.1.21（2026-05-21）

优化ios 停止定位

平台兼容性

uni-app(4.07)

uni-app x(4.07)

xtf-gpslocation

xtf-gpslocation 是一个 uni-app x 定位插件，支持 Android、iOS 和 HarmonyOS 的单次定位、持续定位及后台定位。

安装与引入

将插件放入项目的 uni_modules/xtf-gpslocation 后，在页面中引入：

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

基础用法

const locationEnabled = isProviderEnabled()
if (!locationEnabled) {
  openLocSetting()
}

requestBackgroundLocPer()

onStartLocs({
  backgroud: true,
  distance: 10,
  time: 5000,
  getLastFast: false
} as LocData, (location: LoctionData) => {
  console.log(location)
})

// 停止持续定位
// stop(true)

单次与持续定位

time: 0 会调用单次定位 API，只能在前台完成当前请求。要测试鸿蒙后台持续定位，必须设置大于 0 的 time，例如 5000。

鸿蒙配置

插件自身已经声明定位、后台定位和后台运行权限，但鸿蒙后台保活还必须在主应用的 EntryAbility 中配置后台模式。不能只在 uni_modules/xtf-gpslocation/utssdk/app-harmony/module.json5 中声明权限。

在项目根目录新增或修改：

harmony-configs/entry/src/main/module.json5

当前项目已经包含该文件。EntryAbility 必须包含 backgroundModes，主应用还必须声明 ohos.permission.KEEP_BACKGROUND_RUNNING：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "backgroundModes": [
          "location"
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:EntryAbility_label",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}

本插件启动的是 BackgroundMode.LOCATION，因此主应用配置使用 location。修改 harmony-configs 后必须重新编译并重新安装鸿蒙运行包。

鸿蒙后台定位的正常日志顺序如下：

后台定位权限已授予
Operation startBackgroundRunning succeeded
locationCallback: data: ...

12100011 与 All permissions in the permission list have been granted 表示权限已经授予，不是失败。

iOS 配置

iOS 需要在插件的 app-ios/info.plist 中声明前台定位、后台定位说明和 UIBackgroundModes 的 location 模式。后台持续定位前，用户还需要在系统设置中授予应用“始终”定位权限。

参数：LocData

返回值：LoctionData

停止定位

stop(true)

停止持续定位后应在不再需要定位时调用该方法，避免持续耗电。