更新记录

1.0.1（2026-09-18）

• 新增 iOS 原生步行、骑行路线预览与直接 GPS 导航。
• 修复 iOS 原生导航页面展示与清理的主线程生命周期问题。
• 补齐高德 iOS 组合 GPS 导航要求的 Location updates 后台模式。
• 在 Bundle ID 匹配的 Xcode 模拟器基座完成步行、骑行在线算路、路线页、直接 GPS 导航和退出验证。
• 补充 HBuilderX 5.24 Pod 资源重复导致调试 IPA 增大的说明。
• 提供完整示例工程、接入说明和异常诊断。
• 修复 Android 路线方案页面下方候选路线持续加载的问题。

平台兼容性

uni-app(5.08)

uni-app x(5.15)

wyc-特别版（600 元渠道版）：本说明仅随独立渠道交付包提供。插件 ID 是 wyc-amapx，购买与交付请认准 wyc-特别版 名称。

AMapX 高德地图三端全能引擎｜定位导航·围栏轨迹

wyc-amapx 是一个面向 uni-app / uni-app x App 项目的 UTS API 插件，统一封装 Android、iOS、HarmonyOS 的高德原生定位、导航、圆形地理围栏和本地驾车轨迹纠偏能力。

插件适合需要在自己的 App 内完成以下功能的项目：

• 获取一次当前位置与地址信息
• 在页面前台持续接收位置变化
• 打开路线预览页或直接进入原生导航页
• 切换驾车、步行、骑行、货车、摩托车导航方式
• 按需传入车牌号、避限行和货车/摩托车参数
• 监听进入、离开和停留圆形围栏的事件
• 获取原始驾车轨迹与高德本地纠偏结果
• 在调用功能前检查 Key、隐私状态和 SDK 是否就绪

本插件只支持 App 原生端，不支持 H5 和各类小程序。使用者需要自行申请对应平台的高德 Key，并使用 HBuilderX 制作自定义调试基座或正式安装包；标准基座不包含本插件的原生 SDK。

界面预览

Android 联调台、路线方案、直接导航、导航方式、车辆参数和运行诊断的实际截图请在插件市场详情页预览。发布包不重复携带市场展示图片，以减小使用者下载体积。

功能兼容性

Vue、项目类型和系统版本

本插件是 API 插件，不包含依赖 Vue 渲染的原生 UI 组件。Vue 版本主要影响宿主项目的页面编译，不改变插件公开 API。

系统与工具链要求：

• Android：最低 API 21（Android 5.0），提供 armeabi-v7a 与 arm64-v8a
• iOS：最低 iOS 14.0，提供 arm64 真机与 x86_64 模拟器架构
• HarmonyOS：最低 API 14
• 推荐 HBuilderX 5.24 或更高兼容版本；当前发布包以 HBuilderX 5.24 为验证环境，不承诺更低版本可以正常编译
• Vue 2 项目使用 UTS 插件至少需要满足 DCloud 对 Vue 2 UTS 编译器的版本要求；为避免原生 SDK 和编译器差异，仍建议直接使用上述推荐版本

DCloud 对 UTS 插件的说明见 UTS 插件开发文档。

使用前必须准备

1. 在高德开放平台分别创建 Android、iOS、HarmonyOS 应用并取得对应 Key。
2. Android Key 必须匹配最终应用包名和签名 SHA1；iOS Key 必须匹配最终 Bundle Identifier；HarmonyOS Key 必须匹配最终应用身份信息。
3. 在宿主 App 的隐私政策中披露高德定位、导航等用途，并在用户同意后再通知插件。
4. 使用真机测试时开启定位服务和网络，并允许 App 使用精确位置。
5. 首次加入插件，或修改原生依赖、应用包名、签名、Bundle Identifier 后，重新制作自定义基座或正式包；只修改统一 JSON 中的 Key 时，重新编译并启动 App 即可。
6. iOS 使用应用内 GPS 导航时，宿主还需在 manifest.json > app-plus > distribute > ios 配置 "UIBackgroundModes": "location"；仅在插件目录的 Info.plist 声明不足以保证 HBuilderX 重装或云打包后的宿主 App 保留该能力。

不要把正式 Key 写入公开的示例代码、截图、日志或公开仓库。示例中的三个 YOUR_*_KEY 占位符都必须由使用者在自己的本地宿主工程中替换。

安装插件

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

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

