@bm-helper/uniapp-router

uni-app 路由管理工具，支持 Vue3、H5、各小程序和 App。

特性

• 统一 API：类 Vue Router 风格，覆盖 uni-app 所有跳转场景
• 导航守卫：全局 beforeEach / afterEach，支持异步操作、重定向
• 动态路由：addRoute / removeRoute / hasRoute / getRoutes
• 路径模式匹配：支持 :id、:id? 和 * 路径匹配
• 页面过渡动画：基于 uni-app 原生过渡系统，H5 端通过 CSS 模拟一致效果
• 多平台兼容：H5、微信/支付宝/百度/抖音/QQ/快手/京东/飞书小程序、App
• Composition API：useRouter() / useRoute()
• TypeScript 优先：完整类型定义

安装

npm install @bm-helper/uniapp-router

快速开始

// main.ts
import { createSSRApp } from 'vue'
import App from './App.vue'
import { createRouter } from '@bm-helper/uniapp-router'

const router = createRouter({
  platform: 'h5', // 'h5' | 'app' | 'mp-weixin' | ...
  routes: [
    { path: '/pages/index/index', name: 'index', aliasPath: '/' },
    { path: '/pages/detail/detail', name: 'detail' },
    { path: '/pages/user/:id?', name: 'user-detail' },
    { path: '*', name: 'not-found', redirect: '/pages/404/index' },
  ],
  transition: {
    animationType: 'slide-in-right',
    animationDuration: 300,
  },
})

router.beforeEach((to, from, next) => {
  next()
})

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

<!-- 在页面中使用 -->
<script setup>
import { useRouter, useRoute } from '@bm-helper/uniapp-router'

const router = useRouter()
const route = useRoute()

router.navigateTo({ name: 'detail', query: { id: 1 } })
</script>

导航方式

router.navigateTo({ name: 'detail', query: { id: 1 } })
router.redirectTo({ path: '/pages/login/login' })
router.navigateTo({ name: 'user-detail', params: { id: 42 } })
router.reLaunch('/pages/index/index')
router.switchTab('/pages/tab/tab')
router.navigateBack({ delta: 1 })

动态路由

// 添加路由（返回移除函数）
const remove = router.addRoute({ path: '/pages/admin/admin', name: 'admin' })

// 移除路由
router.removeRoute('admin')

// 检查是否存在
router.hasRoute('admin') // false

// 获取所有路由
router.getRoutes()

动态参数与通配符

const router = createRouter({
  platform: 'h5',
  routes: [
    { path: '/pages/user/:id', name: 'user-detail' },
    { path: '/pages/profile/:tab?', name: 'profile-tab' },
    { path: '/pages/*', name: 'section-fallback', redirect: '/pages/404/index' },
    { path: '*', name: 'not-found', redirect: '/pages/404/index' },
  ],
})

router.resolve('/pages/user/42')?.params // { id: '42' }
router.resolve({ name: 'profile-tab' })?.path // /pages/profile
router.resolve({ name: 'profile-tab', params: { tab: 'settings' } })?.path // /pages/profile/settings

• 匹配优先级：精确路径 > 动态参数 > 通配符
• resolve() 命中动态路径后会返回 params
• record 会指向命中的路由记录，可用于 404/兜底判断

过渡动画

// 全局配置
createRouter({
  transition: { animationType: 'slide-in-right', animationDuration: 300 },
})

// 路由级别（meta.transition）
{ path: '/pages/modal', meta: { transition: { animationType: 'slide-in-bottom' } } }

// 单次跳转
router.navigateTo({ name: 'detail', animationType: 'zoom-fade-in' })

支持动画类型：slide-in-right / slide-in-left / slide-in-top / slide-in-bottom / pop-in / fade-in / zoom-in / zoom-fade-in / none