入门

编程式导航

想在输入 path、name 时看到可选值，可以先按路径与名称补全配置类型声明。下方的导航调用方式不变。

注意：这里name 和 params搭配使用，而path 可以与 query 一起使用。

基础用法

<script setup lang="ts">
import { ref } from 'vue'
import { useRouter } from '@wot-ui/router'
import { getCurrentInstance } from 'vue'

// 使用hooks（推荐）
let router = useRouter()

// 或者 使用全局挂载的router
router = instence?.appContext.config.globalProperties.$Router

// 字符串路径
router.push('/user')

// 带有路径的对象
router.push({ path: '/user' })

// 命名的路由，并加上参数，让路由建立 url
router.push({ name: 'user', params: { username: 'eduardo' } })

// 带查询参数，结果是 /user?username=eduardo
router.push({ path: '/user', query: { username: 'eduardo' } })

// 指定跳转类型（覆盖默认的 push）
router.push({ path: '/user', navType: 'replace' })

// 带动画配置
router.push({ path: '/user', animationType: 'slide-in-right', animationDuration: 300 })

// 带 hash
router.push({ path: '/user', hash: '#section' })

</script>

RouteLocationRaw 参数说明

RouteLocationRaw 可以是字符串或对象，对象形式支持以下属性：

属性	类型	描述
path	`RoutePath`	路由路径；注册类型后提供候选值，默认仍兼容普通字符串
name	`RouteName`	路由名称；注册类型后提供候选值，默认仍兼容普通字符串
params	`RouteParams`	路由参数（与 name 搭配使用）
query	`LocationQuery`	查询参数（与 path 搭配使用）
hash	`string`	URL hash 值
replace	`boolean`	是否使用 replace 方式跳转
navType	`NavType`	跳转类型：`'push'` \| `'replace'` \| `'replaceAll'` \| `'pushTab'` \| `'back'`
animationType	`AnimationType` / `AnimationBackType`	普通跳转使用显示动画，`navType: 'back'` 时使用关闭动画；仅 App 支持窗口动画
animationDuration	`number`	窗口动画持续时间，单位为 ms
delta	`number`	`navType: 'back'` 时返回的页面数

动画类型迁移

AnimationType 使用显示动画：slide-in-right、slide-in-left、slide-in-top、slide-in-bottom、fade-in、zoom-out、zoom-fade-out、pop-in、none、auto。pages.json 的窗口配置也使用这些值。

router.back() 和 navType: 'back' 使用 AnimationBackType：slide-out-right、slide-out-left、slide-out-top、slide-out-bottom、fade-out、zoom-in、zoom-fade-in、pop-out、none、auto。动画名称对应关系见 uni-app 窗口动画。

此前使用关闭动画作为打开动画的代码需要更换为对应的显示动画；返回操作的动画值保持不变。显式以 AnimationType 标注返回动画的代码需改用 AnimationBackType，普通 string 类型的动画变量需收窄为对应联合类型。

router.push({ path: '/user', animationType: 'slide-in-right' })
router.back({ animationType: 'slide-out-right' })
router.push({ path: '/user', navType: 'back', animationType: 'slide-out-right' })

可复用的导航配置使用 RouteNavigationOptions，展开到导航参数中时会保留动画方向。显示动画配置可以省略 navType，关闭动画配置必须带上 navType: 'back'：

import type { RouteNavigationOptions } from '@wot-ui/router'

const opening: RouteNavigationOptions = { animationType: 'pop-in', animationDuration: 300 }
const closing: RouteNavigationOptions = { navType: 'back', animationType: 'pop-out', delta: 1 }
router.push({ path: '/user', ...opening })
router.push({ path: '/user', ...closing })

RouteBackLocation 不再继承 RouteLocationBase。RouteNavigationOptions 和 RouteLocationObject 改为按 navType 区分动画类型的联合类型；需要扩展它们时，使用交叉类型（如 RouteLocationObject & { custom: string }），不再使用 interface extends。

RouteRecordRaw 路由配置说明

路由表中的每个路由配置支持以下属性：

属性	类型	描述
path	`string`	路由路径
name	`string`	路由名称（用于命名路由跳转）
meta	`RouteMeta`	路由元信息（可存储任意自定义数据）
aliasPath	`string`	路由别名路径（兼容旧版）

