更新记录

1.11.0（2026-07-10） 下载此版本

新增

• TabBar / TabBarItem 组件 - 自定义底部导航栏，需配合使用
  • TabBar Props：color / selectedColor / bgColor / borderStyle / fixed / border / placeholder / safeAreaInsetBottom / zIndex / beforeChange
  • TabBar Events：change(item, index) / error(error)
  • TabBarItem Props：to / text / iconPath / selectedIconPath / dot / badge / badgeMax / badgeColor / replace
  • TabBarItem Slots：#icon="{ active }" 自定义图标、default 自定义文字
  • 内置徽标系统：dot 小红点（优先级高于 badge）、badge 数字/文字徽标、badgeMax 上限、badgeColor 自定义颜色
  • beforeChange 拦截器：返回 false 或 reject 阻止切换，支持异步
• SCSS 主题定制 - 组件样式迁移到 SCSS，支持双层级覆盖
  • SCSS 变量 !default：编译时覆盖（通过 vite css.preprocessorOptions.scss.additionalData）
  • CSS 自定义属性：运行时覆盖（在父元素设置 --mx-tabbar-* / --mx-tabbar-item-*）
  • TabBar 变量：--mx-tabbar-height / --mx-tabbar-background / --mx-tabbar-border-color
  • TabBarItem 变量：--mx-tabbar-item-icon-size / --mx-tabbar-item-font-size / --mx-tabbar-item-gap / --mx-tabbar-badge-color / --mx-tabbar-badge-dot-size / --mx-tabbar-badge-font-size / --mx-tabbar-badge-min-width / --mx-tabbar-badge-line-height / --mx-tabbar-badge-padding
• TabBarItemProps 类型导出 - 从 @meng-xi/uni-router 主入口新增导出，用于 TabBar change 事件回调类型标注

优化

• 组件目录按 easycom 规范重构 - 组件从扁平文件改为 components/<name>/<name>.vue 嵌套结构，符合 easycom 自动注册约定
  • components/RouterLink.vue → components/router-link/router-link.vue
  • components/TabBar.vue → components/tab-bar/tab-bar.vue
  • components/TabBarItem.vue → components/tab-bar-item/tab-bar-item.vue
  • 共享上下文 tabbar-context.ts → tab-bar/context.ts
  • 组件类型提取到同级 type.ts（router-link/type.ts、tab-bar/type.ts）
• uni_modules 版本组件导入改为本地 js_sdk - mxuni-router 包内组件从 @meng-xi/uni-router 改为相对路径引用 ../../js_sdk/index，消除对 npm 包的运行时依赖
• uni_modules 版本标签名变更 - <mxuni-router> 改为 <RouterLink>（easycom 自动注册）
• 组件 TypeScript 类型提取 - 各组件 props/emits 类型提取到同级 type.ts，共享上下文（InjectionKey + 接口）放在 context.ts
• 组件 CSS → SCSS - RouterLink、TabBar、TabBarItem 样式全部迁移到 SCSS，使用变量和自定义属性

迁移说明

npm 用户需更新组件导入路径：

uni_modules 用户无需修改，easycom 自动注册 <RouterLink> / <TabBar> / <TabBarItem>。

1.10.0（2026-07-09） 下载此版本

新增

• 内置页面间通信管理器 - 新增 useUniEventChannel 选项与 UniEventChannel 类，基于 uni.$emit/$on/$off/$once 全局事件总线实现，替代 uni.navigateTo 原生 EventChannel，使所有导航方式（push/replace/relaunch）均支持页面间双向通信
  • RouterOptions.useUniEventChannel?: boolean（默认 false）- 启用后所有导航方式使用内置通信管理器；默认 false 时仅 push 使用 uni.navigateTo 原生 EventChannel，其他方式不支持页面通信
  • UniEventChannel 类 - 实现 EventChannel 接口，提供 emit / on / once / off 方法；每次导航生成唯一 navigationId（格式 nav-<timestamp>-<seq>），通过 wrapEventName() 包装为 uni-router:{navId}:{eventName} 隔离事件通道，避免多导航间事件串扰
  • __nav_id 通过 URL query 传递，目标页面 syncCurrentRoute 时读取并重建通道，H5 刷新后仍可恢复通信
  • 新增 noopChannel 导出 - 空操作通道，所有方法均为 no-op 并返回自身；usePageChannel() 在无 __navId 时返回 noopChannel，避免空指针
• Sticky 事件缓存机制 - emit() 始终将事件参数缓存到 pendingEvents，on() / once() 注册监听器时异步触发已缓存事件（不删除缓存），解决发送方 emit 与目标页 setup 注册监听的时序竞态
  • 适用场景：发起页导航后立即 emit，目标页 setup 中 on 监听时仍能收到缓存事件
  • 缓存随 UniEventChannel.destroy() 清理（页面 onUnmounted 时自动调用）
• usePageChannel() 组合式 API - 目标页面获取通信通道的便捷方法
  • 读取 route.params.__navId，返回对应的 UniEventChannel 实例；无 __navId 时返回 noopChannel
  • onUnmounted() 时自动调用 destroyChannel(navId) 清理监听器与缓存，避免内存泄漏
