更新记录

1.0.0（2026-09-05）

• 首次发布 Android、iOS、HarmonyOS 三端统一高德地图 UTS API 插件。
• 支持单次定位、逆地理地址和前台持续定位。
• 支持路线预览与直接进入原生导航。
• 支持驾车、步行、骑行、货车和摩托车等导航方式，具体能力以目标平台为准。
• 支持最多 3 个途经点、可选车牌号、避限行及车辆参数。
• 支持圆形地理围栏和驾车轨迹纠偏。
• 提供三端统一 Key 配置、隐私合规初始化和功能预检。
• 提供完整示例工程、接入说明和异常诊断。
• 修复 Android 路线方案页面下方候选路线持续加载的问题。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

fl-amapx 高德地图三端定位导航

fl-amapx 是面向 uni-app / uni-app x App 项目的 UTS API 插件，以一套业务 API 接入 Android、iOS、HarmonyOS 高德原生定位、路线预览、直接导航、圆形地理围栏和驾车轨迹纠偏能力。

主要能力

• 单次定位与逆地理地址
• App 前台持续定位
• 路线预览和候选路线选择
• 算路成功后直接进入原生导航
• 驾车、步行、骑行、货车和摩托车模式，具体以目标平台能力为准
• 最多 3 个途经点
• 可选车牌号、避限行及货车/摩托车参数
• 圆形地理围栏进入、离开和停留事件
• 驾车轨迹采集和纠偏
• Key、隐私状态、SDK 与功能就绪预检

本插件只支持 App 原生端，不支持 Web/H5、小程序、鸿蒙元服务或快应用。当前只提供前台定位，不申请后台定位权限。

兼容范围

• HBuilderX / CLI：最低 5.24.0
• Android：最低 Android 5.0 / API 21，支持 armeabi-v7a、arm64-v8a
• iOS：最低 iOS 14.0，支持 arm64 真机与 x86_64 模拟器
• HarmonyOS：最低 API 14
• App nvue：不在本插件当前承诺范围内

iOS 当前原生组合导航支持驾车、货车和摩托车；步行、骑行请勿在 iOS 端调用。Android 与 HarmonyOS 支持驾车、步行、骑行、货车和摩托车。

使用前准备

1. 在高德开放平台分别创建 Android、iOS、HarmonyOS 应用并取得对应 Key。
2. Android Key 需要匹配最终包名和签名 SHA1；iOS Key 需要匹配 Bundle Identifier；HarmonyOS Key 需要匹配最终应用身份和签名。
3. 在宿主隐私政策中披露高德 SDK、处理数据、使用目的和高德隐私政策链接。
4. 首次加入插件后制作自定义基座或正式安装包；标准基座不包含本插件原生 SDK。
5. 真机验证时开启网络、系统定位和精确位置权限。

不要把正式 Key 发布到公开仓库、截图或日志。

安装

在插件市场选择“使用 HBuilderX 导入插件”，导入后目录为：

你的项目/
├── fl-amapx.config.json
├── manifest.json
└── uni_modules/
    └── fl-amapx/

如 HBuilderX 提示需要安装三方依赖，请右键 uni_modules/fl-amapx，选择“安装插件三方依赖”。

三端 Key 统一配置

从插件目录复制 fl-amapx.config.example.json 到宿主项目根目录，并改名为 fl-amapx.config.json：

{
  "androidKey": "YOUR_ANDROID_KEY",
  "iosKey": "YOUR_IOS_KEY",
  "harmonyKey": "YOUR_HARMONY_KEY"
}

暂不构建的平台可以保留占位符。真实 Key 只放在使用者自己的宿主工程，不要修改进 uni_modules/fl-amapx。

不要把插件 Key 配置到 manifest.json > sdkConfigs.maps.amap。该位置属于 DCloud 内置 Maps 模块，并非本插件配置入口；Android 同时启用内置 Maps 还可能与插件携带的高德组合 SDK 发生重复类冲突。

隐私同意后初始化

宿主应先展示自己的隐私政策并获得用户明确同意，然后执行：

import * as FlAmapX from "@/uni_modules/fl-amapx"
import amapConfig from "@/fl-amapx.config.json"

async function initAmapAfterConsent() {
  await FlAmapX.updatePrivacyShow(true, true)
  await FlAmapX.updatePrivacyAgree(true)
  await FlAmapX.setAmapKey(amapConfig)
}

Key 只在当前 App 进程中交给原生 SDK，插件不主动持久化或打印 Key。用户撤回隐私同意时，应同步调用：

await FlAmapX.updatePrivacyAgree(false)

撤回后插件会停止正在运行的定位、围栏和轨迹任务。

调用前检查

const status = await FlAmapX.getSdkStatus()
const support = await FlAmapX.checkFeatureSupport("location")
await FlAmapX.ensureFeatureReady("location")

可检查的功能包括 location、navigation、geofence、trackCorrection。

单次定位

const location = await FlAmapX.singleLocation({
  needAddress: true,
  timeoutMs: 12000
})

console.log(location.latitude, location.longitude, location.address)

定位结果可能包含经纬度、精度、时间、速度、方向和地址信息；字段是否有值取决于平台及定位环境。

前台持续定位

const onLocation = (result) => {
  console.log(result.latitude, result.longitude)
}

FlAmapX.onLocationChange(onLocation)

