编程式导航

除了使用 <RouterLink> 组件进行声明式导航外，vitarx-router 还提供了一套编程式导航 API，允许你在任何地方通过代码触发路由跳转。

router.push()

router.push() 是最常用的导航方法，它会在浏览器历史记录中添加一条新记录，用户可以通过浏览器的后退按钮返回之前的页面。

该方法返回一个 Promise<NavigateResult>，你可以通过它判断导航是否成功。

字符串路径

最简单的用法是直接传入路径字符串：

router.push('/user/123')

路由名称

你也可以通过路由名称（字符串或 Symbol）进行导航：

// 字符串名称
router.push('user')

// Symbol 名称
router.push(Symbol('user'))

使用路由名称导航时，vitarx-router 会自动查找对应的路由配置并解析路径。如果路由需要参数但未提供，导航可能会失败。

NavOptions 对象

当你需要携带参数、查询字符串或哈希时，可以传入一个导航选项对象：

router.push({
  index: '/user',
  params: { id: '123' },
  query: { tab: 'info' },
  hash: '#section'
})

上述调用将导航到 /user/123?tab=info#section。

params 中的参数必须与路由配置中的动态路径参数匹配，否则参数将被忽略。

router.replace()

router.replace() 的行为与 router.push() 完全相同，唯一的区别是它不会在浏览器历史记录中添加新记录，而是替换当前的记录。

router.replace('/login')

这在登录后跳转首页、删除操作后替换当前页等场景下非常有用——用户不希望通过后退按钮回到已失效的页面。

router.go()

router.go() 用于在浏览器历史记录中前进或后退指定步数：

// 前进 1 步（等同于浏览器的前进按钮）
router.go(1)

// 后退 1 步（等同于浏览器的后退按钮）
router.go(-1)

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

// 传入 0 不会产生任何效果
router.go(0)

如果指定的步数超出了历史记录的范围，导航将静默失败，不会抛出错误。

router.back() / router.forward()

这两个方法是 router.go() 的快捷方式：

// 等同于 router.go(-1)
router.back()

// 等同于 router.go(1)
router.forward()

完整示例

import { createRouter } from 'vitarx-router'

const router = createRouter({
  mode: 'hash',
  routes: [
    { path: '/', component: Home },
    { path: '/user/{id}', index: 'user', component: User },
    { path: '/login', component: Login }
  ]
})

// 字符串路径导航
await router.push('/user/123')

// 带参数的对象导航
const result = await router.push({
  index: 'user',
  params: { id: '456' },
  query: { tab: 'profile' }
})

if (result.state === 1) {
  console.log('导航成功')
}

// 替换当前历史记录
router.replace('/login')

// 浏览器后退
router.back()

// 浏览器前进
router.forward()

RouterLink 组件 — 了解如何使用声明式导航组件创建路由链接。