更新记录

1.0.0（2026-11-09）

• 新增 Nexus 高德地图与导航，提供原生地图与 SDK 导航接入、独立离线轨迹记录与回放。
• 平台、配置和验证范围以 README 为准；厂商服务授权与配额独立配置。

平台兼容性

uni-app(5.34)

uni-app x(5.34)

Nexus 高德地图与导航

把每程，走得更从容。作者：Nexus Wang。

基于高德原生 SDK 的嵌入式地图、前台定位、地点搜索、地址解析和多方式导航插件。新增独立的本地离线轨迹记录与回放：无需地图 Key 即可保存显式提交的坐标、暂停续记、回放、导出和删除。地图画面由真实 SDK 提供；封面中的路线只是品牌图形。

价格与服务授权

普通授权目标价为 ¥79.90；2026-11-09 市场实际显示 ¥79.91（提交值与市场相差 1 分）。平台当前限制 24 小时内仅改价一次，待允许后更正；购买前以市场实际金额为准。源码授权 ¥2499.00 正确。

插件授权与高德账号的服务许可、调用配额、地图/定位/导航及货车服务授权分别配置。插件价格不包含高德商业许可，不附送可转售或共享的 Key。购买前确认自己的应用具备所需服务权限；货车服务未开通时不会降级为小客车路线。具体插件使用范围遵循 DCloud 实际授权订单。

平台与构建

Android 固定依赖 com.amap.api:navi-3dmap-location-search:11.3.100_3dmap11.3.100_loc11.3.101_sea9.8.1，包含地图、导航、定位和搜索。iOS 固定 Pods 为 AMapNavi 11.2.100、AMapFoundation 1.9.1、AMapSearch 9.8.1、AMapLocation 2.12.2；选择实际发布且完成本轮编译的版本。AMapNavi 自带地图，不要重复加入 AMap3DMap。不要将其他版本的高德 JAR、AAR、Framework 或 SO 与本插件依赖叠加。

高德 Key、隐私状态及导航管理器包含进程级状态。宿主应统一管理同一进程的高德 SDK；不支持与另一套未协调的高德插件共同争用单例。地图可创建多个受限实例，同时只能有一个本插件导航视图。腾讯版和高德版的离线轨迹存储各自独立，不能互删对方会话。

Key 配置与隐私

1. 在高德开放平台控制台创建自己的应用和 Android 或 iOS Key。
2. Android 精确绑定最终 APK 包名与签名证书 SHA1。HBuilderX 标准基座、自定义基座、正式包可能使用不同签名，不能混用测试签名。iOS 使用实际 Bundle ID。
3. 在宿主提供的本机配置/受控配置中保存客户端 Key，初始化时传给 initializeAMapMap。不要将 Web 服务 SecretKey 或 JS 安全密钥传入本插件，也不要将实际 Key 提交到公开仓库或示例文件。
4. 向使用者说明 SDK 提供方、目的、数据类型及高德隐私权政策，取得明确同意后再设置 privacyAgreed: true。未同意时不要挂载组件或构造 SDK 服务。
5. 仅在用户明确点击定位/GPS 导航时调用权限入口；本插件不申请后台定位。iOS 宿主须提供真实用途的 NSLocationWhenInUseUsageDescription，本插件附有基础说明。

初始化返回成功表示已配置隐私状态与 Key，不代表地图、算路或导航服务鉴权成功。getAMapMapReadiness 的 authorizationVerified 初始为 false，应结合实际 SDK 服务回包和可见图面验收。

官方资料：Android SDK 下载、Android Maven 集成、iOS 导航接入、SDK 合规方案。高德未购买商用许可的测试 Key 仅用于短期、少量测试，不能随收费插件交付给买家运行。

最小接入

组件必须在 SDK 初始化成功后挂载。完整的本机 Key 输入、显式隐私同意、地图事件、路线选择和离线轨迹页面参见 example/uniappx/map-demo.uvue 与 example/uniapp/map-demo.nvue。

<template>
  <nexus-amap v-if="ready" :mapId="mapId" mode="drive"
    :voiceEnabled="false" style="width:100%;height:420px"
    @map-event="onMapEvent" />
</template>
<script setup lang="uts">
import { createAMapMapId, initializeAMapMap, AMapMapInitOptions } from '@/uni_modules/nexus-amap'
const ready = ref(false)
const mapId = ref(createAMapMapId())
function startAfterUserConsent(clientKey: string): void {
  const options: AMapMapInitOptions = {
    key: clientKey,
    privacyAgreed: true,
    success: (_res: UTSJSONObject) => { ready.value = true },
    fail: (err: UTSJSONObject) => { console.log(err['code'] as number | null) }
  }
  initializeAMapMap(options)
}
function onMapEvent(event: UTSJSONObject): void {
  // 使用 type / mapId / data；这里只读取事件类型，不输出 Key。
  console.log(event['type'] as string | null)
}
</script>

mapId 必须由 createAMapMapId() 生成。组件 mode 为 map、drive、truck、walk、ride；挂载后不可改变。切换模式应卸载旧视图，等待销毁，生成新 ID 后重建。组件发出 map-event 或 mount-error，事件为 {type,mapId,data}。App nvue 兼容事件可能位于 event.detail，完整示例已处理两种形式。

公共接口

