更新记录

1.0.0（2026-09-18） 下载此版本

• 初始版本，支持 Android 平台（Android 6.0 / API 23 及以上）
• 支持 SDK 初始化（内置隐私合规处理 + API Key）与销毁
• 支持路线规划：驾车 / 货车 / 骑行 / 步行 / 摩托车 / 骑行电动车，算路结果自动返回
• 支持途经点（最多 16 个）、算路策略、车辆信息（货车 / 摩托车 / 尾号限行）
• 支持高德导航组件页（路线规划页 / 导航页），语音、播报模式、车头朝向、比例尺等均作为参数传入
• 支持实时导航 / 模拟导航的启动与停止
• 支持 TTS 语音播报：内置语音开关、播报模式、自定义文字播报、停止播报、播报状态查询
• 支持导航实时数据回调：导航信息、定位、车道、路口放大图、电子眼、服务区、交通事件、平行路
• 原生混编层通过反射 + 动态代理实现，兼容高德导航 SDK 版本差异，SDK 依赖固定为 com.amap.api:navi-3dmap:10.0.800_3dmap10.0.800

平台兼容性

uni-app(4.72)

uni-app x(4.72)

zy-amap-navi 高德导航插件

高德导航 UTS 插件（Android），封装高德导航 SDK，提供 路线规划（算路结果自动返回）、 高德导航组件页、实时/模拟导航、TTS 语音播报 与 导航实时数据回调。

导航 UI 由高德官方导航组件页提供（路线规划页 / 导航页），接入成本低、与高德地图 App 效果一致。

功能特性

• ✅ SDK 初始化（内置隐私合规处理 + API Key）与销毁
• ✅ 路线规划：驾车 / 货车 / 骑行 / 步行 / 摩托车 / 骑行电动车，算路结果自动返回
• ✅ 途经点（最多 16 个）、算路策略、车辆信息（货车 / 摩托车 / 尾号限行）
• ✅ 高德导航组件页（路线规划页 / 导航页），语音、播报模式、视角等全部作为参数传入
• ✅ 实时导航 / 模拟导航的启动与停止
• ✅ TTS 语音播报：内置语音开关、播报模式（简洁 / 详细 / 静音）、自定义文字播报、停止播报
• ✅ 导航实时数据回调：导航信息（剩余距离/时间/当前道路/转向图标）、定位、车道、路口放大图、电子眼、服务区、交通事件、平行路

支持平台

依赖与环境

安装

在 HBuilderX 插件市场搜索 zy-amap-navi 安装，或手动将插件目录复制到项目的 uni_modules/ 下。

配置说明

1. 配置高德 Key（二选一）

方式一：AndroidManifest 配置（推荐）

在项目 nativeResources/android/AndroidManifest.xml 的 <application> 节点内添加：

<meta-data
    android:name="com.amap.api.v2.apikey"
    android:value="您申请的高德 Key" />

方式二：调用时传入

initModule({ apiKey: '您申请的高德 Key' })

Key 需与打包证书的 SHA1、包名在高德开放平台绑定，否则算路会返回 Key 非法错误码。

2. 权限配置

插件已在 utssdk/app-android/AndroidManifest.xml 中声明导航所需权限，无需手动配置：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

实时导航需要 定位权限，请在应用启动时通过 uni.authorize 或 Android 运行时权限申请获得用户授权。

3. 隐私合规

高德导航 SDK 自 8.1.0 起强制要求隐私合规，插件已在 initModule 内部按官方要求先调用 updatePrivacyShow / updatePrivacyAgree，再实例化 AMapNavi，无需额外处理。

• privacyAgree 传 false 时插件会直接初始化失败（错误码 9080002）；
• 请确保用户已阅读并同意您的隐私政策后再调用 initModule。

快速开始

import { initModule, calculateRoute, openNaviPage } from '@/uni_modules/zy-amap-navi'

// 1. 初始化（唯一的前置步骤）
initModule({
  privacyAgree: true,
  parallelRoad: true,
  onEvent: (e) => console.log('导航事件', e.event, e.data),
  success: () => {
    // 2. 算路：结果自动返回
    calculateRoute({
      mode: 'drive',
      start: { latitude: 39.993308, longitude: 116.473199 },
      end: { latitude: 39.917834, longitude: 116.397036 },
      strategy: 10,
      success: (result) => {
        console.log(`共 ${result.routeCount} 条路线，主路线 ${result.distance} 米 / ${result.time} 秒`)

        // 3. 打开高德导航组件页，语音与车头朝向等作为参数传入
        openNaviPage({
          mode: 'drive',
          end: { latitude: 39.917834, longitude: 116.397036 },
          useInnerVoice: true,     // 内置语音播报
          broadcastMode: 2,        // 1 简洁 / 2 详细 / 3 静音
          carDirectionMode: 2,     // 1 正北向上 / 2 车头向上
          scaleAutoChange: true    // 比例尺智能缩放
        })
      },
      fail: (err) => console.error('算路失败', err.errCode, err.errMsg)
    })
  }
})

API 说明

1. initModule - 初始化 SDK

initModule(options: NaviInitOptions): void

2. calculateRoute - 路线规划（结果自动返回）

calculateRoute(options: NaviCalculateRouteOptions): void

success 返回的 NaviRouteResult：

3. startNavi - 开始导航（语音作为参数）

startNavi(options?: NaviStartNaviOptions): void

需先算路成功；未算路时高德 SDK 会返回启动失败。实时导航会自动开启卫星定位。

4. stopNavi - 停止导航

stopNavi(options?: NaviSimpleOptions): void

5. openNaviPage - 打开高德导航组件页

openNaviPage(options: NaviPageOptions): void

6. exitNaviPage - 退出导航组件页

exitNaviPage(options?: NaviSimpleOptions): void

7. playTTS - 播放自定义语音

playTTS(options: NaviPlayTtsOptions): void

8. stopSpeak - 停止语音播报

stopSpeak(options?: NaviSimpleOptions): void

9. isTtsPlaying - 是否正在播报（同步）

isTtsPlaying(): boolean

10. destroyModule / isInit

destroyModule(options?: NaviSimpleOptions): void  // 销毁导航 SDK，释放资源
isInit(): boolean                                  // 是否已初始化（同步）

数据模型

NaviPoi（起终点 / 途经点）

NaviCarInfo（车辆信息）

出行方式（mode）

事件列表（onEvent）

错误码

示例

完整示例见项目中的 pages/amap-navi/amap-navi.vue（初始化、算路、导航组件页、语音、事件日志）。

注意事项

1. 必须自定义基座：插件依赖高德导航 SDK，标准基座无法生效，请提交云端打包生成自定义基座后再真机运行。
2. Key 绑定：高德 Key 需与本应用的包名、签名 SHA1 绑定，否则算路返回「用户 key 非法或过期」。
3. 收费接口：货车、摩托车、骑行电动车算路为高德收费接口，需通过高德工单系统申请商务授权，否则算路会失败。
4. 导航组件页途经点上限为 3 个，而普通算路接口最多支持 16 个途经点。
5. 实时导航需要定位权限，且会自动开启卫星定位；模拟导航（naviType: 'emulator'）无需定位。
6. 车辆信息需在算路前设置，否则要等到下一次算路才生效（插件已在算路流程中自动按参数调用 setCarInfo）。
7. 每次初始化会复用 AMapNavi 单例，页面销毁时建议调用 destroyModule 释放资源。

更新日志

见 changelog.md。