更新记录

2.1.6（2026-06-28）

• 底部行程进度：整块在白底栏内居中；剩余时间在「距离 + ETA」行宽度内居中（不改 Mapbox 约束，避免时间行消失/白底撑满屏）
• 出行方式切换条：去掉外层背景色；静音按钮与切换条同一行左侧对齐
• 导航页：Mapbox 官方转向横幅保持默认左右布局；关闭/静音按钮圆角

2.1.0（2026-06-28）

• 插件市场上架 ID：cmk-mapboxnav（作者前缀 cmk）
• 补充 readme / changelog / license
• 导航页内支持骑行 / 汽车 / 步行切换
• Android UTS + Maven 依赖（Maps 11.24.3 / Navigation 3.24.3）
• thin AAR + 云端拉取 Mapbox SDK，避免上传体积超限

平台兼容性

uni-app(4.36)

Mapbox 导航 (Android)

基于 Mapbox Maps 11.24.3 + Navigation 3.24.3 的 uni-app UTS 插件，提供 Android 端路线规划与实时导航（驾车 / 骑行 / 步行，导航页内可切换）。

平台：仅 App-Android（Vue2）。iOS 暂未支持。
依赖：用户需自备 Mapbox Access Token（pk. 开头）。
当前版本：见 package.json → version（建议 2.1.6+）

安装

1. 从插件市场导入 cmk-mapboxnav 到项目 uni_modules/ 目录。
2. 不要在 manifest 中勾选同名「原生语言插件」；本插件为 UTS，随 uni_modules 自动集成。
3. 使用 HBuilderX 4.36+（建议 5.x），制作 Android 自定义调试基座 后真机测试。
4. 每次更新插件版本后：卸载旧 App → 重新制作自定义基座 → 选自定义基座运行。

新建项目试用（必读）

从插件市场导入后，不能直接「标准基座运行」。UTS 插件必须打进自定义基座。

步骤

1. 插件市场 → 试用/购买 → 导入到项目（确认存在 uni_modules/cmk-mapboxnav/）。
2. manifest → App 原生插件配置：nativePlugins 留空，不要勾选任何 Mapbox 相关原生插件。
3. 发行 → 原生 App-云打包 → 制作自定义调试基座（只勾 Android）。
4. 等待云端打包完成，卸载手机上旧 App（含旧标准/旧基座）。
5. 运行 → 运行到手机或模拟器 → 运行基座选择 → 自定义调试基座。
6. 再点运行到 Android 真机。

若日志出现 uts插件[cmk-mapboxnav]不存在，请重新打包自定义基座，说明当前手机上的基座没有编入本插件——按上面 3～5 步重做。

页面代码

本插件仅含导航 API， 最小页面示例见下方「快速开始」。pages.json 只需注册你的 index 页，无需 easycom 配置 mapbox 组件。

快速开始

import {
  initMapboxServices,
  navigationFromCurrentLocation,
  routePlanning,
  stopNavigation
} from '@/uni_modules/cmk-mapboxnav/js_sdk/index.js'

// 1. 初始化（全局调用一次，传入你的 Mapbox Token）
await initMapboxServices({
  accessToken: 'pk.你的MapboxToken'
})

// 2. 从当前位置导航到目的地
await navigationFromCurrentLocation({
  endLat: 39.917337,
  endLng: 116.397056,
  endName: '故宫博物院',
  routeProfile: 'cycling', // driving | cycling | walking
  showProfileSwitcher: true // 是否显示导航页内 骑行/汽车/步行 切换条，默认 true
})

// 3. 指定起终点路线规划（进入同一导航页）
await routePlanning({
  startLat: 39.904556,
  startLng: 116.427231,
  startName: '北京站',
  endLat: 39.917337,
  endLng: 116.397056,
  endName: '故宫博物院',
  routeProfile: 'driving',
  showProfileSwitcher: false // 隐藏切换条，仅用初始 routeProfile
})

// 4. 停止导航（关闭导航 Activity）
stopNavigation()

API

options 常用字段

导航页 UI 说明

云打包说明

manifest

• nativePlugins 留空，勿勾选旧版 cmk_MapboxNav 原生插件。

Android 权限

插件已在 utssdk/app-android/AndroidManifest.xml 声明定位、前台服务、通知等权限；请在应用 manifest.json 中保留定位相关权限说明（隐私政策需说明用途）。

Mapbox SDK 依赖（Maven）

Mapbox SDK 通过 utssdk/app-android/config.json 的 Maven 仓储 在云端拉取（非 fat AAR 上传），上传体积约 < 1MB。

若云打包报 Could not find com.mapbox...：

1. 确认仓储可公网访问；
2. 或参考 config.maven.example.json 替换为你自己的 Mapbox SDK 镜像；
3. 修改后需 重新制作自定义基座。

libs/ 目录仅含 thin AAR（插件原生 UI 与桥接，约 55KB），不要向 libs/ 放入 Mapbox vendor AAR。

config.json 已包含 androidx.databinding:viewbinding（Mapbox 官方 UI 组件必需）。

注意事项

1. Mapbox 账号与计费：路线与地图请求消耗 Mapbox 配额，请遵守 Mapbox 服务条款。
2. Token 安全：生产环境建议通过服务端下发 Token，勿硬编码在客户端。
3. 首次冷启动：地图样式首次加载较慢，属正常现象。
4. Vue3：当前版本仅验证 Vue2；Vue3 标记为未测试。
5. 更新插件后界面无变化：必须重新制作自定义基座；建议删除 unpackage 后重打。

目录结构

cmk-mapboxnav/
├── package.json
├── readme.md
├── changelog.md
├── license.md
├── js_sdk/index.js          # Vue2 Promise 封装（推荐引用）
└── utssdk/
    ├── interface.uts        # API 类型声明
    └── app-android/
        ├── index.uts
        ├── config.json      # Gradle 依赖与 Maven 仓储
        ├── AndroidManifest.xml
        └── libs/
            └── cmk_MapboxNav-release.aar   # thin 插件 AAR

常见问题

技术支持

• 插件 ID：cmk-mapboxnav
• 版本：package.json → version
• 更新记录：changelog.md