• NavigationResult 返回类型 - push / replace / relaunch 返回值从 RouteLocation 扩展为 NavigationResult（继承 RouteLocation，新增可选 eventChannel?: EventChannel）
  • 默认模式：仅 push（对应 uni.navigateTo）的 eventChannel 可用
  • useUniEventChannel: true：所有导航方式均返回内置 UniEventChannel
  • 类型向后兼容：NavigationResult extends RouteLocation，原 const route: RouteLocation = await router.push(...) 仍可用
• 通道注册表（内部） - registerChannel / getOrCreateChannel / getRegisteredChannel / hasChannel / destroyChannel 管理 navId → UniEventChannel 映射
  • registerChannel 采用 first-wins 策略：同一 navId 已存在通道时返回 false，避免重复注册
  • getOrCreateChannel 优先复用已注册通道，无则新建
• RouterLink 的 navigated 事件支持所有导航方式 - 配合 NavigationResult 返回类型，navigate() 现对 push/replace/relaunch 统一触发 navigated 事件并传递 eventChannel（默认模式仅 push 有值，useUniEventChannel: true 时所有方式均有值）；1.9.0 中 replace/relaunch 无 eventChannel，仅 push 触发为当时一致行为

优化

• RouterLink 的 events prop 与 navigated 事件 JSDoc 完善 - 明确说明默认模式下 events 仅 push 生效、navigated 的 eventChannel 仅 push 有值；启用 useUniEventChannel 后所有导航方式均生效

1.9.0（2026-07-06） 下载此版本

新增

• 全局 mixin 自动同步路由状态 - install() 中注册 app.mixin({ onShow() { router.syncRoute() } })，每个页面 onShow 时自动同步路由状态，无需在各页面手动调用 syncRoute()
  • mixin 钩子先于组件自身 onShow 执行，配合 syncRoute() 的去重机制（path + query 相同则跳过）避免重复同步
  • 应用从后台回到前台时，当前活动页的 onShow 会自动触发同步，App.vue 的 onShow 无需手动调用
  • onLoad 早于 onShow，若需在 onLoad 中读取路由信息可手动调用 syncRoute()

修复

• back() 后 params 丢失 - push / replace 时实际导航 URL 保留 __params_key（route.query 中不可见），back() 返回原页面后 syncCurrentRoute 从 URL 读取 key 并用 peek 重建 params
  • 问题：matcher.resolve 会从 query 中移除 __params_key，导致实际导航 URL 不含 key，back() 后无法从 URL 重建 params
  • 修复：performNavigation 在 resolve 后通过 extractParamsKey 提取 key，executeNavigation 将 key 拼回实际导航 URL 的 query 中；syncCurrentRoute 从 URL 读取 key 并用 peek（非 get）重建 params，避免惰性清理误删
• setCurrentRoute 执行时机 - setCurrentRoute(to) 提前到 uni 导航 API 调用之前执行，确保目标页 onLoad / onShow 时 route.value 已是完整目标路由（含 name / params）
  • 问题：此前 setCurrentRoute 在 uni API 成功后执行，目标页 onLoad / onShow 触发时 currentRoute 仍为来源路由，导致 route.value 不含目标路由信息
  • 修复：在调用 navigateTo / replaceTo / relaunchTo 之前调用 setCurrentRoute(to)；导航 API 失败时回滚到 from

平台兼容性

uni-app(3.7.10)

uni-app x(3.7.10)

其他

@meng-xi/uni-router

为 uni-app (Vue 3) 提供类似 vue-router 风格的路由管理系统（uni_modules 版本）。

仅支持 Vue 3 — 基于 Vue 3 Composition API，不支持 Vue 2 项目。

特性

• vue-router 风格 API - push / replace / relaunch / back
• 路由守卫 - beforeEach / beforeResolve / afterEach / beforeEnter，支持 guardRoute 冷启动补执行
• 页面间通信 - useUniEventChannel 内置通信管理器，粘性缓存确保时序安全
• 声明式组件 - RouterLink / TabBar / TabBarItem，easycom 自动注册
• 页面参数传递 - params 传递复杂数据，back() 后自动保留
• 查询参数增强 - queryInt() / queryNumber() / queryBool()
• 错误处理 - RouterError / NavigationFailure / UniApiError，instanceof 精准判断

安装

将 mxuni-router 目录复制到项目的 uni_modules 目录下即可，无需 npm 安装。

快速开始

// main.ts
import { createSSRApp } from 'vue'
import { createRouter } from './uni_modules/mxuni-router/js_sdk/index.js'
import App from './App.vue'

const router = createRouter({
    routes: [
        { path: 'pages/index/index', name: 'home', meta: { title: '首页' } },
        { path: 'pages/about/about', name: 'about', meta: { requireAuth: true } }
    ],
    interceptUniApi: true
})

export function createApp() {
    const app = createSSRApp(App)
    app.use(router)
    return { app }
}

组件在 uni_modules 中自动注册，直接使用即可：

<RouterLink to="/pages/about/about">关于</RouterLink>

<TabBar selected-color="#007aff">
    <TabBarItem to="/pages/index/index" text="首页" />
    <TabBarItem to="/pages/about/about" text="关于" :badge="5" />
</TabBar>

文档

📖 https://mengxi-studio.github.io/uni-router/v1/

License

MIT