更新记录

1.1.0（2026-10-14）

• Android / iOS 共用 startNavigation 接口与 NVUE 导航组件，支持普通驾车、步行和司机接送页面接入。
• 驾车支持最多 16 个有序途经点；提供进度、到达、途经点和重算事件，便于业务页面显示行程状态。步行仅支持起终点，货车暂未开放。
• 新增经典 standard、简洁 custom 两种顶部提示风格，使用高德地图、语音、转向素材与导航数据。两种风格均隐藏高德默认底栏，退出、剩余行程、设置和订单操作统一由业务页面绘制。
• 新增三挡底部面板，支持自定义内容与高度、拖动、长内容滚动、按内容收紧和展开动画；导航时自动为关键转向、车道、路口及地图预留空间。
• 新增静音、全览和跟随控制，以及设置结果和实际视角事件；面板展开不强制地图回到跟随模式。
• 完善启动失败提示、取消请求、停止导航和离页清理；导航中重算失败单独提示，不直接结束当前导航。
• 随插件提供驾车 / 步行、司机接送、路线预览页面及配置文件。Key 和隐私同意由业务项目配置，页面内容可直接修改。
• 路线预览支持横滑方案卡、选中路线摘要及自动全览，为起终点、途经点和上下面板保留显示空间；点击“全览”恢复视野，紧凑屏自动简化提示。司机行程预览保持只读并返回订单，骑行仅预览。
• Android 司机接送准备阶段显示底图，开始导航和停止后切换地图；预览路线加粗，补充主要道路气泡与有效收费/红绿灯摘要，修复 NVUE 多路线卡片超宽时的横向滚动布局。
• 优化全览时路线摘要气泡的位置，避让起终点与途经点，必要时上移并用细线连接路线；没有合适位置时保留底部路线卡中的行程信息。
• 获取当前位置使用系统定位，不需要额外配置另一套高德定位 SDK；移除未使用的 Android 电话状态权限。暂停 / 恢复接口仅用于模拟导航。
• Android SDK 通过 Maven、iOS SDK 通过 CocoaPods 获取固定版本；插件交付包不附带 SDK 大二进制，减少下载和云打包上传内容。iOS 地图及导航资源统一配置到主 App。
• 接入步骤、权限、常用参数与包体积说明集中到 README；API 文档补充进阶布局、Web 服务接口和底层接法。

升级说明

• 需要 HBuilderX 5.26、uni-app Vue 3 App NVUE；当前不支持 uni-app x、Web 和小程序。
• 升级后重新制作并安装自定义基座，不能只更新业务页面。
• standard 现在表示插件的经典提示风格，不再表示完整高德默认界面。顶部不保证包含高德默认界面的所有附加服务提示；请在业务页面提供底部操作。
• showDefaultUI 已弃用：省略或传 true 都不会恢复高德默认底栏，false 仍返回错误。界面风格使用 uiMode 选择，需停止后再切换。
• 通用接口默认 uiMode='standard'，随附示例默认 custom。旧 startDrivingNavi 接口继续按驾车处理。
• 活动导航的底部面板最多占地图区域的 60%，还会受实际提示区域限制；司机等待、到站确认等非活动阶段可显示更高的详情。
• 当前不提供后台持续导航和 iOS 模拟器支持。高德账号、Key、服务权限与商业使用授权由使用方自行配置。

平台兼容性

uni-app(5.26)

austin-amap 高德地图与导航

插件源码交付约 0.6 MB，包含 Android / iOS 实现、组件、完整示例和文档，不附带高德 SDK 大二进制。云打包时由 DCloud 获取固定版本 SDK：Android 使用 Maven，iOS 使用 CocoaPods；无需手动下载 SDK，云打包也不要求本机安装 CocoaPods 或 Xcode。最终 APK / IPA 仍包含 SDK，0.6 MB 不是 App 增量。

环境：HBuilderX 5.26+、uni-app Vue 3 App，导航使用 .nvue，普通 .vue 可跳转进入。Android 6.0+；iOS 依赖最低 12.0、arm64 真机。