// 示例：在 pages.json 中配置路由
{
  "path": "pages/user/User",
  "name": "user",
  "meta": {
    "title": "用户中心",
    "requiresAuth": true
  }
}

// 使用 meta 信息
router.beforeEach((to, from, next) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    next({ name: 'login' })
  } else {
    next()
  }
})

在user.vue接收传入的对象参数

<script setup lang="ts">
onLoad((option) => {
  if (option && option.username) {
    const username = option.username
  }
})
</script>

传递对象参数

url有长度限制，太长的字符串会传递失败，可改用窗体通信、全局变量。

<script setup lang="ts">
import { ref } from 'vue'
import { useRouter } from '@wot-ui/router'
import { getCurrentInstance } from 'vue'

let router = useRouter()

const user = {
  name:'小星星',
  label:"小熊熊"
}

// 命名的路由，传递对象参数
router.push({ name: 'user', params: { user: JSON.stringify(user) } })

// path+query，传递对象参数
router.push({ path: '/user', query: { user: JSON.stringify(user) } })

</script>

在user.vue接收传入的对象参数

<script setup lang="ts">
onLoad((option) => {
  if (option && option.user) {
    const user = JSON.parse(decodeURIComponent(option.user))
  }
})

// 返回
function back() {
  router.back()
}
</script>

导航守卫

@wot-ui/router支持全局前置导航守卫 beforeEach和全局后置导航守卫 afterEach，主要用来通过跳转或取消的方式守卫导航。

全局前置守卫 beforeEach

你可以使用 router.beforeEach 注册一个全局前置守卫：

const router = createRouter({ ... })

router.beforeEach((to, from, next) => {
  // next入参 false 以取消导航
  next(false)
})

`beforeEach`守卫方法接收三个参数：

to: 即将要进入的目标
from: 当前导航正要离开的路由
next: 用于resolve beforeEach钩子，需要确保 next 在导航守卫中都被严格调用一次

next 参数说明：

调用方式	描述
`next()`	执行默认路由跳转逻辑
`next(false)`	终止跳转逻辑，取消导航
`next({ path: '/' })`	重定向到不同的页面
`next({ path: '/', navType: 'replaceAll' })`	改变当前跳转类型并跳转到不同的页面

导航守卫支持多种返回方式：

// 方式1：使用 next 回调
router.beforeEach((to, from, next) => {
  if (to.meta.requiresAuth) {
    next({ name: 'login' })
  } else {
    next()
  }
})

// 方式2：返回 Promise
router.beforeEach(async (to, from, next) => {
  const isAuthenticated = await checkAuth()
  if (!isAuthenticated) {
    next(false)
  } else {
    next()
  }
})

// 方式3：同步返回值
router.beforeEach((to, from) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    return { name: 'login' }
  }
  return true
})

beforeEach 返回值： 注册守卫后会返回一个函数，调用该函数可以移除对应的守卫：

const removeGuard = router.beforeEach((to, from, next) => {
  console.log('导航守卫')
  next()
})

// 移除守卫
removeGuard()

全局后置钩子 afterEach

你也可以注册全局后置钩子，然而和守卫不同的是，这些钩子不会接受 next 函数也不会改变导航本身

const router = createRouter({ ... })

router.afterEach((to, from) => {
  console.log(to)
  console.log(from)
})

它对于分析、更改页面标题、声明页面等辅助功能以及许多其他事情都很有用。

afterEach 返回值： 注册后置钩子后会返回一个函数，调用该函数可以移除对应的钩子：

const removeHook = router.afterEach((to, from) => {
  console.log('页面切换完成')
})

// 移除钩子
removeHook()

注意：

后置钩子不接收 next 函数
后置钩子无法改变导航本身
原生跳转（如 uni.navigateTo）也会触发后置钩子
onShow 生命周期会更新路由信息并触发后置钩子

入门 ​

编程式导航 ​

基础用法 ​

RouteLocationRaw 参数说明 ​

动画类型迁移 ​

RouteRecordRaw 路由配置说明 ​

传递对象参数 ​

导航守卫 ​

全局前置守卫 beforeEach ​

beforeEach守卫方法接收三个参数： ​

全局后置钩子 afterEach ​

入门