如果 HBuilderX 提示三方依赖尚未安装，可右键 uni_modules/wyc-amapx，选择“安装插件三方依赖”。

配置高德 Key：三端只维护一个文件

从 0.3.0 起，推荐在宿主项目根目录只创建一个 wyc-amapx.config.json。可以从插件目录的 wyc-amapx.config.example.json 复制：

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

把本次需要的平台 Key 替换为自己的值；暂不构建的平台可以保留占位符。然后在应用启动或首次使用插件时导入一次：

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

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

三端字段含义：

配置注意事项：

• 文件必须位于宿主项目根目录，不要放到 uni_modules/wyc-amapx 内。
• JSON 不能包含注释、尾逗号或重复字段。
• setAmapKey() 应在宿主已经展示隐私政策并取得用户同意后调用，且要早于定位、导航、围栏和轨迹接口。
• Key 只在当前 App 进程内交给原生 SDK，插件不主动持久化，也不会打印 Key。
• Android 插件清单自带无效占位资源，因此不再要求额外创建 nativeResources/android/manifestPlaceholders.json。
• iOS 仍兼容旧项目主 Bundle 中的 FlAmapXIOSKey 回退，但新项目无需再维护根目录 Info.plist Key 字段。
• 不要把 Key 配到 manifest.json > sdkConfigs.maps.amap。该字段属于 DCloud 内置 Maps 模块；Android 同时启用内置 Maps 还可能与本插件携带的高德组合 SDK 产生重复类冲突。
• 正式 Key 通常不适合提交到公开 Git 仓库。私有项目可直接使用该文件；公共模板应只提交占位符，并在本地部署流程中注入真实值。

wyc-amapx.config.json 属于 JavaScript/UTS 运行时配置。仅修改 Key 本身无需为了“写入 AndroidManifest”重新制作基座；但首次加入插件，以及原生依赖、Android 清单、iOS Pod、HarmonyOS 模块或 UTS 原生桥发生变化时，仍必须重建自定义基座。

为什么不统一写进 manifest.json

manifest.json 没有为第三方 UTS 插件提供一个可由 Android、iOS、HarmonyOS 同时读取的通用自定义 Key 字段。sdkConfigs.maps.amap 专用于 DCloud 内置 Maps，不是本插件的配置入口。因此本插件用宿主根目录 JSON 统一管理，再由 setAmapKey() 交给三端原生 SDK。

隐私合规初始化

宿主必须先向用户展示自己的隐私说明。只有用户已看到并同意后，才调用：

import * as FlAmapX from "@/uni_modules/wyc-amapx"

await FlAmapX.updatePrivacyShow(true, true)
await FlAmapX.updatePrivacyAgree(true)

参数含义：

• updatePrivacyShow(isContains, isShow)：宿主隐私政策是否包含高德相关说明、是否已经展示给用户
• updatePrivacyAgree(isAgree)：用户是否已同意

如果用户撤回同意，应立即同步状态：

await FlAmapX.updatePrivacyAgree(false)

撤回隐私同意会终止插件当前活动的原生定位相关工作。不要在没有实际展示隐私政策时直接把参数写死为 true。

最短可用示例：单次定位

先从统一配置文件初始化，再调用定位：

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

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

  await FlAmapX.ensureFeatureReady("singleLocation")

  const result = await FlAmapX.getSingleLocation({
    needAddress: true,
    onceLocationLatest: true,
    timeout: 15000
  })

  console.log("纬度", result.latitude)
  console.log("经度", result.longitude)
  console.log("地址", result.address)
}

建议用 try/catch 向用户展示权限拒绝、Key 不匹配、网络异常和定位超时，而不是静默失败：

try {
  const location = await FlAmapX.getSingleLocation({
    needAddress: true,
    timeout: 15000
  })
  console.log(location)
} catch (error) {
  uni.showToast({
    title: String(error),
    icon: "none"
  })
}

定位结果主要字段：

坐标请统一使用高德坐标体系。外部来源的 WGS84 或其他坐标如果没有正确转换，可能造成定位点、终点和围栏位置偏移。

前台持续定位

先绑定回调，再启动持续定位：

FlAmapX.onLocationChange((location) => {
  console.log("位置更新", location.latitude, location.longitude)
})

await FlAmapX.ensureFeatureReady("continuousLocation")
await FlAmapX.startLocation({
  interval: 2000,
  needAddress: true,
  onceLocationLatest: false
})