await FlAmapX.startLocation({
  intervalMs: 2000,
  needAddress: true
})

// 页面销毁时
await FlAmapX.stopLocation()
FlAmapX.offLocationChange(onLocation)

持续定位只承诺 App 页面处于前台期间工作。

路线预览

await FlAmapX.startNavi({
  pageType: "route",
  mode: "drive",
  start: { latitude: 23.1291, longitude: 113.2644 },
  end: { latitude: 23.1065, longitude: 113.3245 },
  waypoints: [
    { latitude: 23.1200, longitude: 113.2800 }
  ]
})

pageType: "route" 会先进入路线方案页，用户可查看候选路线、时间、距离并点击“开始导航”。最多传入 3 个途经点。

直接打开导航

await FlAmapX.startNavi({
  pageType: "navi",
  mode: "drive",
  start: { latitude: 23.1291, longitude: 113.2644 },
  end: { latitude: 23.1065, longitude: 113.3245 }
})

pageType: "navi" 会在算路成功后直接进入原生导航，不停留在路线方案选择页。

可选车牌号

const plate = userInput.trim()

const options = {
  pageType: "route",
  mode: "drive",
  start,
  end
}

if (plate.length > 0) {
  options.plateNumber = plate
}

await FlAmapX.startNavi(options)

未填写、空字符串或只有空格时不要传 plateNumber；插件也会再次清理空白值。插件不会把车牌号输出到日志。

车辆参数

驾车模式可按需传入 avoidRestriction。货车和摩托车可传入平台支持的车辆类型、尺寸、载重等字段。请只传真实、合法且符合接口范围的数据；参数无效时插件会在进入原生 SDK 前返回错误。

圆形地理围栏

const onFence = (event) => console.log(event)
FlAmapX.onGeoFenceChange(onFence)

await FlAmapX.startGeoFence({
  center: { latitude: 23.1291, longitude: 113.2644 },
  radius: 300,
  customId: "office"
})

// 页面销毁时
await FlAmapX.stopGeoFence()
FlAmapX.offGeoFenceChange(onFence)

围栏判断需要精确定位。当前版本不承诺退到后台、锁屏或进程被回收后继续触发。

轨迹纠偏

const onTrack = (event) => console.log(event)
FlAmapX.onTrackChange(onTrack)

await FlAmapX.startTrackCorrection()

// 页面销毁时
await FlAmapX.stopTrackCorrection()
FlAmapX.offTrackChange(onTrack)

请在室外、网络正常、精确定位开启的真机上实际移动。静止、模拟器或采样点过少时可能只有原始点而没有有效纠偏结果。

生命周期清理

页面卸载或业务结束时应停止对应任务并解绑回调：

await FlAmapX.stopLocation()
await FlAmapX.stopGeoFence()
await FlAmapX.stopTrackCorrection()

FlAmapX.offLocationChange(onLocation)
FlAmapX.offNaviRouteResult(onRoute)
FlAmapX.offGeoFenceChange(onFence)
FlAmapX.offTrackChange(onTrack)

停止接口可以重复调用；任务已经停止时不会因为重复停止导致业务失败。

权限与数据说明

Android 使用粗略/精确位置、网络和 Wi-Fi 状态、网络访问、A-GPS 辅助及唤醒相关权限；iOS 使用 App 期间定位并按需申请临时精确位置；HarmonyOS 使用粗略位置、精确位置和网络权限。本插件不申请后台定位权限。

插件自身不建设业务服务器，也不向插件作者上传或保存用户数据。定位、地图、路线和导航能力由高德 SDK 与高德开放平台服务器提供，具体信息处理范围见：高德地图开放平台隐私权政策。

宿主应用必须在首次初始化高德 SDK 前完成隐私披露并取得用户同意。

常见问题

提示 Key 缺失

确认根目录 fl-amapx.config.json 已替换当前平台 Key，并在隐私同意后、调用业务接口前执行 setAmapKey()。

Android 提示 Key 鉴权失败

检查 Key 对应的包名、正式签名 SHA1 和当前安装包是否完全一致。更换包名或签名后需要在高德控制台申请匹配的新 Key。

修改 Key 后仍显示旧值

停止并重新运行项目，确保配置文件被重新编译。首次加入插件、修改原生依赖、包名、签名、Bundle Identifier 或原生桥源码时，需要重新制作自定义基座。

Android 出现重复 AMap 类

不要同时启用 DCloud App Maps 模块或叠加其他版本的高德地图、定位、导航、搜索 SDK。宿主已有高德依赖时，应先统一版本并完成全功能验证。

标准基座无法运行

这是包含原生 SDK 的 UTS 插件，必须使用包含本插件的自定义基座或正式安装包。

反馈问题需要提供什么

请提供插件版本、HBuilderX 版本、项目类型、Vue 版本、系统版本、设备型号、自定义基座制作时间、功能名称、脱敏参数、完整错误文本，以及 getSdkStatus() 和 checkFeatureSupport() 的脱敏结果。不要发送高德 Key、完整车牌、精确业务坐标或用户轨迹。

许可与第三方条款

普通授权版和源码授权版均采用 DCloud 插件市场标准许可协议，并绑定购买时选择的 App ID 与包名。高德 SDK、地图与在线服务仍受高德开放平台自身的服务条款、配额、计费和合规要求约束。