Router 实例

Router 实例是 vitarx-router 的核心对象，提供了路由导航、历史记录管理、守卫注册、动态路由操作等能力。通过 createRouter()、createWebRouter() 或 createMemoryRouter() 创建。

push()

编程式导航到新的路由页面，会在历史记录中添加一条新记录。

类型定义

ts
push<T extends RouteIndex>(target: T | NavOptions<T> | RouteLocation): Promise<NavigateResult>

参数

参数类型说明
targetT | NavOptions<T> | RouteLocation导航目标。可以是路由路径字符串、路由名称、NavOptions 对象或 RouteLocation 对象

返回值

类型说明
Promise<NavigateResult>导航结果对象，包含导航状态和相关信息

详见 NavigateResult

示例

ts
// 通过路径导航
await router.push('/users')

// 通过路径 + 查询参数
await router.push({ index: '/users', query: { page: '1' } })

// 通过路由名称导航
await router.push('userDetail')

// 通过名称 + 动态参数
await router.push({ index: 'userDetail', params: { id: '123' } })

// 带 hash 导航
await router.push({ index: '/about', hash: '#section' })

replace()

替换当前路由页面，不会在历史记录中添加新记录，而是替换当前记录。

类型定义

ts
replace<T extends RouteIndex>(target: T | NavOptions<T> | RouteLocation): Promise<NavigateResult>

参数

参数类型说明
targetT | NavOptions<T> | RouteLocation导航目标，与 push() 相同

返回值

类型说明
Promise<NavigateResult>导航结果对象

详见 NavigateResult

详情

replace() 的行为与 push() 类似，区别在于它不会向历史记录栈中添加新条目，而是替换当前条目。常用于重定向场景或"登录后跳转"等不需要回退的情况。

示例

ts
// 替换当前路由
await router.replace('/login')

// 通过名称替换
await router.replace({ index: 'home' })

go()

在历史记录中前进或后退指定步数。

类型定义

ts
go(delta: number): void

参数

参数类型说明
deltanumber跳转步数。正数前进，负数后退，0 无效果

示例

ts
// 后退一步
router.go(-1)

// 前进两步
router.go(2)

// 无效果
router.go(0)

back()

后退到上一个历史记录，等价于 go(-1)。

类型定义

ts
back(): void

示例

ts
router.back()

forward()

前进到下一个历史记录，等价于 go(1)。

类型定义

ts
forward(): void

示例

ts
router.forward()

beforeEach()

注册全局前置守卫。当路由匹配成功后、导航确认前执行。守卫可以拦截导航、重定向或放行。

类型定义

ts
beforeEach(guard: NavigationGuard): () => void

参数

参数类型说明
guardNavigationGuard前置守卫函数。返回 false 拦截导航，返回 NavTarget 重定向，返回 void 或 true 放行

详情

守卫函数签名：

ts
type NavigationGuard = (this: Router, to: RouteLocation, from: RouteLocation | null) => GuardResult
  • to：目标路由位置
  • from：来源路由位置（首次导航时为 null）
  • 返回 false：阻止导航
  • 返回 NavTarget 或 RouteIndex：重定向到新目标
  • 返回 void 或 true：放行导航

多次调用 beforeEach() 会注册多个守卫，按注册顺序依次执行。

示例

ts
router.beforeEach((to, from) => {
  if (to.path.startsWith('/admin') && !isAuthenticated()) {
    return { index: '/login' } // 重定向到登录页
  }
  // 放行
})

// 异步守卫
router.beforeEach(async (to, from) => {
  await checkAuth()
})

afterEach()

注册全局后置钩子。在导航成功结束后执行，无法影响导航结果。

类型定义

ts
afterEach(hook: AfterCallback): () => void

参数

参数类型说明
hookAfterCallback后置钩子函数

详情

钩子函数签名：

ts
type AfterCallback = (this: Router, to: RouteLocation, from: RouteLocation) => void

后置钩子不接受返回值，仅用于执行副作用（如日志记录、页面统计等）。

示例

ts
router.afterEach((to, from) => {
  // 记录页面访问
  analytics.trackPageView(to.path)
})

addRoute()

动态添加路由规则到路由表中。

类型定义

ts
addRoute(route: Route, parent?: RouteIndex): void

参数

参数类型说明
routeRoute路由配置对象
parentRouteIndex可选的父路由索引（路径或名称），添加为子路由

示例

ts
// 添加顶级路由
router.addRoute({ path: '/new-page', component: NewPage })

// 添加为子路由
router.addRoute({ path: 'profile', component: Profile }, 'user')

removeRoute()

动态移除路由规则。

类型定义

ts
removeRoute(index: RouteIndex): void

参数

参数类型说明
indexRouteIndex路由索引，可以是路由路径或路由名称

示例

ts
// 通过路径移除
router.removeRoute('/old-page')

// 通过名称移除
router.removeRoute('oldRoute')

hasRoute()

检查指定路由是否存在于路由表中。

类型定义

ts
hasRoute(index: RouteIndex): boolean

参数

参数类型说明
indexRouteIndex路由索引，可以是路由路径或路由名称

返回值

