@wot-ui/router 使用指南

专为 uni-app 设计的轻量级路由库，提供类似 Vue Router 的 API。

核心特性

• 📝 编程式导航
• 🔄 参数传递（params + query）
• 🛡️ 导航守卫
• 📊 路由信息获取
• 🎯 TypeScript 支持

路由配置

// src/router/index.ts
import { pages, subPackages } from 'virtual:uni-pages'

function generateRoutes() {
  const routes = pages.map((page) => ({
    ...page,
    path: `/${page.path}`,
  }))

  subPackages?.forEach((sub) => {
    sub.pages.forEach((page) => {
      routes.push({
        ...page,
        path: `/${sub.root}/${page.path}`,
      })
    })
  })

  return routes
}

const router = createRouter({
  routes: generateRoutes(),
})

export default router

基础导航

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

// 字符串路径
router.push('/pages/detail/index')

// 对象形式
router.push({ path: '/pages/detail/index' })

// 命名路由
router.push({ name: 'detail' })

// 替换当前页面
router.replace({ name: 'login' })

// 返回上一页
router.back()

// 返回多级
router.go(-2)

参数传递

Query 参数

// 跳转
router.push({
  name: 'detail',
  query: { id: '123', type: 'product' },
})

// 获取
const route = useRoute()
const id = route.query.id
const type = route.query.type

Params 参数

// 跳转
router.push({
  name: 'detail',
  params: { id: '123' },
})

// 获取
const route = useRoute()
const id = route.params.id

导航守卫

全局前置守卫

router.beforeEach((to, from, next) => {
  console.log(`导航: ${from.path} → ${to.path}`)

  // 权限检查
  if (to.meta?.requiresAuth && !isLoggedIn()) {
    next({ name: 'login' })
    return
  }

  // 异步守卫
  if (to.name === 'protected') {
    return new Promise((resolve) => {
      showConfirm({
        title: '确认访问',
        success: () => { next(); resolve() },
        fail: () => { next(false); resolve() },
      })
    })
  }

  next()
})

全局后置钩子

router.afterEach((to, from) => {
  console.log(`页面切换完成: ${to.path}`)

  // 页面统计
  trackPageView(to.path)
})

路由信息

const route = useRoute()

// 当前路径
route.path        // '/subPages/detail/index'

// 路由名称
route.name        // 'detail'

// 查询参数
route.query       // { id: '123' }

// 路径参数
route.params      // { id: '123' }

// 完整路径
route.fullPath    // '/subPages/detail/index?id=123'

// 路由元信息
route.meta        // { requiresAuth: true }

页面定义

<script setup lang="ts">
definePage({
  name: 'detail',           // 路由名称
  layout: 'default',        // 布局
  meta: {
    requiresAuth: true,     // 自定义元信息
  },
  style: {
    navigationBarTitleText: '详情',
  },
})
</script>

TabBar 页面跳转

// TabBar 页面使用 reLaunch
router.push({
  name: 'home',
  reLaunch: true,  // 或自动识别 tabBar 页面
})

注意事项

• uni-app 路由限制仍然存在（如页面栈限制）
• TabBar 页面需要特殊处理
• 导航守卫中的异步操作需要返回 Promise
• 参数过长时考虑使用全局状态传递