停止时同时释放原生任务和页面回调：

await FlAmapX.stopLocation()
FlAmapX.offLocationChange()

建议在页面卸载时统一清理：

export default {
  onUnload() {
    FlAmapX.stopLocation().catch(() => {})
    FlAmapX.stopGeoFence(null).catch(() => {})
    FlAmapX.stopTrack(null).catch(() => {})

    FlAmapX.offLocationChange()
    FlAmapX.offNaviRouteResult()
    FlAmapX.offGeoFenceChange()
    FlAmapX.offTrackChange()
  }
}

导航

路线预览与直接导航

pageType 决定打开方式：

• route：先打开插件路线预览，确认后进入高德路线方案页；用户可在页面下方选择路线并开始导航，也是默认值
• navi：算路成功后直接进入原生导航页

Android 的 route 流程会完整显示高德路线方案页下方的候选方案、预计时间、距离和“开始导航”按钮；navi 才会跳过确认流程直接进入行驶导航。

路线预览：

await FlAmapX.startNavi({
  latitude: 30.574956,
  longitude: 104.040380,
  name: "目的地",
  startLatitude: currentLocation.latitude,
  startLongitude: currentLocation.longitude,
  mode: "drive",
  pageType: "route"
})

直接导航：

await FlAmapX.startNavi({
  latitude: 30.574956,
  longitude: 104.040380,
  name: "目的地",
  startLatitude: currentLocation.latitude,
  startLongitude: currentLocation.longitude,
  mode: "drive",
  pageType: "navi"
})

可选导航方式：

• drive：驾车，默认值
• walk：步行；Android、iOS、HarmonyOS 支持
• ride：骑行；Android、iOS、HarmonyOS 支持
• truck：货车
• motorcycle：摩托车

步行、骑行路线建议同时传入起点；startLatitude 与 startLongitude 必须成对出现。iOS 使用高德原生步行/骑行 Manager 与 View，驾车、货车和摩托车继续使用高德组合导航组件。

车牌号：用户填写才传

车牌号不是必填项。推荐在页面提供一个可选输入框，去掉前后空格后，只有非空时才加入导航参数：

const plate = userPlateNumber.trim()
const vehicleOptions = {}

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

await FlAmapX.startNavi({
  latitude: destination.latitude,
  longitude: destination.longitude,
  name: "目的地",
  startLatitude: currentLocation.latitude,
  startLongitude: currentLocation.longitude,
  mode: "drive",
  pageType: "navi",
  avoidRestriction: true,
  ...vehicleOptions
})

空字符串、纯空格、null 不会写入原生车辆信息。宿主也不应在日志、埋点或错误上报中输出完整车牌号。

途经点

最多传入 3 个途经点：

await FlAmapX.startNavi({
  latitude: destination.latitude,
  longitude: destination.longitude,
  startLatitude: currentLocation.latitude,
  startLongitude: currentLocation.longitude,
  mode: "drive",
  pageType: "route",
  waypoints: [
    { latitude: 30.583823, longitude: 104.049307, name: "途经点 A" },
    { latitude: 30.578060, longitude: 104.046388, name: "途经点 B" }
  ]
})

新项目优先使用 waypoints。waypointsJson 仅用于兼容需要传字符串的旧调用方式，不要同时维护两份不同数据。

车辆参数

startNavi 还支持：

车辆参数应来自用户真实选择，不要为了通过校验填写虚假默认值。不同地区与高德控制台权限可能影响路线结果。

监听导航结果

导航事件以 JSON 字符串返回。建议只提取业务所需字段，不要把完整路线点或车辆信息上传到日志系统：

FlAmapX.onNaviRouteResult((payload) => {
  try {
    const result = JSON.parse(payload)
    console.log("导航状态", result.status)
    console.log("页面类型", result.pageType)
    console.log("错误信息", result.errorMessage)
  } catch (error) {
    console.error("导航结果无法解析", error)
  }
})

页面销毁时调用 FlAmapX.offNaviRouteResult()。

圆形地理围栏

本插件同时只维护一个活动圆形围栏。启动新围栏时会清理旧围栏：

FlAmapX.onGeoFenceChange((event) => {
  console.log("围栏状态", event.status)
})

await FlAmapX.ensureFeatureReady("geoFence")
await FlAmapX.startGeoFence({
  latitude: currentLocation.latitude,
  longitude: currentLocation.longitude,
  radius: 500,
  customId: "store-001"
})