1. 复制示例

导入完整的 uni_modules/austin-amap，再复制以下文件。已有 pages.json / manifest.json 只合并对应配置，不要整文件覆盖。

{
  "pages": [
    { "path": "pages/navigation/index", "style": { "navigationStyle": "custom", "disableScroll": true } },
    { "path": "pages/driver/index", "style": { "navigationStyle": "custom", "disableScroll": true } },
    { "path": "pages/preview/index", "style": { "navigationStyle": "custom" } }
  ]
}

先保留三页跑通。更名或删除页面时，同时修改示例中的导航地址和 back / goBack 返回地址；不要将插件内 examples 直接注册为路由。

2. 配置权限

合并到项目根目录的 manifest.json：

{
  "vueVersion": "3",
  "app-plus": {
    "modules": { "Geolocation": {} },
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSLocationWhenInUseUsageDescription": "用于获取您的当前位置，提供路线规划和前台导航服务"
        }
      }
    }
  }
}

插件已声明高德 APSService，无需重复添加定位 SDK 或勾选 Maps → 高德地图。本插件不要求电话、相机、存储或麦克风权限；指定坐标的模拟导航无需获取当前位置。

示例先询问用户是否同意高德服务，再加载地图；GPS 还需系统定位授权。将 amap-consent.js 的提示和同意记录接到自己的隐私流程。

3. 填写 Key

在业务项目 utils/amap-config.js 填自己的 Key，不改插件源码：

export default {
  androidMapKey: '',  // Android 平台 SDK Key
  iosMapKey: '',      // iOS 平台 SDK Key
  webServiceKey: '',  // Web 服务 Key，不是 Web 端 JS API Key
}

三项都是 String。跑通全部示例：填当前平台 SDK Key + Web 服务 Key。 仅原生导航、不调用 Web 功能时，Web Key 可留空。Android 调试与正式包签名不同时，分别配置实际 SHA1。

Android Key · iOS Key · Web 服务 Key

示例自动读取该文件，加密版接法相同。自写页面时，先 setAmapConfig(config)；取得用户同意后再 setNaviConfig({ privacyAgree: true }) 并挂载地图。

4. 打包运行

1. HBuilderX → 发行 → 原生 App 云打包，勾选自定义调试基座。
2. 安装到手机，运行项目时选择自定义基座。
3. 首页调用下方入口，同意服务后点击“开始模拟”。

// 普通驾车
uni.navigateTo({ url: '/pages/navigation/index' })

// 步行
uni.navigateTo({ url: '/pages/navigation/index?transportMode=walking' })

// 司机：杭州东站接客 → 萧山机场送达
uni.navigateTo({ url: '/pages/driver/index?mode=emulator' })

正式发布选择传统云打包，配置自己的包名与证书；iOS 需要证书及描述文件。普通加密授权不支持安心 / 离线打包，试用仅可制作基座，正式包需购买并授权到自己的 App。原生代码、SDK 或权限变更后重制基座；只改业务页通常不需要。

5. 传入路线和订单

驾车 / 步行

复制到首页方法中。GPS 使用当前位置；模拟自己的路线时另传 origin：

const query = {
  destination: '120.21257,30.290851', destinationName: '杭州东站',
  transportMode: 'driving', // walking：步行
  mode: 'gps',             // emulator：模拟，需另传 origin
  uiMode: 'custom',        // standard：经典提示
  coordType: 'gcj02', autoStart: '1',
}
const search = Object.keys(query)
  .map(key => encodeURIComponent(key) + '=' + encodeURIComponent(query[key])).join('&')
uni.navigateTo({ url: '/pages/navigation/index?' + search })

打开路线预览

import { ensureAmapConsent } from '@/utils/amap-consent.js'

async function openPreview() {
  if (!await ensureAmapConsent()) return
  uni.navigateTo({
    url: '/pages/preview/index?origin=120.180477%2C30.242235&destination=120.21257%2C30.290851&mode=emulator&transportMode=driving',
  })
}

