更新记录

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

多地图原生展示、路线与定位控制、自有离线路网和资源导入导出。

功能介绍

  1. MapLibre 自有资源与高德、百度、腾讯、Google 原生地图接入。
  2. 点位检索、坐标设置、路线规划与导航状态查询。
  3. 离线路网资源导入、校验、导出与删除。
  4. 定位生命周期、轨迹显示、主题及地图交互选项。

平台兼容性

项目 要求
HBuilderX 5.26 或更新版本
uni-app / uni-app x Vue 3;原生 App
Android API 23 起;部分系统能力有更高版本要求
iOS 16.2 起;以设备能力及宿主配置为准
HarmonyOS 使用 app-harmony 源码及其声明的 SDK / 权限
Web / 小程序 不提供原生能力

插件测试使用方法

  1. 在插件市场绑定自己的项目 AppID,将插件导入项目的 uni_modules/wen-navigation。本地使用时也可直接复制完整插件目录。
  2. 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
  3. 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
  4. 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
  5. 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 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. 本插件是否包含广告

不包含广告。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:INTERNET、ACCESS_NETWORK_STATE,用于地图、路线服务和资源下载;ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION,用于用户主动开启的前台定位导航。地图 SDK 依赖还可能合并 ACCESS_WIFI_STATE 等权限。 iOS:使用期间位置授权,对应 NSLocationWhenInUseUsageDescription。 HarmonyOS:INTERNET、GET_NETWORK_INFO、APPROXIMATELY_LOCATION、LOCATION,用于地图服务通信和前台定位导航。 当前导航功能不以后台持续定位权限作为默认前提。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。