类型说明
boolean路由存在返回 true，否则返回 false

示例

ts
if (router.hasRoute('/admin')) {
  // 路由存在
}

if (router.hasRoute('userDetail')) {
  // 路由存在
}

init()

手动初始化路由器。仅 WebRouter 支持此方法，防止重复初始化。

类型定义

ts
init(): this

返回值

类型说明
this当前路由器实例，支持链式调用

详情

初始化过程会执行以下操作：

  1. 根据当前 URL 执行初始路由替换
  2. 监听 popstate 事件，处理浏览器前进/后退
  3. 监听 hashchange 事件，处理 URL hash 变化

如果路由器已经初始化，再次调用 init() 会直接返回当前实例，不会重复初始化。

示例

ts
const router = createWebRouter({ routes: [...] }, false)
router.beforeEach(guard)
router.init() // 手动初始化

isReady()

等待路由器完成首次导航。如果首次导航已完成，Promise 会立即解析。

类型定义

ts
isReady(): Promise<void>

返回值

类型说明
Promise<void>路由就绪后解析

详情

如果路由器尚未初始化，调用 isReady() 会返回一个被拒绝的 Promise，错误信息为 "Router is not initialized."。

示例

ts
await router.isReady()
// 路由已就绪，可以安全访问 router.route

destroy()

销毁路由器实例，清理所有内部状态和事件监听。

类型定义

ts
destroy(): void

详情

销毁操作会：

  • 重置就绪状态
  • 清空路由表
  • 移除浏览器事件监听（WebRouter 的 popstate 和 hashchange）
  • 清空历史记录（MemoryRouter）

通常仅在单元测试中使用。

示例

ts
// 测试结束后清理
afterEach(() => {
  router.destroy()
})

route

当前路由位置的只读响应式对象。

类型定义

ts
readonly route: DeepReadonly<RouteLocation>

返回值

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

详见 RouteLocation

详情

route 是响应式的，当路由发生变化时会自动更新。可以监听其属性变化来响应路由切换。

示例

ts
// 访问当前路径
console.log(router.route.path)

// 访问路由参数
console.log(router.route.params.id)

// 访问查询参数
console.log(router.route.query.page)

routes

获取所有已注册的路由记录数组。

类型定义

ts
readonly routes: RouteRecord[]

返回值

类型说明
RouteRecord[]路由记录数组

示例

ts
// 遍历所有路由
router.routes.forEach(record => {
  console.log(record.path, record.name)
})

matchRoute()

根据导航目标匹配路由，返回路由位置对象。

类型定义

ts
matchRoute(target: NavTarget, redirectFrom?: RouteLocation): RouteLocation | null

参数

参数类型说明
targetNavTarget导航目标对象
redirectFromRouteLocation可选的重定向来源

返回值

类型说明
RouteLocation | null匹配成功返回路由位置对象，否则返回 null

示例

ts
const location = router.matchRoute({ index: '/user', params: { id: '123' } })
if (location) {
  console.log(location.path, location.params)
}

buildUrl()

根据路径、查询参数和 hash 构建完整的 URL。

类型定义

ts
buildUrl(path: string, query?: URLQuery, hash?: URLHash | ''): `/#123;string}`

参数

参数类型说明
pathstring路由路径
queryURLQuery查询参数，默认为 {}
hashURLHash | ''URL hash，默认为 ''

返回值

类型说明
`/${string}`完整的 URL 路径

示例

ts
const url = router.buildUrl('/user', { id: '123' }, '#profile')
// hash 模式: /#/user?id=123#profile
// path 模式: /user?id=123#profile

waitViewRender()

等待视图渲染完成，包括异步组件解析和 DOM 更新。

类型定义

ts
waitViewRender(navResult?: Promise<NavigateResult>): Promise<void>

参数

参数类型说明
navResultPromise<NavigateResult>可选的导航结果 Promise（由 push()/replace() 返回）

返回值

类型说明
Promise<void>视图渲染完成后解析

示例

ts
// 链式调用（推荐，性能更佳）
await router.waitViewRender(router.push('/foo'))

// 分步调用
await router.push('/foo')
await router.waitViewRender()

// 此时 DOM 已更新
console.log(document.querySelector('#app').innerHTML)

resolveComponents()

解析当前路由匹配到的所有异步组件，确保它们加载完成。

类型定义

ts
resolveComponents(route?: RouteLocation): Promise<void>

参数

参数类型说明
routeRouteLocation可选的路由位置，默认使用当前路由

返回值

类型说明
Promise<void>所有组件加载完成后解析

详情

采用 Promise.allSettled 策略：即使部分组件加载失败，也不会阻断路由导航。组件加载的具体错误应由视图层捕获和处理。

install()

将路由器安装到 Vitarx 应用实例中，使组件可以通过 useRouter() 访问路由器。

类型定义

ts
install(app: App): void

参数

参数类型说明
appAppVitarx 应用实例

示例

ts
import { createApp } from 'vitarx'
import { createRouter } from 'vitarx-router'
import App from './App'

const router = createRouter({ routes: [...] })
const app = createApp(App).use(router)
app.mount('#root')

参考：编程式导航、导航守卫