更新记录

1.1.24（2026-09-23）

优化gps 定位

1.1.23（2026-07-29）

修复鸿蒙端配置

1.1.22（2026-05-22）

优化 ios gps定位

平台兼容性

uni-app(4.07)

uni-app x(4.07)

xtf-gpslocation

xtf-gpslocation 是一个 UTS 原生定位插件，支持 App-Android、App-iOS 和 App-Harmony 的 GPS 单次定位、持续定位与后台定位。插件不支持 Web 和各类小程序平台。

仅建议在室外或 GPS 信号良好的环境测试。室内、地下停车场等环境可能无法取得有效 GPS 位置。

支持范围

安装

将插件放到项目的 uni_modules/xtf-gpslocation 目录后，重新运行或云打包 App。定位和后台服务权限由插件声明；后台定位还需要按本文的各平台说明完成系统授权与配置。

使用前的流程

1. 调用 isProviderEnabled() 检查系统定位服务。
2. 未开启时调用 openLocSetting() 引导用户开启定位服务。
3. 需要后台定位时，先调用 requestBackgroundLocPer() 发起后台定位权限申请。
4. 用户完成系统授权后，再使用 backgroud: true 调用定位方法。
5. 业务不再需要位置时，调用 stop(true)。

requestBackgroundLocPer() 不返回授权结果。Android、iOS 或 HarmonyOS 的系统授权界面关闭后，应由用户再次触发开始后台定位；不要在调用该方法后立即启动后台定位。

uni-app 用法

传统 uni-app 页面使用 JavaScript 对象参数和对象回调，不需要导入 LocData、LoctionData 类型。推荐使用 onStartLocs 与 getLastLocations，三端均可用。

<script>
import {
  getLastLocations,
  isProviderEnabled,
  onStartLocs,
  openLocSetting,
  requestBackgroundLocPer,
  stop
} from "@/uni_modules/xtf-gpslocation"

export default {
  methods: {
    applyBackgroundLocationPermission() {
      requestBackgroundLocPer()
    },
    startLocation() {
      if (!isProviderEnabled()) {
        openLocSetting()
        return
      }

      onStartLocs({
        title: "定位服务",
        content: "正在获取位置",
        notifationIconName: "icon",
        time: 5000,
        distance: 10,
        backgroud: true,
        getLastFast: false
      }, (location) => {
        if (location.type === 2) {
          console.error(location.msg)
          return
        }

        console.log(location.lat, location.lng)
      })
    },
    getCachedLocation() {
      getLastLocations((location) => {
        console.log(location)
      })
    },
    stopLocation() {
      stop(true)
    }
  }
}
</script>

uni-app 方法

uni-app x 用法

uni-app x 的页面脚本按 UTS 编译。可从插件主入口导入 LocData、LoctionData 并进行类型标注；不要直接导入插件内部的 utssdk 文件。

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

export default {
  methods: {
    applyBackgroundLocationPermission(): void {
      requestBackgroundLocPer()
    },
    startLocation(): void {
      if (!isProviderEnabled()) {
        openLocSetting()
        return
      }

      const options: LocData = {
        title: "定位服务",
        content: "正在获取位置",
        notifationIconName: "icon",
        time: 5000,
        distance: 10,
        backgroud: true,
        getLastFast: false
      }

      onStartLocs(options, (location: LoctionData): void => {
        if (location.type === 2) {
          console.error(location.msg)
          return
        }

        console.log(location.lat, location.lng)
      })
    },
    getCachedLocation(): void {
      getLastLocations((location: LoctionData): void => {
        console.log(location)
      })
    },
    stopLocation(): void {
      stop(true)
    }
  }
}
</script>

uni-app x 方法

定位参数：LocData

后台持续定位应同时设置 backgroud: true 与大于 0 的 time，例如 time: 5000。time: 0 仅用于单次定位，不能用于验证 HarmonyOS 后台持续定位。

返回数据：LoctionData

类型名称以插件实际导出为准，拼写为 LoctionData。

回调收到 type: 2 时表示定位或权限失败，应先判断 type，再使用经纬度等位置字段。部分平台的底层异步异常仅输出到运行控制台，不保证统一回调失败对象；定位调试时应同时查看控制台日志。

平台配置与限制

Android

• 插件已声明精确定位、粗略定位、前台服务、前台位置服务与后台定位权限。
• 使用后台定位前，调用 requestBackgroundLocPer()。Android 10（API 29）及以上会申请 ACCESS_BACKGROUND_LOCATION。
• backgroud: true 会启动前台定位服务并显示通知。title、content 和 notifationIconName 仅对 Android 生效。
• 调用 stop(true) 可同时停止定位和前台服务通知。

iOS

• 插件的 app-ios/info.plist 已声明使用期间定位、始终定位说明及 UIBackgroundModes 的 location 模式。
• 使用后台定位时，用户仍需在系统设置中授予应用“始终”定位权限。
• 当前 openLocSetting() 在 iOS 端不执行跳转；请在业务页面中提示用户自行进入系统设置处理。

HarmonyOS

插件声明了定位、后台定位和后台运行权限。要使 BackgroundMode.LOCATION 真正生效，还必须在主应用的 EntryAbility 中声明后台模式和后台运行权限；仅配置插件目录中的 module.json5 不够。

在项目根目录新增或修改 harmony-configs/entry/src/main/module.json5：

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

修改 harmony-configs 后，必须重新编译并重新安装鸿蒙运行包。成功启动后台定位时，控制台通常会出现以下顺序的日志：

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

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

停止定位

stop(true)

页面卸载、用户退出定位任务或业务不再需要位置时应调用 stop(true)，避免持续定位产生额外耗电。Android 的参数控制是否移除前台服务通知；iOS 与 HarmonyOS 当前实现会停止定位，但不使用该参数。