更新记录

1.0.0（2026-11-10）

• 合并为单一 UTS 插件，使用官方 Maven 依赖和完整自研 Java 混编源码。
• 提供原生驾车选路、实时/模拟导航、最多 3 个途经点和内置语音开关。
• 补齐定位、启停、会话事件、错误码、权限和超时处理。
• 支持运行时 Key、GCJ-02 / WGS-84 输入和可选业务适配层。
• 兼容 UTS 可选字段的 JSON null 传参，使用 Android JSON 实现验证默认值。
• 提供独立 uni-app 演示界面、环境诊断与接入文档。

平台兼容性

uni-app(4.25)

高德原生导航（多途经点）

为 uni-app Android 项目提供高德原生路线页面与驾车导航。一个 UTS 插件包含完整接入层，支持定位、最多 3 个途经点、模拟导航、实时导航、停止任务与原生事件回调。

配套示例 App 提供可编辑行程、SDK 配置、签名信息和事件日志，方便独立验证接入。

功能

• 高德原生选路页、直接导航页、模拟导航与内置语音开关。
• 起终点及最多 3 个按顺序经过的途经点。
• GCJ-02 坐标；可将 WGS-84 输入统一转换为 GCJ-02。
• 高德单次定位，自动处理运行时精确定位权限请求与超时。
• accepted、page_open、route、start、arrival、finish 等独立事件。
• 会话 ID、并发任务检查和完整退出清理，方便反复打开导航。
• Android Key 可在运行时配置，也可由宿主清单提供。
• 可选 JS 接入层支持项目自己的定位函数、路线接口和兜底页。

环境与依赖

• Android 5.0+，arm64-v8a / armeabi-v7a。
• HBuilderX 4.25+；当前开发验证使用 HBuilderX 5.24。
• 当前提供驾车导航。iOS、鸿蒙、小程序与 Web 不提供原生导航功能。
• 使用自定义调试基座或正式 App；Java 混编、Activity 与 SDK 依赖需要参与原生打包。
• 普通授权加密插件请使用 传统云打包，遵循 DCloud 对付费 UTS 插件的打包要求。

官方依赖已固定在 utssdk/app-android/config.json：

com.amap.api:navi-3dmap-location-search:11.2.100_3dmap11.2.100_loc11.2.100_sea9.8.1

该官方 JAR 自带导航、地图、定位、搜索、JNI 与语音资源，首次云打包需要下载依赖。插件包交付自研源码和依赖配置。

SDK 集成要求：该合包拥有完整高德地图、定位类。宿主不要再同时加入另一套高德 SDK，也不要勾选 DCloud 的 Maps / Geolocation 模块，否则可能产生重复类或版本冲突。定位使用本插件的 getLocation，或由业务传入起点。

快速开始

从插件市场导入 waiqin-amapnavi。UTS 插件通过 uni_modules 和代码导入识别，无需在旧式“App 原生插件配置”列表中添加。

import {
  configure, startNavi, stopNavi,
  getLocation, onNaviEvent, offNaviEvent,
  getState, getEnvironment
} from '@/uni_modules/waiqin-amapnavi'

// 应用展示 SDK 隐私说明，且用户明确同意后调用。
const configured = configure({
  amapKey: '你的高德 Android Key',
  privacyAccepted: true
})

const listener = event => {
  console.log(event.type, event.sessionId, event.code, event.message, event.data)
  // route 表示算路成功，start 表示导航真正开始。
  // error 后仍有 finish，用于结束当前会话和恢复界面。
}
onNaviEvent(listener)

const accepted = startNavi({
  origin: { name: '北京南站', longitude: 116.378517, latitude: 39.865246 },
  destination: { name: '天坛公园', longitude: 116.41667, latitude: 39.88113 },
  via: [{ name: '陶然亭公园', longitude: 116.3846, latitude: 39.8787 }],
  pageType: 'navi',
  emulator: true,
  useInnerVoice: true
})
if (!accepted.success) {
  console.error(accepted.code, accepted.message)
}

// 结束当前导航或定位任务
// stopNavi()

// 页面卸载时取消自己注册的监听
// offNaviEvent(listener)

startNavi / getLocation 同步返回的是请求受理结果。成功打开 Activity、算路成功和导航开始会分别回调。建议用返回的 sessionId 关联后续事件。

配置 Key

Key 优先级：单次请求的 amapKey → configure 配置的 Key → 宿主 AndroidManifest 的 com.amap.api.v2.apikey。

• 使用高德开放平台的 Android 类型 Key，按最终 App 包名和签名 SHA1 配置。
• 调用 getEnvironment() 可读取当前实际包名和签名 SHA1。
• 标准基座、自定义基座、正式 App 的包名/签名可能不同，应以最终安装包为准。
• configure 返回成功表示配置已保存；Key 是否通过高德认证以实际 SDK 回调为准。
• 插件不提供公共 Key。插件授权费用与高德服务授权、配额分别按各平台规则处理。

