组合式函数

vitarx-router 提供了一组组合式函数（Composables），用于在组件中访问路由实例、获取路由信息、创建链接助手以及注册组件内导航守卫。

useRouter()

获取当前应用中注册的路由器实例。

类型定义

function useRouter(): Router
function useRouter(allowEmpty: false): Router | null
function useRouter(allowEmpty: true): Router

参数

参数	类型	说明
allowEmpty	`boolean`	是否允许返回空值，默认为 `false`

返回值

条件	类型	说明
无参数	`Router`	路由器实例，未找到时抛出异常
`allowEmpty = false`	`Router \| null`	路由器实例或 `null`
`allowEmpty = true`	`Router`	路由器实例，未找到时抛出异常

详情

不传参数或传入 true：如果未找到路由器实例，会抛出 Error
传入 false：如果未找到路由器实例，返回 null 而不抛出异常

useRouter() 依赖 Vitarx 的依赖注入系统，需要先通过 app.use(router) 安装路由器。

示例

import { useRouter } from 'vitarx-router'

// 获取路由器实例（未安装时抛出异常）
const router = useRouter()

// 安全获取（未安装时返回 null）
const router = useRouter(false)
if (router) {
  router.push('/home')
}

useRoute()

获取当前路由位置对象，返回深层只读的 RouteLocation。

类型定义

function useRoute(global?: boolean): DeepReadonly<RouteLocation>

参数

参数	类型	默认值	说明
global	`boolean`	`false`	是否返回全局路由对象

返回值

类型	说明
`DeepReadonly<RouteLocation>`	深层只读的当前路由位置对象

详情

默认情况下（global = false），useRoute() 返回的是当前 RouterView 层级对应的路由信息。在嵌套路由场景中，内层 RouterView 中的组件获取到的 route 会代理到当前层级的路由记录，使得 params 和 query 只包含当前层级路由记录的参数。

当 global = true 时，始终返回全局的 router.route 对象，不受 RouterView 层级影响。

示例

tsx

import { useRoute, watch } from 'vitarx-router'

// 监听路由参数变化
export default function UserPage() {
  const route = useRoute()

  watch(
    () => route.params.id,
    (newId, oldId) => {
      console.log(`参数 id 从 #123;oldId} 更新到 #123;newId}`)
    }
  )

  return <div>当前用户 ID：{route.params.id}</div>
}

// 获取全局路由信息
const globalRoute = useRoute(true)

useLink()

创建链接助手，用于处理路由导航、生成链接属性及判断激活状态。RouterLink 组件即基于此函数实现。

类型定义

function useLink<T extends RouteIndex>(options: UseLinkOptions<T>): UseLinkReturn

参数

参数	类型	说明
options	`UseLinkOptions<T>`	链接配置选项

UseLinkOptions

interface UseLinkOptions<T extends RouteIndex = RouteIndex> {
  to: NavTarget<T> | T | string
  replace?: boolean
  viewTransition?: boolean
  exactMatchMode?: 'path' | 'href' | 'hash' | 'query'
}

属性	类型	默认值	说明
to	`NavTarget<T> \| T \| string`	—	必填。导航目标
replace	`boolean`	`false`	是否使用 `router.replace()`
viewTransition	`boolean`	`false`	是否使用 View Transition API
exactMatchMode	`'path' \| 'href' \| 'hash' \| 'query'`	`'path'`	精确匹配模式

返回值

类型	说明
`UseLinkReturn`	链接助手对象

UseLinkReturn

interface UseLinkReturn {
  href: Computed<string>
  route: Computed<RouteLocation | null>
  isActive: Computed<boolean>
  isExactActive: Computed<boolean>
  navigate: (e?: MouseEvent) => Promise<NavigateResult>
}

属性	类型	说明
href	`Computed<string>`	链接的 `href` 属性值
route	`Computed<RouteLocation \| null>`	匹配的路由信息，未匹配时为 `null`
isActive	`Computed<boolean>`	是否部分匹配当前路由（前缀匹配）
isExactActive	`Computed<boolean>`	是否精确匹配当前路由
navigate	`(e?: MouseEvent) => Promise<NavigateResult>`	执行导航的函数

示例

import { useLink } from 'vitarx-router'

const { href, isActive, isExactActive, navigate } = useLink({
  to: '/user/123',
  exactMatchMode: 'path'
})

// 获取链接地址
console.log(href.value)

// 判断激活状态
if (isActive.value) {
  console.log('当前路径匹配')
}

// 执行导航
await navigate()

onBeforeRouteLeave()

注册组件内路由离开守卫。当当前路由即将离开时触发，守卫会在组件作用域销毁时自动清理。

类型定义

function onBeforeRouteLeave(guard: RouteLeaveGuard): void

参数

参数	类型	说明
guard	`RouteLeaveGuard`	路由离开守卫函数

详情

守卫函数签名：

type RouteLeaveGuard = (
  to: RouteLocation,
  from: RouteLocation
) => boolean | void | Promise<boolean | void>

返回 false：阻止导航
返回 void 或 true：放行导航
返回 Promise：异步处理

守卫会注册到当前 RouterView 层级对应的路由记录上，当组件作用域销毁时自动移除。

示例

tsx

import { onBeforeRouteLeave } from 'vitarx-router'

export default function EditForm() {
  const hasUnsavedChanges = true

  onBeforeRouteLeave((to, from) => {
    if (hasUnsavedChanges) {
      const answer = window.confirm('有未保存的更改，确定要离开吗？')
      if (!answer) return false
    }
  })

  return <form>...</form>
}

onBeforeRouteUpdate()

注册组件内路由更新回调。当同一组件对应的路由参数发生变化（但组件未卸载）时触发，回调会在组件作用域销毁时自动清理。

类型定义

function onBeforeRouteUpdate(cb: RouteUpdateCallback): void

参数

参数	类型	说明
cb	`RouteUpdateCallback`	路由更新回调函数

详情

回调函数签名：

type RouteUpdateCallback = (to: RouteLocation, from: RouteLocation) => void

典型场景：当路由从 /user/1 导航到 /user/2 时，UserComponent 不会卸载重建，但参数发生了变化。此时可以通过 onBeforeRouteUpdate() 监听参数变化并执行相应逻辑（如重新获取数据）。

示例

tsx

import { onBeforeRouteUpdate } from 'vitarx-router'

export default function UserPage() {
  onBeforeRouteUpdate((to, from) => {
    console.log('参数 id 从', from.params.id, '更新到', to.params.id)
    // 重新获取用户数据
    fetchUser(to.params.id)
  })

  return <div>用户详情</div>
}

参考：组件内守卫