更新记录

1.0.0（2026-10-21）

兼容蒸汽模式

平台兼容性

uni-app x(5.26)

其他

UTS 高德地图导航（驾车、步行、司机接驾）

面向 uni-app x 的 App 内地图与导航组件。提供普通驾车、司机接送、步行出行三种场景，包含完整路线预览与可自定义的业务底栏。Key 在项目文件中配置，页面无需填写。

环境：HBuilderX 5.26+，uni-app x App，Vapor / VDOM。Android 6.0+；iOS Vapor 15.0+，VDOM 以对应基座最低系统版本为准。本插件使用标准 native-view 组件，普通 uni-app 项目请使用独立的 austin-amap。不支持 Web、小程序或鸿蒙。

1. 导入并注册页面

将完整 uni_modules/austin-amap-x 放入项目。在自己的 pages.json 中追加以下页面，保留已有页面：

{
  "pages": [
    { "path": "uni_modules/austin-amap-x/index", "style": { "navigationBarTitleText": "高德导航", "disableScroll": true } },
    { "path": "uni_modules/austin-amap-x/navi", "style": { "navigationStyle": "custom", "disableScroll": true } },
    { "path": "uni_modules/austin-amap-x/driver", "style": { "navigationStyle": "custom", "disableScroll": true } },
    { "path": "uni_modules/austin-amap-x/preview", "style": { "navigationStyle": "custom", "disableScroll": true } }
  ]
}

打开入口：

uni.navigateTo({ url: '/uni_modules/austin-amap-x/index' })

2. 配置系统定位与权限

演示页在 GPS 模式下使用 uni.getLocation 获取当前位置。在项目根目录的 manifest.json 合并以下配置，保留已有模块和权限说明：

{
  "app-android": {
    "distribute": {
      "modules": { "uni-location": { "system": {} } }
    }
  },
  "app-ios": {
    "distribute": {
      "modules": { "uni-location": { "system": {} } },
      "privacyDescription": {
        "NSLocationWhenInUseUsageDescription": "用于用户主动发起的地图定位、路线规划和前台导航"
      }
    }
  }
}

不要照搬普通 uni-app 的 app-plus 配置，也不需要另外集成一套高德地图 SDK。取得用户对高德服务的同意后，再配置插件和挂载地图；演示入口已包含同意流程。

模块和权限配置修改后重新制作自定义基座。可视化配置入口见 DCloud 的 Android 系统定位配置 和 iOS 系统定位配置。

3. 申请并填写高德 Key

进入 高德开放平台控制台，创建应用，分别添加需要的平台 Key：

在项目文件中配置 Key：

1. 将插件 examples/utils/ 中的两个 .uts 文件复制到项目根目录的 utils/。
2. 把 amap-demo-config.example.uts 复制或改名为 amap-demo-config.local.uts，填写对应平台的 Key：

import { AmapConfigOptions } from '@/uni_modules/austin-amap-x'

const config: AmapConfigOptions = {
  androidMapKey: 'Android 平台 SDK Key',
  iosMapKey: 'iOS 平台 SDK Key',
  webServiceKey: 'Web 服务 Key',
}
export default config

3. 在项目 App.uvue 的现有 onLaunch 中调用一次项目配置函数。以下为 <script setup lang="uts"> 写法：

import { onLaunch } from '@dcloudio/uni-app'
import { configureAmapDemo } from '@/utils/amap-demo-config.uts'

onLaunch(() => {
  configureAmapDemo()
  // 保留项目原有启动逻辑
})

4. 在项目 .gitignore 添加 /utils/amap-demo-config.local.uts。真实 Key 留在宿主项目，插件包只带空白配置模板。

配置函数只登记项目 Key。用户首次进入场景时，页面显示地图服务说明，同意后再初始化 SDK；页面和本地存储均不负责编辑或保存 Key。当前平台的 SDK Key 用于地图与导航，Web 服务 Key 用于地址查询、坐标转换、路线预览。

Android 调试包和正式包的签名不同时，需要对应配置 SHA1。Key 校验的是实际安装包，不是 DCloud AppID。iOS 模拟器同样需要与测试宿主 Bundle ID 匹配的 Key。

