更新记录
1.0.0(2026-11-18)
第一版
平台兼容性
uni-app(4.51)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | - | - | √ | √ | 6.0 | 15 | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | - | - | - | - | - | - |
uni-app x(4.51)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | 6.0 | 15 | √ | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
wen-navigation
多地图原生展示、路线与定位控制、自有离线路网和资源导入导出。
功能介绍
- MapLibre 自有资源与高德、百度、腾讯、Google 原生地图接入。
- 点位检索、坐标设置、路线规划与导航状态查询。
- 离线路网资源导入、校验、导出与删除。
- 定位生命周期、轨迹显示、主题及地图交互选项。
平台兼容性
| 项目 | 要求 |
|---|---|
| HBuilderX | 5.26 或更新版本 |
| uni-app / uni-app x | Vue 3;原生 App |
| Android | API 23 起;部分系统能力有更高版本要求 |
| iOS | 16.2 起;以设备能力及宿主配置为准 |
| HarmonyOS | 使用 app-harmony 源码及其声明的 SDK / 权限 |
| Web / 小程序 | 不提供原生能力 |
插件测试使用方法
- 在插件市场绑定自己的项目 AppID,将插件导入项目的
uni_modules/wen-navigation。本地使用时也可直接复制完整插件目录。 - 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
- 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
- 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
- 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 Key、Token、账号密码或签名私钥。
使用示例
import { nativeNavigationRequest } from '@/uni_modules/wen-navigation'
nativeNavigationRequest('open', JSON.stringify({
"config": {
"provider": "maplibre",
"offlineOnly": true
},
"consent": true
}), (raw: string) => {
const result = JSON.parseObject(raw)
if (result == null) return
if (result.getNumber('code') != 0) {
uni.showToast({ title: result.getString('message') ?? '操作失败', icon: 'none' })
return
}
console.log(result['data'])
})
API 介绍
原生入口接收 operation、JSON 字符串 payload 和回调。回调统一返回 { code, message?, data? };code 为 0 表示成功。
nativeNavigationRequest
nativeNavigationRequest(operation: string, payload: string, done: (result: string) => void): void
配置参数
配置通过打开/启动操作传入;其他操作参数以示例调用为准。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
provider |
enum | "maplibre" |
地图引擎 |
theme |
enum | "light" |
视觉主题 |
mapType |
enum | "normal" |
底图类型 |
centerLat |
number | 31.2304 |
中心纬度 WGS84;最小 -85;最大 85 |
centerLng |
number | 121.4737 |
中心经度 WGS84;最小 -180;最大 180 |
zoom |
number | 16 |
初始缩放;最小 3;最大 20 |
minZoom |
number | 3 |
最小缩放;最小 3;最大 18 |
maxZoom |
number | 20 |
最大缩放;最小 5;最大 20 |
bearing |
number | 0 |
初始方向;最小 0;最大 359 |
pitch |
number | 0 |
俯仰角;最小 0;最大 60 |
accentColor |
string | "#197a68" |
界面强调色;最长 7 |
routeColor |
string | "#147dca" |
路线颜色;最长 7 |
routeOutlineColor |
string | "#ffffff" |
路线描边色;最长 7 |
routeWidth |
number | 7 |
路线宽度 dp;最小 2;最大 18 |
routeOutlineWidth |
number | 2 |
描边宽度 dp;最小 0;最大 6 |
markerColor |
string | "#e8913b" |
标记颜色;最长 7 |
markerScale |
number | 1 |
标记缩放;最小 0.5;最大 2 |
markerLabels |
boolean | true |
显示标记名称 |
showCompass |
boolean | true |
显示指南针 |
showScale |
boolean | true |
显示比例尺 |
showZoomControls |
boolean | true |
显示缩放按钮 |
scrollGestures |
boolean | true |
地图平移 |
zoomGestures |
boolean | true |
缩放手势 |
rotateGestures |
boolean | true |
旋转手势 |
tiltGestures |
boolean | true |
俯仰手势 |
traffic |
boolean | false |
实时路况(厂商支持时) |
buildings |
boolean | true |
三维建筑(厂商支持时) |
showPois |
boolean | true |
显示资源点位 |
showTrack |
boolean | true |
显示本次轨迹 |
maxTrackPoints |
number | 2000 |
轨迹点上限;最小 100;最大 10000 |
keepScreenOn |
boolean | true |
导航保持亮屏 |
enableLocation |
boolean | false |
启用真实定位(另需授权) |
followLocation |
boolean | true |
导航跟随位置 |
locationIntervalMs |
number | 1500 |
定位间隔 ms;最小 1000;最大 30000 |
minDistanceM |
number | 2 |
最小定位位移 m;最小 0;最大 50 |
locationAccuracyM |
number | 80 |
接受的精度上限 m;最小 5;最大 500 |
maxLocationAgeMs |
number | 15000 |
定位过期阈值 ms;最小 3000;最大 120000 |
offRouteDistanceM |
number | 35 |
偏航阈值 m;最小 10;最大 200 |
arrivalDistanceM |
number | 12 |
到达阈值 m;最小 3;最大 100 |
voiceEnabled |
boolean | true |
系统语音播报 |
voiceVolume |
number | 0.8 |
播报音量;最小 0;最大 1 |
voiceRate |
number | 1 |
播报语速;最小 0.5;最大 2 |
simulationSpeedMps |
number | 8 |
模拟速度 m/s;最小 1;最大 40 |
routeMode |
enum | "walk" |
出行方式 |
routeStrategy |
enum | "shortest" |
路线偏好 |
avoidTolls |
boolean | false |
避开收费(高德驾车) |
avoidHighways |
boolean | false |
避开高速(高德驾车) |
avoidCongestion |
boolean | false |
避开拥堵(高德驾车) |
snapToRoute |
boolean | true |
位置吸附路线 |
autoRecalculate |
boolean | true |
偏航自动重新规划 |
autoRecalcCooldownS |
number | 15 |
重新规划冷却 s;最小 5;最大 120 |
units |
enum | "metric" |
距离单位 |
resourceId |
string | "demo-campus" |
离线资源 ID;最长 64 |
offlineOnly |
boolean | true |
仅使用本地离线资源 |
wifiOnly |
boolean | true |
下载仅限 Wi-Fi |
maxStorageMB |
number | 512 |
自有资源总配额 MB;最小 32;最大 4096 |
maxDownloadMB |
number | 128 |
单包下载上限 MB;最小 1;最大 2048 |
maxUnpackedMB |
number | 256 |
单包解压上限 MB;最小 2;最大 4096 |
maxArchiveEntries |
number | 2000 |
压缩包文件数上限;最小 10;最大 20000 |
maxPackages |
number | 30 |
离线包数量上限;最小 1;最大 100 |
networkTimeoutS |
number | 20 |
网络超时 s;最小 5;最大 90 |
maxRetries |
number | 2 |
下载失败重试次数;最小 0;最大 5 |
JavaScript 封装接口
普通 uni-app 页面可使用插件目录中的 client.js。调用前先完成平台权限申请;异步操作用 await / catch 处理。具体参数类型见同目录的 client.d.ts 或 index.d.ts。
nativeAtlas
从 client.js 导入。
| 方法与参数 | 原生 operation |
|---|---|
open(config, consent=false, centerOnResource=false, options={}) |
open |
status() |
status |
capabilities() |
capabilities |
credentialsStatus() |
credentialsStatus |
saveCredentials(provider, values, persist=false) |
saveCredentials |
clearCredentials(provider) |
clearCredentials |
resources() |
resources |
openResources(config, consent=false) |
openResources |
download(config, id, url, sha256) |
download |
clearDownloads() |
clearDownloads |
pauseDownload() |
pauseDownload |
deleteResource(id) |
deleteResource |
command(name, value={}) |
command |
diagnostics() |
diagnostics |
resourceNodes(id) |
resourceNodes |
search(query, id) |
search |
permissions() |
permissions |
requestPermission(kind) |
requestPermission |
locate() |
locate |
exportResource(id) |
exportResource |
importResource(path, config, consent=false) |
importResource |
shareResource(path) |
shareResource |
在项目页面中定制
场景预设、按钮排版、页面文案和配色由示例项目的 pages 目录及项目自身的公共文件管理;安装插件不需要接收这些页面。可以直接修改页面,或按自己的设计重新编写。插件只提供原生能力、参数默认值及校验,不再导出业务 PRESETS。
配置函数只接收配置对象,不接收场景名称;多种预设在页面里定义,再把对象传入。未提供的字段由插件补齐默认值。
import { createNavConfig } from '@/uni_modules/wen-navigation/client.js'
// 这份对象写在自己的页面里,字段值可由表单或业务数据产生。
const options = { routeMode: 'walk', theme: 'dark' }
const config = createNavConfig(options)
使用注意
- 示例不包含地图 Key。商业地图需申请正确平台的 Key,绑定自己的包名、签名或 Bundle ID。
- 腾讯等引擎的路线能力需要配置应用自己的 HTTPS 路线服务端点,地图 Key 不等于路线服务。
- 离线示例路网仅用于本机体验;真实道路导航需要合法地图数据、可用定位和路线服务。
- Google 地图需要可用的 Google Play 服务。不同平台的提供商支持范围以能力查询为准。
隐私、权限声明
1. 本插件需要申请的系统权限列表
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
iOS 用途说明在 app-ios/Info.plist 中,鸿蒙权限在 app-harmony/module.json5 中;宿主仍需按实际业务说明用途并配置能力。
2. 本插件采集的数据、发送的服务器地址、以及数据用途说明
根据配置处理定位点、地图视图和路线。使用商业地图时 SDK 会与所选地图服务商通信,宿主需披露相应 SDK 隐私政策。离线资源保存在本机。
3. 本插件是否包含广告
不包含广告。

收藏人数:
购买源码授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 18
赞赏 0
下载 12771027
赞赏 1959
赞赏
京公网安备:11010802035340号