常见事件状态：

• created：围栏创建成功
• in：进入围栏
• out：离开围栏
• stayed：在围栏内停留
• createFailed、locationFailed、eventError：创建、定位或事件处理异常
• stopped：围栏已停止

停止指定围栏：

await FlAmapX.stopGeoFence("store-001")
FlAmapX.offGeoFenceChange()

围栏依赖精确位置。用户拒绝精确位置、设备定位关闭或 App 退到后台后，不应把“没有回调”当作确定的进出结果。

本地驾车轨迹纠偏

轨迹功能使用各平台高德 SDK 的本地驾车轨迹纠偏能力，不会自动上传到高德猎鹰或其他云端轨迹服务。

FlAmapX.onTrackChange((event) => {
  console.log("轨迹状态", event.status)
  console.log("原始点数", event.rawCount)
  console.log("纠偏点数", event.correctedCount)
  console.log("最后纠偏点", event.lastCorrectedPoint)
})

await FlAmapX.ensureFeatureReady("track")
await FlAmapX.startTrack({
  serviceId: "order-service",
  terminalId: "driver-001",
  trackId: "order-20260905-001"
})

停止轨迹：

await FlAmapX.stopTrack("order-20260905-001")
FlAmapX.offTrackChange()

serviceId、terminalId、trackId 是宿主用于关联本次任务的标识，不代表插件已经创建高德猎鹰服务、终端或云端轨迹。轨迹纠偏需要真实移动与足够数量的定位点；静止测试或模拟器测试出现 correctedCount: 0 不等于插件故障。

调用前检查

查看整体状态

const status = await FlAmapX.getSdkStatus()

console.log("平台", status.platform)
console.log("SDK 已集成", status.sdkIntegrated)
console.log("隐私已展示", status.privacyShown)
console.log("隐私已同意", status.privacyAgreed)
console.log("Key 已配置", status.keyConfigured)
console.log("持续定位中", status.locating)

检查某个功能

const check = await FlAmapX.checkFeatureSupport("navi")

if (!check.ready) {
  console.log(check.messages.join("；"))
}

确保功能可调用

await FlAmapX.ensureFeatureReady("navi")

可检查的功能名：

• singleLocation
• continuousLocation
• navi
• geoFence
• track

checkFeatureSupport 和 ensureFeatureReady 只检查插件集成、隐私状态和 Key 是否具备。它们不能替代系统权限、网络、高德 Key 绑定关系和真机测试。

API 一览

完整参数类型可由 HBuilderX 从插件的 utssdk/interface.uts 自动获得提示。

示例工程建议操作顺序

导入带示例工程的版本后，建议按页面顺序操作：

1. 配置目标平台 Key，并重新制作自定义基座。
2. 启动 App，完成宿主隐私政策展示和同意。
3. 点击“一键验证定位”，确认隐私、Key、SDK、真实定位、导航预检均通过。
4. 检查单次定位坐标和地址是否符合设备当前位置。
5. 开始持续定位，移动设备后确认位置连续变化，再停止持续定位。
6. 选择驾车/步行/骑行/货车/摩托车。
7. 车牌号可以不填；如填写，确认只影响本次导航且日志未展示完整车牌。
8. 先测试“打开路线预览”，再测试“直接打开导航”。
9. 以当前位置创建围栏，实际跨越边界验证 in、out 和 stayed。
10. 在室外驾车或以安全方式移动，累计多个真实定位点后观察原始点和纠偏点。
11. 停止所有活动，再退出页面，确认没有继续定位或重复回调。

权限、隐私与数据安全

• iOS 应用内 GPS 导航需要宿主包含 Background Modes > Location updates；插件仅在高德导航进行中使用该能力，普通持续定位、围栏和轨迹接口仍显式关闭后台更新。
• 宿主负责在隐私政策中说明高德 SDK、定位目的、使用场景、数据类型和第三方共享情况。
• 宿主负责处理“拒绝权限”“不再询问”“仅大致位置”“系统定位关闭”等用户路径，并提供设置页引导。
• Key、车牌号、完整轨迹、家庭/公司地址和精确坐标都不应直接写入公开日志。
• 如果曾经把正式 Key 提交到公开仓库，仅删除当前文件还不够，应到高德控制台轮换 Key。
• 正式发布前请使用生产包名、生产签名、生产 Bundle Identifier 和生产证书重新验证。

