更新记录

1.0.13（2026-06-08）

增加鸿蒙端 重整插件文档，补充鸿蒙平台接入注意事项

1.0.12（2026-01-21）

优化iOS

1.0.11（2025-12-04）

you hua

平台兼容性

uni-app(4.05)

uni-app x(4.11)

xtf-baidulocation

百度地图定位插件，支持 uni-app x 和 uni-app。

功能说明

• 获取当前位置
• 监听实时定位结果
• 支持单次定位和连续定位
• 支持地址信息解析
• 支持室内定位、北斗定位、后台定位等配置项

接入前准备

1. 申请百度地图 Key

使用前需要到百度地图开放平台申请 Key，并按平台配置包名、签名等信息。

• Android 使用 key
• iOS 使用 ios_key
• HarmonyOS 使用 harmony_key，鸿蒙端优先使用该 Key

参考文档：

• 百度地图开发文档，参数类型请查询

2. 推荐搭配

• 推荐作者保活插件一起使用

3. 问题反馈

长期维护，有任何问题可在插件群联系作者。

快速使用

uni-app x

import {
  isProviderEnabled,
  openGpsSetting,
  setLocListener,
  initWithOption,
  start,
  LocOption,
  BDAddress,
  stop
} from "@/uni_modules/xtf-baidulocation"

let gpsEnable: boolean = isProviderEnabled()

openGpsSetting()
initWithOption(function(res: boolean) {
  if (res) {
    setLocListener(function(s: BDAddress) {
    })
    start()
  }
}, {
  scanSpan: 0,
  enableBeidou: true,
  indoor: true,
  key: "xxxxxxxxxxxx",
  ios_key: "xxxx",
  harmony_key: "harmony_xxxxxxxx"
} as LocOption)

// stop()

uni-app

import {
  isProviderEnabled,
  openGpsSetting,
  setLocListener,
  initWithOption,
  start,
  LocOption,
  BDAddress,
  stop
} from "@/uni_modules/xtf-baidulocation"

let gpsEnable = isProviderEnabled()

openGpsSetting()
initWithOption(function(res) {
  if (res) {
    setLocListener(function(s) {
    })
    start()
  }
}, {
  scanSpan: 0,
  enableBeidou: true,
  indoor: true,
  key: "xxxxxxxxxxxx",
  ios_key: "xxxx",
  harmony_key: "harmony_xxxxxxxx"
})

// stop()

使用流程建议

推荐按下面顺序接入：

1. 调用 isProviderEnabled() 检查系统定位开关。
2. 如未开启，调用 openGpsSetting() 引导用户打开定位服务。
3. 调用 initWithOption() 完成插件初始化。
4. 在初始化成功后调用 setLocListener() 监听定位结果。
5. 调用 start() 开始定位。
6. 不再需要时调用 stop() 停止定位。

参数说明

export type LocOption = {
  key: string | null,
  ios_key: string | null,
  harmony_key: string | null,
  locationMode: number | null,
  coorType: string | null,
  scanSpan: number | null,
  openGnss: boolean | null,
  enableSimulateGnss: boolean | null,
  needAddress: boolean | null,
  enableBeidou: boolean | null,
  backgroundLocation: boolean | null,
  indoor: boolean | null,
  notificationIconName: string | null,
  notificationChannel: string | null,
  notificationTitle: string | null,
  notificationMsg: string | null,
}

字段含义

• key：百度地图 Android Key
• ios_key：百度地图 iOS Key
• harmony_key：百度地图 HarmonyOS Key，鸿蒙端优先使用
• locationMode：定位模式
  • 0：高精度定位，同时使用网络和 GNSS，优先返回高精度结果
  • 1：低功耗定位，只使用网络定位（Wi-Fi 和基站）
  • 2：仅设备定位，只使用 GNSS，不支持室内定位
  • 3：模糊定位，只使用基站信息
• coorType：返回坐标类型，默认 gcj02
  • gcj02：国测局坐标
  • bd09ll：百度经纬度坐标
  • bd09：百度墨卡托坐标
  • ""：海外地区统一返回 wgs84
• scanSpan：定位间隔，0 表示单次定位；非 0 时需设置为 1000ms 以上才有效
• openGnss：是否使用卫星定位，默认 false；高精度定位和仅设备定位建议设为 true
• enableSimulateGnss：是否允许卫星仿真结果，默认 false 表示过滤仿真结果
• needAddress：是否需要街道地址信息，默认 true
• enableBeidou：是否启用北斗定位
• backgroundLocation：是否启用后台定位
• indoor：是否启用室内定位
• notificationIconName：后台定位通知图标名称，图标需放在 /res/drawable/ 目录
• notificationChannel：后台定位通知栏 Channel 名称
• notificationTitle：后台定位通知标题
• notificationMsg：后台定位通知内容