4. 制作自定义基座并运行

1. HBuilderX → 发行 → 原生 App 云打包，选择目标平台并制作自定义调试基座。
2. 安装生成的基座。运行项目时选择自定义基座。
3. 进入“高德导航场景”，选择模拟体验和提示样式，再选择普通驾车 / 司机接送 / 步行出行。
4. 普通驾车和步行先进入全屏路线预览，可输入地址或坐标、交换起终点、切换路线，再开始导航。驾车可添加途经点。
5. 司机接送提供订单与乘客信息、联系乘客、站点增删、行程预览和到站确认。导航中可静音、全览、回到车位、拖动底栏和暂停行程。

SDK 版本固定为 Android navi-3dmap:10.0.600_3dmap10.0.600、iOS AMapNavi 11.2.100 / AMapFoundation 1.9.1。云端获取依赖，最终 APK / IPA 仍然包含 SDK。第一次接入、SDK / 原生代码 / 权限变化后需重新制作基座；改业务页面通常只需重新运行。

模拟器提示：Android 如遇高德 OpenGL / EGL 初始化崩溃，可在 Android Studio 的 AVD 设置中使用软件图形渲染。当前 iOS SDK 包含 x86_64 模拟器切片，Apple Silicon 上需要兼容的 Intel 模拟器构建与运行环境；仅有 arm64 真机库不能当成 arm64 模拟器库使用。

5. 在自己的页面嵌入导航

完成上面的项目 Key 配置后，下面是最小 .uvue 页面。用户同意服务后挂载导航。路线坐标使用 GCJ-02，经度在前、纬度在后。

<template>
  <view class="page">
    <button v-if="!opened" @click="open">打开模拟导航</button>
    <AustinNavigationView v-if="opened" :request="request" :auto-start="true"
      :height="height" :bottom-height="80" @error="onError">
      <template #bottom>
        <view class="business"><text>这里放订单、距离信息和业务按钮</text></view>
      </template>
    </AustinNavigationView>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { onReady,  } from '@dcloudio/uni-app'
import { NavigationOptions } from '@/uni_modules/austin-amap-x'
import { ensureAmapDemoConsent } from '@/uni_modules/austin-amap-x/utils/config.uts'
import AustinNavigationView from '@/uni_modules/austin-amap-x/components/austin-navigation-view/austin-navigation-view.uvue'

const opened = ref(false)
const height = ref(uni.getWindowInfo().windowHeight)
function updateHeight(): void { height.value = uni.getWindowInfo().windowHeight }
onReady(() => { updateHeight() })
(() => { updateHeight() })
const request: NavigationOptions = {
  origin: { longitude: 120.180477, latitude: 30.242235, name: '起点' },
  destination: { longitude: 120.21257, latitude: 30.290851, name: '终点' },
  naviMode: 'emulator',
  transportMode: 'driving',
  uiMode: 'custom',
}

async function open(): Promise<void> {
  if (!await ensureAmapDemoConsent()) return
  opened.value = true
}
function onError(result: UTSJSONObject) { console.log(result['errMsg']) }
</script>