API

configure(options): NaviResult

活动任务期间修改配置返回 1105，请先停止任务并等待 finish。

startNavi(options): NaviResult

高德原生路线页最多接收 3 个途经点。多路线数量由 SDK 决定；存在途经点、长距离等情形下可能仅有一条路线。

getLocation(options): NaviResult

const accepted = getLocation({ geocode: true, timeoutMs: 15000 })
// 监听同一 sessionId 的 location 事件：
// event.data = { longitude, latitude, accuracy, address, coordinateType: 'gcj02' }
// 随后收到 finish，reason 为 located。

支持 geocode（默认 true）、timeoutMs（默认 15000）和单次 amapKey。定位与导航共享单活动任务约束。

stopNavi(): NaviResult

停止当前定位或导航、关闭插件页面并释放资源。无任务时返回成功且 data.stopped=false。有任务时返回 state=stopping，在 finish 后可开始下一次任务。

onNaviEvent(callback) / offNaviEvent(callback?)

可注册多个回调；取消时传入同一函数引用。不传参数时清除本插件当前 UTS 层的全部监听。取消监听不等同于停止导航。

getState(): NaviResult

state 可能为 idle、starting、locating、planning、route_ready、navigating、arrived、stopping。data 包含 active 与 operation。

getEnvironment(): NaviResult

data 包含 version、sdkVersion、platform、packageName、sha1、keyConfigured、privacyAccepted。不返回 Key 本身。

结果与事件格式

type NaviResult = {
  success: boolean
  code: number
  message: string
  sessionId: string
  state: string
  data: UTSJSONObject | null
}
// NaviEvent 额外包含 type: string 和 timestamp: number。

错误码

可选：适配项目定位、路线接口和兜底页

import * as navi from '@/uni_modules/waiqin-amapnavi'
import { createNaviClient } from '@/uni_modules/waiqin-amapnavi/js_sdk/client.js'

const client = createNaviClient(navi, {
  amapKey: () => appConfig.androidAmapKey,
  privacyAccepted: true, // 仅在用户已同意后设置
  locationProvider: () => myGcj02Location(),
  routePlanner: options => myRouteApi(options),
  fallbackPage: '/pages/my-navigation/index',
  modeLabels: { drive: '导航目的地' },
  onEvent: event => console.log(event.type)
})

await client.start({ destination: { longitude: 116.41667, latitude: 39.88113 } })
// client.planRoute(options) 调用自定义 routePlanner；未配置时打开原生选路页。
// client.stop()
// client.dispose() 释放此客户端的监听，不自动停止全局导航。

自定义 routePlanner 提供业务预规划结果；高德原生页面由 SDK 进行自己的算路。自定义 locationProvider 在未传起点时调用，应返回匹配 coordinateType 的坐标。

兜底页通过查询参数 navi 接收 URL 编码 JSON，仅含起终点、途经点与坐标系。可配置 navigate(url) 接管跳转。原生失败仍保留 success=false；同步降级完成时额外返回 fallbackOpened=true。异步错误也会触发一次兜底，onFallbackError 可接收跳转失败。

示例 App

1. 下载配套示例工程，用 HBuilderX 打开。
2. 将已购买或试用的本插件导入示例的 uni_modules。示例下载包不重复提供受授权保护的原生源码。
3. 为示例生成自己的 AppID，制作 Android 自定义调试基座或正式包。
4. 安装后打开“配置 SDK”，将显示的包名/SHA1 绑定到高德 Android Key。
5. 填入 Key、阅读并同意 SDK 隐私说明，体验定位、途经点、路线与模拟导航。

授权与支持

验证范围与网络排查

本版本使用 HBuilderX 5.24 完成 Java 混编、UTS/Kotlin/D8 和传统云打包，并在 Android 12L 的 MuMu 测试环境中验证定位、3 个途经点、算路、模拟导航、导航文本与音频播放、回调及退出恢复。实体手机的实地 GPS 导航尚未进行验收。

若地图或算路长时间等待，请检查设备到高德服务的 IPv4/IPv6 HTTPS 连通性。测试环境曾出现 IPv6 无法连接而 IPv4 正常的情况；在可用 IPv4 条件下完成上述验证。插件不会更改设备路由、防火墙或其他应用网络配置。

模拟器可能自动批准权限请求，无法替代实体设备上的权限拒绝测试。宿主仍应处理 1103 并引导用户到系统设置授权。

购买与咨询

• 普通授权：49.99 元，核心 UTS / Java 混编源码由 DCloud 平台加密交付。
• 源码授权：599.00 元，获得完整自研实现；第三方 SDK 由官方仓库提供。
• 授权范围、AppID/包名绑定和使用规则，以 DCloud 插件市场购买协议为准。
• 问题反馈请使用插件页面的站内 uni-im 咨询，提供 HBuilderX 版本、Android 版本、错误码和经过脱敏的事件日志。