地图调用使用 AMapMapCallOptions：{mapId, params?, success?, fail?, complete?}；初始化使用 AMapMapInitOptions；离线轨迹使用 AMapTrackOptions：{params?, success?, fail?, complete?}。终态回包统一为 {code,message,data}，code=0 成功，非零失败。回调在主线程，单次终态回调；页面仍须按自己的实例与请求代次忽略过期 UI 更新。

本插件 SDK 工作流以高德支持的国内坐标区域为范围，输入均须为 GCJ02；iOS 设备定位会先由高德坐标区域判断 API 校验，区域外明确失败，不把 WGS84 标为 GCJ02。接口坐标为：{latitude,longitude,coordinateSystem:'GCJ02'}。不能将 WGS84 直接当作 GCJ02。几何输入最多 4096 点；路线返回几何总计最多 4096 点，geometryTruncated 表示响应截断，SDK 仍持有完整路线。

路线与导航

const options: AMapMapCallOptions = {
  mapId: currentMapId,
  params: {
    mode: 'drive',
    origin: { latitude: 22.543096, longitude: 114.057865, coordinateSystem: 'GCJ02' },
    destination: { latitude: 22.552400, longitude: 114.077600, coordinateSystem: 'GCJ02' }
  },
  success: (res: UTSJSONObject) => { /* 从 res.data.routes 选择真实 routeId */ }
}
planAMapRoutes(options)
// 算路成功后，在同一视图显式提交 { routeId, simulation: true, speed: 40 }。

routeId 为 SDK 当前算路结果的不透明字符串，不能自造、转为数组索引或跨视图/跨模式复用。Android 的 SDK 路线选择 ID 与 sdkPathId 不同；iOS 使用真实 routeGroup 的路线键。

navigationStart 返回成功只表示 SDK 接受请求。实际开始、进度、结束分别以真实 SDK 导航事件为准。模拟导航使用固定起终点与 SDK 模拟引擎，不获取手机位置；GPS 导航需显式前台权限。进入后台、视图隐藏/移除、销毁或撤回同意时停止自有定位、导航与语音，回前台不自动恢复导航。

Android 驾车/货车可传最多 16 个 waypoints 和避堵、避高速、避收费策略；步行/骑行不支持途经点。iOS 驾车/货车支持同样的途经点与策略；步行/骑行会拒绝非空途经点及开启的避让策略。

iOS 主动停止返回 navigation_stop_requested（SDK stopNavi 返回与 naviMode 读回），不会冒充 navigation_stopped；后者仅用于实际 SDK didStopNavi 事件，且不保证每次主动停止都收到。

Android 每个导航视图同时只允许一次算路；请求超时、拒绝或状态不确定后必须销毁并重建视图，以隔离 SDK 没有独立请求令牌的迟到回包。iOS 的独立算路使用闭包代次隔离，实际未完成请求有数量上限。停止请求与真实停止事件应分别处理；不应收到请求回调就认定所有 SDK 工作已经停止。

货车模式需顶层 licenseNumber 与完整 truck：{length,width,height,weight,load,axisCount,size}。长宽高为米；weight 为总吨位，load 为核定载重吨位，axisCount 为轴数，size 为车型级别。高德各平台底层字段含义不同，适配层分别映射，不要直接传原生字段。尺寸范围及可选参数以本轮平台说明为准，非法输入返回失败。缺少货车权限会显示 SDK 真实错误。

语音默认在演示中关闭，可在明确开启后请求。speech_text 仅表示 SDK 提供文字，播放开始回调也不能证明物理扬声器已可听；不将它们当成音量或可听验收证据。

离线轨迹：新增工作流

该引擎独立于高德 SDK，不自动定位、联网或上传。存储在应用私有目录，卸载会清除。GCJ02/WGS84 必须明确且同一会话保持一致，不自动转换坐标系。演示中的四个点明确标为合成样例，用来测试暂停间隔、插值和回放，并不冒充采集轨迹；其他已存轨迹的真实性由宿主说明。

本轮验证状态

1.0.0 验证记录（2026-11-09）：

未验收：UTS/uvue 真机页面、iOS 真机及签名包、实时 GPS/连续定位、货车商业服务、步行/骑行真机导航、真实搜索/地址解析及物理可听语音。iOS HBuilder 自动原生构建当前受本机 CocoaPods 环境影响，生成消费者的真实 SDK 类型检查/链接为独立检查，不冒充签名构建。当前真实截图来自独立 Android Native QA 宿主，固定深圳坐标，不代表手机当前位置。

常见问题

• 地图空白：先检查原生 SDK 依赖是否真正进入自定义基座、网络、包名、最终签名 SHA1/Bundle ID 和 Key 平台；标准基座不能验证新原生依赖。
• 地图成功但导航失败：地图与导航/货车服务授权不同，核对 SDK 错误码和账号权限，不把鉴权失败改成成功。
• 切模式后算路失败：使用新 mapId 和相应模式的导航视图，不能在 map-only 视图上发导航命令。
• 没有定位权限：模拟导航不需要定位；用户主动定位或 GPS 导航才走权限入口，拒绝权限时保留真实失败。
• 收到回调但页面已退出：宿主须在卸载时销毁组件，回调按实例/代次校验，禁止旧请求重新挂载地图。