<style>
.page { flex: 1; }
.business { height: 80px; padding: 16px; background-color: #ffffff; }
</style>

导航组件卸载时停止并释放本组件的导航。startNavigation() 等底层 API 需要已挂载的原生导航视图；只有 API 调用、没有地图组件，无法显示导航。

路线字段

NaviPoint：longitude: number、latitude: number，可选 name: string。WGS-84 / GPS 坐标先通过 convertCoordinate 转为 GCJ-02，不要把不同坐标系混用。

司机页按站点顺序导航，到站后需业务人员确认接客 / 送达，再进入下一站。接单、订单持久化、乘客信息和支付由业务项目接入。

用页面参数打开路线预览

支持通过坐标参数打开页面。例如，项目已配置 Key 后直接打开驾车预览：

uni.navigateTo({
  url: '/uni_modules/austin-amap-x/preview?mode=emulator&uiMode=custom'
    + '&transportMode=driving&coordType=gcj02'
    + '&origin=120.180477,30.242235&destination=120.21257,30.290851'
    + '&originName=' + encodeURIComponent('杭州城站公交站')
    + '&destinationName=' + encodeURIComponent('杭州东站'),
})

坐标均为 GCJ-02，中文名称和参数内容使用 encodeURIComponent。GPS 模式省略起点时，预览页获取当前位置，定位成功后点击“规划路线”。也支持 request= 后拼接编码后的 NavigationOptions JSON。直接打开 navi 页面可用相同坐标参数，传 autoStart=1 自动开始。

自定义组件与事件

导航视图的主要属性：

top、bottom 插槽会占布局高度，overlay 插槽覆盖地图。使用浮层底栏时，将面板的 occlusion 事件高度传回 bottomOcclusion；完整代码见 navi.uvue / driver.uvue。

面板可设置 state（collapsed / half / expanded）、placement（默认 overlay；flow 为普通布局，不拖动、不播放收展动画），以及 availableWidth、collapsedHeight、halfHeight、expandedHeight、maxHeight、maxHeightRatio、availableHeight、safeBottom、actionsHeight、draggable、autoHeight、contentVersion 和 animationDuration。默认收起，半屏高度 220px、最大高度 420px、操作区高度 48px。业务内容变化后更新字符串或数字 contentVersion，启用 autoHeight 时会重新测量。收展动画默认 220 毫秒，设为 0 可关闭；展开前预留地图避让空间，收起完成后释放。

导航组件暴露 start(requestOverride?)、stop()、pause()、resume()、setMuted(boolean)、setViewMode('follow' | 'overview')、measureSlots() / measureBusinessSlots()。pause() / resume() 用于暂停和继续模拟导航。通过组件 ref 的 $callMethod 调用，两种渲染模式使用相同入口。

面板支持 v-model:state，暴露 setState(state, reasonOrAnimated?) 和 refreshContent() / measureContent()；setState 第二个参数传 false 可立即切换。summary 和默认插槽可读取 state、height。主要事件：

导航提示中的高德转向、车道、路口图片由 SDK 提供。自定义业务图片可放插槽，不支持任意替换 SDK 原生诱导素材。

地图与路线 API

从 @/uni_modules/austin-amap-x 导入 API 和类型：

路线结果包含 routes、selectedRouteId，每条路线有 distance、duration、polyline、steps 等字段。全部类型定义在 utssdk/interface.uts，回调失败时保留 errCode 与 errMsg。

路线预览与导航：预览使用 Web 服务算路；开始原生导航时 SDK 会重新算路，选择的预览路线不保证逐点原样进入导航。

把演示页复制到业务项目

保留整个插件目录，将需要的页面复制到自己的 pages 目录：

1. 注册新的页面路由；导航页、司机页和路线预览页保持 navigationStyle: custom。
2. 页面中的组件和工具均从 @/uni_modules/austin-amap-x/... 导入，插件目录不改名时无需修改导入路径。
3. 改成自己的页面路由：页面跳转及 utils/route-input.uts 中 navigationPageUrl() 默认指向插件演示目录。可在业务项目封装自己的跳转函数。
4. 保留项目 utils/amap-demo-config.local.uts 的 Key 配置，按业务接口生成路线与站点；也可以用自己项目的隐私同意流程替换示例弹窗。

常见问题

地图不显示 / 导航准备失败：确认已使用包含高德 SDK 的新基座、当前平台 Key 不为空且包名 / SHA1 / Bundle ID 匹配，先同意服务再挂载地图。修改 Key 后退出导航页重新进入。

只显示“正在算路”：检查网络、Key 授权和原生错误日志。同步返回 ok 不代表已进入导航，组件会等待异步 navigating 并提供超时提示。

拖动底栏遮住车标：检查 occlusion → bottomOcclusion 绑定，采用 viewport 回执中的实际高度上限；不要仅修改 CSS 而不通知原生地图。

切后台还能导航吗：本版本提供前台导航，不承诺后台持续导航或强制关闭后的保活。需要实时 GPS 的功能应在前台使用。