常见问题

1. 提示 Gradle 版本过高

如果 HBuilderX 提示只支持 Gradle 7.5～8.x，而本机配置成 Gradle 9.x，请在 HBuilderX 设置中改用兼容的 Gradle 8.x，再重新编译。不要因为项目其他工具安装了 Gradle 9.x 就让 HBuilderX UTS 编译器共用它。

2. Android 编译提示找不到 com.amap

依次检查：

1. 是否使用了支持 UTS 原生插件的 HBuilderX。
2. 是否已右键插件安装三方依赖。
3. 是否启用了 DCloud App Maps；如启用，请关闭后重建基座。
4. 是否仍在运行修改前的旧自定义基座。
5. 清理本次运行产物后，重新制作并安装自定义基座。

3. Android 提示 Android AMap key is missing

确认根目录 wyc-amapx.config.json 的 androidKey 不是空值或 YOUR_ANDROID_KEY，并确认已在隐私同意后执行 setAmapKey(amapConfig)。Key 还必须匹配最终包名和签名 SHA1。

4. iOS 提示 iOS AMap key is missing

确认根目录 wyc-amapx.config.json 的 iosKey 不是空值或 YOUR_IOS_KEY，并确认已调用 setAmapKey(amapConfig)。Key 必须匹配最终 Bundle Identifier。旧项目仍可使用主 Bundle 的 FlAmapXIOSKey 回退。

5. keyConfigured 为 true，但定位或导航仍失败

keyConfigured 只表示插件读取到了非空 Key，不表示高德服务器已经验证通过。继续检查 Key 的平台类型、包名/Bundle Identifier、签名 SHA1、证书、服务权限、网络和系统时间。

6. 点击导航没有反应

建议依次确认：

1. 隐私展示和同意状态已提交。
2. checkFeatureSupport("navi") 的 ready 为 true。
3. 已授予精确定位权限。
4. 起点和终点是有效高德坐标，且不能只传起点纬度或只传起点经度。
5. 当前平台的高德 Key、账号权限和 SDK 能力支持所选导航模式。
6. 监听 onNaviRouteResult，查看算路失败、页面打开失败或 Key 鉴权错误。
7. 当前安装的确实是最新自定义基座。

7. 单次定位报结果解析失败

先确认已经更新到插件最新版本并重新制作基座。UTS 源码改变后只同步页面不够；旧基座仍会运行旧的 Kotlin/Swift/ArkTS 桥接代码。

8. 轨迹原始点在增长，但纠偏点为 0

请在室外、网络正常、精确定位开启的真机上实际移动，并累计足够数量的连续点。静止、模拟器、点数过少或纠偏服务返回错误时，可能只有原始点。

9. 修改 Key 后仍显示旧配置

先停止并重新运行 App，确保新的 wyc-amapx.config.json 被重新编译并在本进程调用 setAmapKey()。如果同时改了包名、签名、Bundle Identifier、原生依赖或插件原生源码，还要重新制作基座并卸载旧 App。

10. 页面退出后仍收到回调

在 onUnload/对应页面销毁生命周期中调用停止 API，并解绑 offLocationChange、offNaviRouteResult、offGeoFenceChange、offTrackChange。

反馈问题时请提供

为提高排查效率，请提供以下脱敏信息：

• 插件版本、HBuilderX 版本、uni-app 或 uni-app x、Vue 2 或 Vue 3
• Android/iOS/HarmonyOS 系统版本与设备型号
• 自定义基座重新制作时间，以及是否卸载过旧 App
• Key 是否已配置、是否与包名/签名/Bundle Identifier 匹配；不要发送 Key 原文
• 调用的功能、参数类型和完整错误文本；车牌、坐标、轨迹、设备标识请脱敏
• getSdkStatus() 与 checkFeatureSupport() 的结果；不要附带业务敏感数据

原生依赖说明

• Android：高德组合导航/地图/定位/搜索 SDK 11.1.200
• iOS：AMapLocation-NO-IDFA 2.12.2、AMapNavi-NO-IDFA 11.2.100
• HarmonyOS：高德 common/location/map3d/navi 11.2.0

Android 当前组合依赖同时保留 32 位和 64 位 ABI。不要自行叠加另一个高德地图、定位、导航或搜索 SDK 版本；如果宿主已有高德依赖，请先统一版本并完整验证，避免重复类或运行时冲突。

许可与第三方服务

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