路由使用指南

本项目使用了 uni-mini-router 配合 unplugin-vue-router 和 vite-plugin-uni-pages 来实现类似 Vue Router 的路由体验。

1. 核心特性

• 自动生成路由: 基于文件系统自动生成路由表（pages.json），无需手动配置 routes 数组。
• 组合式 API: 支持 useRouter 和 useRoute 钩子。
• 参数传递: 支持通过 query 和 params 传递参数（params 需配合 name 使用）。
• 路由守卫: 支持全局 beforeEach 和 afterEach 守卫。

2. 基础用法

2.1 引入

在 <script setup> 中，useRouter 和 useRoute 已经配置为自动导入，可以直接使用。

// const router = useRouter() // 自动导入，无需手动 import
const router = useRouter()

2.2 页面跳转

保留当前页跳转 (navigateTo)

// 通过路径跳转
router.push('/pages/login/index')

// 通过名称跳转 (推荐)
router.push({ name: 'login' })

// 带查询参数 (URL query)
router.push({ 
  path: '/pages/product/detail',
  query: { id: '123' } 
})

关闭当前页跳转 (redirectTo)

router.replace({ name: 'order-list' })

返回上一页 (navigateBack)

router.back()
// 或者指定返回层数
// router.go(-1)

跳转 Tabbar 页面 (switchTab)

router.pushTab({ path: '/pages/home/index' })

关闭所有页面打开新页面 (reLaunch)

router.replaceAll({ name: 'login' })

3. 路由定义与命名

本项目使用 vite-plugin-uni-pages 自动管理路由。

3.1 页面命名

在页面的 <script setup> 中使用 definePage 宏来定义路由名称和页面样式：

<script setup lang="ts">
definePage({
  name: 'goods-detail', // 路由名称，用于 router.push({ name: 'goods-detail' })
  style: {
    navigationStyle: 'custom',
    navigationBarTitleText: '商品详情'
  }
})
</script>

如果未指定 name，默认会根据文件路径生成（例如 pages/home/index -> pages-home-index），建议显式指定 name 以便维护。

4. 参数传递与接收

4.1 传递参数

方式一：Query (推荐) 参数会拼接到 URL 后面，页面刷新不丢失。

router.push({
  name: 'goods-detail',
  query: { id: '1001', type: 'seckill' }
})

方式二：Params 必须配合 name 使用。uni-mini-router 会自动处理参数传递。

router.push({
  name: 'goods-detail',
  params: { id: '1001' }
})

4.2 接收参数

方式一：onLoad (标准 UniApp 方式) 推荐在 onLoad 生命周期中接收参数。

import { onLoad } from '@dcloudio/uni-app'

onLoad((options) => {
  console.log(options?.id) // 获取参数
})

5. 路由守卫

全局路由守卫配置在 src/router/index.ts 文件中。

5.1 全局前置守卫 (beforeEach)

用于处理登录拦截、权限校验等。

router.beforeEach(async (to, from, next) => {
  // 1. 白名单检查
  if (WHITE_LIST.includes(to.path)) {
    next()
    return
  }
  
  // 2. 登录检查
  const authStore = useAuthStore()
  if (!authStore.isLoggedIn) {
    next({ path: '/pages/login/index' })
    return
  }
  
  next()
})

5.2 全局后置钩子 (afterEach)

用于页面切换后的逻辑，如日志上报。

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

6. 常见问题

1. Tabbar 跳转: 跳转到 Tabbar 页面必须使用 pushTab，使用 push 无效。
2. Params 丢失: 在 H5 刷新时，单纯的内存 params 会丢失，但 uni-mini-router 通常会将其序列化到 URL query 中以保证兼容性。建议优先使用 query 传递参数。
3. 路径书写: 路径必须以 / 开头，例如 /pages/home/index。