预览支持多方案横滑、路线气泡和自动全览。开始导航时原生 SDK 重新算路，所选预览路线暂不保证原样进入导航。

司机订单

接口取得订单后，在复制的 pages/driver/index.nvue 的页面方法中执行，开始行程前按接送顺序更新 stops。只替换演示路线时，直接改 data() 中的 stops 数组：

this.stops = [
  { id: 'order-1-pickup', name: '杭州东站', longitude: 120.21257, latitude: 30.290851, kind: 'pickup' },
  { id: 'order-1-dropoff', name: '萧山机场', longitude: 120.4343, latitude: 30.23379, kind: 'dropoff' },
]
this.navigationRequest = this.buildRemainingRequest()

mode=gps 从当前位置出发；模拟用示例起点。中途接其他乘客，将站点插入对应顺序。到站后示例等待用户确认上车 / 送达，接单接口和订单状态由业务处理。司机页 URL 只读 mode、uiMode，起终点和站点通过 stops 设置。

怎么自定义界面

直接改复制出来的页面。两种提示风格都隐藏高德默认“退出 / 中速 / 暂停”底栏，底部由你的页面绘制。

导航中限制面板高度，保留转向、车道、路口空间；司机等候时可显示更高详情。修改时保留 @change 更新状态、@occlusion 更新 bottomOcclusion、@viewport 限制展开上限，示例已连好。

字段说明

页面 URL 参数

适用于复制后的 /pages/navigation/index，值均为字符串。司机页只用 mode / uiMode，预览补充字段见 API。

预览页还支持以下 URL 字段：

坐标为 GCJ-02，经度在前、纬度在后。GPS 原始 WGS-84 / 百度坐标需先转换，convertCoordinate 需要 Web Key；传入自己的路线后，缺少或错误坐标会报错，不会替换成演示坐标。

request：导航参数

自写 .nvue 页面时，将对象传给 austin-navigation-view；示例已完成 URL 转换：

const request = {
  transportMode: 'driving', naviMode: 'emulator', uiMode: 'custom',
  origin: { longitude: 120.180477, latitude: 30.242235, name: '杭州城站' },
  destination: { longitude: 120.21257, latitude: 30.290851, name: '杭州东站' },
  waypoints: [],
}

起终点、途经点坐标结构：

URL 用 mode + 坐标字符串，组件用 naviMode + 坐标对象。 组件默认 GPS / 经典，示例默认模拟 / 简洁。requestId 由组件生成，兼容字段见 API。不要传 showDefaultUI: false，旧字段会报错。

组件属性

austin-navigation-view 在 .nvue 中使用，宽高单位为逻辑 px；模板用 :bottom-occlusion="变量"。

插槽：#overlay 为地图浮层；#top / #bottom 会实际缩小地图。同一块 overlay 面板保持 bottomHeight=0，避免重复占空间。

调用方法

通过 this.$refs.navigation 调用，不要同时调用模块 startNavigation()。

语音 / 视角控制返回请求编号 controlId，是否生效看 @control.ok。退出前 stop，示例已包含返回和离页清理。

事件与返回字段

监听 @事件名="方法"，直接读 event.state 等字段，不用取 event.detail。request 不放 success / fail / complete，组件使用事件：

progress 字段：

navigating 表示已启动；多途经点剩余时间是到最终终点的整段时间，不是下一位乘客的到达时间。guidance / routeChanged / layout 事件见 API。

底部面板常用字段

austin-navigation-panel 高度为逻辑 px，不含安全区。下表为组件默认值，业务页可覆盖：

面板事件：change 返回状态 / 高度，occlusion 返回含安全区的 {height}，dragging 返回 Boolean。refreshContent() 手动重测正文。完整接线与高度计算

插件体积与打包

不要重复引入地图 / 导航 SDK。仅面向 64 位 Android 可选 arm64-v8a。iOS Pod 资源配置为 app，避免云包同时放进插件 framework；本地原生编译按实际产物检查。

常见问题

Web 接口、底层 API、兼容字段和错误码见 API.md。