鸿蒙注意事项

1. 请单独配置鸿蒙 Key

• 鸿蒙平台请优先配置 harmony_key
• 不建议直接复用 Android Key，避免平台配置不一致导致鉴权失败
• 百度地图开放平台中需确认鸿蒙应用对应的包信息、签名信息配置正确

2. 需要声明定位权限

鸿蒙平台对定位权限要求更严格，至少需要在 manifest.json 的 app-harmony 节点声明：

• ohos.permission.APPROXIMATELY_LOCATION
• ohos.permission.LOCATION

注意：申请精确定位时，通常需要同时声明模糊定位权限。

3. 需要补充权限说明

• permissiondescriptions 需要填写清楚用途
• 建议直接说明用于“获取当前位置、实时定位、导航或轨迹记录”
• 如果权限说明过于模糊，容易影响审核或用户授权通过率

4. 使用系统定位模块时要确认模块声明

• 鸿蒙侧如依赖系统定位能力，需要确认 manifest.json 中已正确声明 uni-location 模块
• 较老版本 HBuilderX 中对应节点可能是 uni-getLocation
• 如果项目是历史工程升级上来的，建议重点检查这一项

5. 后台定位不是只开参数就够

• backgroundLocation: true 只表示插件侧启用后台定位逻辑
• 鸿蒙平台通常还需要额外声明后台定位权限，例如 ohos.permission.LOCATION_IN_BACKGROUND
• 长时间后台运行场景还可能涉及 ohos.permission.KEEP_BACKGROUND_RUNNING 以及原生工程配置
• 如果只改 JS 或 UTS 调用参数，没有补足鸿蒙侧权限和能力声明，后台定位通常不会生效

6. 真机调试优先

• 定位授权、系统开关、后台保活等能力建议优先真机验证
• 模拟器或非完整调试环境下，权限弹窗、后台能力、厂商 SDK 行为可能与正式设备不一致
• 使用第三方原生定位 SDK 时，通常需要打自定义基座后再调试

7. 重点排查鉴权失败问题

如果鸿蒙端无法定位，优先检查以下项目：

• harmony_key 是否填写正确
• 百度地图开放平台是否已开通定位服务
• 包名、签名、平台配置是否与当前打包环境一致
• 是否已经授予定位权限
• 是否已打开系统定位开关

基座制作与运行说明

Android / iOS

本插件涉及原生能力，Android 和 iOS 调试时请优先使用自定义基座。

1. 如何制作基座

• 在 HBuilderX 中选择云打包或自定义基座相关功能，制作包含当前插件的基座
• 制作基座前，请确认当前插件代码、manifest.json 配置、应用包名和证书配置都已经准备完成
• 如果插件新增了原生依赖、权限、清单配置或 SDK 参数变更，请重新制作基座

2. 运行时要选择基座

• 真机运行时，不要直接使用普通运行模式
• 请在运行配置里选择对应平台的自定义基座进行启动
• 如果仍然使用默认基座，插件中的原生代码通常不会生效，可能出现无法定位、无回调或直接报错

3. 未修改版本号时，需要先卸载手机里的旧基座

• 如果重新制作基座时没有修改应用版本号，手机里已安装的旧基座可能不会被正确覆盖
• 这时请先手动卸载手机中的旧基座，再重新安装新的基座包
• 否则容易出现“明明重新打了基座，但运行结果还是旧代码”的情况

4. 哪些情况必须重做基座

• 新增或修改了原生插件代码
• 新增或修改了定位相关权限
• 修改了 manifest.json 中的原生配置
• 更新了百度地图 Key、SDK 配置或其他原生依赖

鸿蒙端特别说明

uni-app 仅支持源码版

• 鸿蒙端 uni-app 当前只能使用源码版方式运行和调试
• 不能按 Android / iOS 的常规自定义基座方式理解和处理
• 如果你在鸿蒙端调试插件，请优先按照源码工程方式进行联调

调试判断建议

• Android / iOS：优先检查是否已经制作并选择了正确基座
• HarmonyOS：优先确认当前使用的是源码版工程，而不是按普通基座方式运行

定位结果状态码参考

BDAddress 中 locType 的常见返回值可参考下表，完整含义请以百度地图官方文档为准。

相关文档

• 百度地图开发文档，参数类型请查询
• UTS 语法
• UTS API 插件
• UTS 组件插件
• Hello UTS

打赏

感谢您使用此插件，如果本插件解决了你的问题，欢迎支持作者。