更新记录

1.0.0（2026-04-10）

初始化

平台兼容性

高德导航 UTS 插件 (amap-navi-plugin)

简介

本插件为 uni-app 提供完整的高德导航SDK集成，使用 UTS（uni-app TypeScript）开发，支持跨平台编译到 Android 和 iOS。

技术特点：

• 使用 UTS 语法，一套代码编译到 Android/iOS 原生
• 支持 GPS 导航和模拟导航
• 支持语音播报
• 类型安全，完善的 TypeScript 类型定义
• 单例模式管理，避免重复初始化

SDK版本：

• Android: 高德导航 SDK 11.1.001（本地集成）
• iOS: AMapNaviKit (CocoaPods 自动集成)

安装步骤

1. 申请高德开发者账号

访问 高德开放平台 注册账号并创建应用，获取 Key。

2. 下载并集成 Android SDK

重要：高德导航 SDK 不在公共 Maven 仓库中，需要手动集成：

1. 从 高德官网 下载导航 SDK
2. 将 SDK 文件放入插件目录：
   • jar包 → utssdk/app-android/libs/ 目录
   • armeabi-v7a 架构 .so 文件 → utssdk/app-android/libs/armeabi-v7a/ 目录
   • arm64-v8a 架构 .so 文件 → utssdk/app-android/libs/arm64-v8a/ 目录

推荐的 SDK 文件：

AMap3DMap_11.1.001_AMapNavi_11.1.001_AMapSearch_9.7.4_AMapLocation_11.1.001_20260402.jar
libAMapSDK_NAVI_v11_1_000.so
libapssdk.so
libc++_shared.so
libneonui_shared.so
libneonuijni_public.so
libnui.so
libopenssl.so

3. 配置 Key

在项目的 manifest.json 中配置高德 Key：

{
  "app-plus": {
    "distribute": {
      "sdkConfigs": {
        "maps": {
          "amap": {
            "appkey_ios": "您的iOS Key",
            "appkey_android": "您的Android Key"
          }
        }
      }
    }
  }
}

4. 制作自定义基座

UTS 原生插件需要在自定义基座中运行：

1. HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座
2. 选择平台后等待打包完成

使用方法

API 调用示例

// 引入插件
import {
  initNavi,
  calculateRoute,
  startGPSNavigation,
  stopNavigation,
  getNaviStatus,
  destroyNavi
} from '@/uni_modules/amap-navi-plugin';

// 初始化导航（建议在页面 onLoad 时调用）
initNavi({ voiceEnable: true }, (result) => {
  if (result.code === 0) {
    console.log('初始化成功');
  } else {
    console.error('初始化失败:', result.message);
  }
});

// 计算路线
calculateRoute({
  startPoint: {
    latitude: 39.90469,
    longitude: 116.40717,
    name: '天安门'
  },
  endPoint: {
    latitude: 39.915,
    longitude: 116.404,
    name: '故宫'
  },
  strategy: 0  // 单路径推荐
}, (routeInfo) => {
  console.log('距离:', routeInfo.distance, '米');
  console.log('时间:', routeInfo.duration, '秒');
  console.log('过路费:', routeInfo.tollCost, '元');
});

// 开始GPS导航
startGPSNavigation({ routeIndex: 0 }, (result) => {
  console.log(result.message);
});

// 开始模拟导航
startEmulatorNavigation({ routeIndex: 0 }, (result) => {
  console.log(result.message);
});

// 停止导航
stopNavigation((result) => {
  console.log(result.message);
});

// 获取当前导航状态
const status = getNaviStatus();
console.log('当前状态:', status); // 'idle' | 'calculating' | 'navigating' | 'emulator' | 'error'

// 页面卸载时销毁导航引擎（建议在 onUnmounted 时调用）
destroyNavi();

API 文档

方法

类型定义

// 坐标点
type NaviPoint = {
  latitude: number;   // 纬度（高德坐标系 gcj02）
  longitude: number;  // 经度（高德坐标系 gcj02）
  name?: string;      // 地点名称（可选）
};

// 路线信息
type RouteInfo = {
  distance: number;   // 距离（米）
  duration: number;   // 时间（秒）
  tollCost: number;   // 过路费（元）
  steps: any[];       // 路线步骤
};

// 导航策略
type NaviStrategy = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
// 0: 单路径（推荐）
// 1: 时间优先
// 2: 距离优先
// 3: 不走高速
// 4: 避免收费
// 5: 不走高速且避免收费
// 6: 避免拥堵
// 7: 时间优先且避免拥堵

// 导航状态
type NaviStatus = 'idle' | 'calculating' | 'navigating' | 'emulator' | 'error';
// idle: 空闲状态
// calculating: 正在计算路线
// navigating: 正在GPS导航
// emulator: 正在模拟导航
// error: 错误状态

平台支持

常见问题

1. 提示"未找到插件"

确保使用自定义基座运行，标准基座不支持 UTS 原生插件。

2. 初始化失败

检查 manifest.json 中的高德 Key 配置是否正确，确保 Android 和 iOS 分别使用对应的 Key。

3. 路线计算失败

• 确保坐标使用 gcj02 坐标系（高德坐标系），不是 wgs84
• 检查起点和终点的坐标是否有效
• 查看错误码和错误信息进行诊断

4. 导航过程中没有语音播报

• 初始化时确保 voiceEnable: true
• 检查设备音量设置
• 检查应用是否有音频播放权限

5. 页面切换后导航失效

导航引擎是单例模式，建议在需要导航的页面：

• onLoad 时初始化
• onUnmounted 时销毁（如果不再需要导航）

注意事项

1. 坐标系要求：高德地图使用 gcj02 坐标系，请确保传入的坐标是 gcj02 格式
2. 自定义基座：UTS 插件必须在自定义基座中运行，标准基座不支持
3. 生命周期管理：建议在页面生命周期中正确管理导航引擎的初始化和销毁
4. 单例模式：导航管理器采用单例模式，避免重复初始化
5. SDK 文件大小：Android SDK 文件约 60MB，上传插件市场时可能受限，建议：
   • 使用「资源包」方式上传 SDK 文件
   • 或在插件说明中指引用户自行下载 SDK
6. 云打包配置：确保 utssdk/app-android/config.json 中 dependencies 为空数组（使用本地SDK而非Maven依赖）

更新日志

v1.0.0 (2026-04-10)

• 初始版本发布
• 支持 Android 平台完整导航功能（SDK 11.1.001）
• iOS 平台基础支持
• 支持路线计算、GPS导航、模拟导航
• 本地SDK集成方式，避免Maven依赖问题

相关链接

• 高德开放平台
• UTS 语法文档
• UTS 原生插件开发
• 高德导航 SDK Android 文档
• 高德导航 SDK iOS 文档