Vue Router 中高频 API

[TOC]

<h1>Vue Router 中常使用的高频 API</h1>

## resolve

resolve 是 useRoute() 下的一个函数方法，下面将直接使用 `router` 作为 resolve 调用的对象实例

**作用：**解析路由，返回路由对象，但不执行页面跳转。

它会根据你传入的路由名称 / 路径 / 参数，计算出完整的：

+ href：完整 URL（可直接用于 `<a href>`）
+ path：路由路径
+ params/query：路由参数
+ 路由匹配信息等

**语法：**

```js
const routeInfo = this.$router.resolve({
  name: 'Detail',
  params: { id: 123 },
  query: { tab: 'info' }
})

// 返回结果
routeInfo.href // 完整链接：/detail/123?tab=info
routeInfo.path // 路径：/detail/123
routeInfo.params // { id: 123 }
```

**使用场景：**

所有「需要路由地址，但不想立刻跳转」的场景：

+ 生成外链、下载链接、二维码链接
+ 新标签页打开路由（window.open）
+ 动态拼接 `<a href>`
+ 获取完整 URL 用于分享

示例：新标签页打开

```js
const { href } = this.$router.resolve({ name: 'User', params: { id: 5 } })
window.open(href, '_blank')
```

> Tips：router.resolve 只计算、不跳转，生成路由地址信息（路径、URL、参数等），纯计算工具。

## push

**作用：**编程式导航，跳转到指定路由，会：

+ 修改浏览器地址栏
+ 切换页面组件
+ 添加一条历史记录（可返回）

**语法：**

```js
// 跳转到详情页
this.$router.push('/detail/123')

// 或带参数写法
this.$router.push({
  name: 'Detail',
  params: { id: 123 }
})
```

**router.push返回：**router.push 和所有其他导航方法都会返回一个 Promise，让我们可以等到导航完成后才知道是成功还是失败。

**使用场景：**所有「点击按钮、触发事件后需要页面跳转」的普通场景

+ 点击按钮跳转到详情页
+ 表单提交后跳转
+ 登录成功后跳转首页
+ 菜单点击切换页面

> **Tips：**
+ router.push 直接跳转页面，修改浏览器地址栏并渲染对应组件，导航工具。
+ 想要导航到不同的 URL，可以使用 router.push 方法。这个方法会向 history 栈添加一个新的记录，所以，当用户点击浏览器后退按钮时，会回到之前的 URL。

### push 参数介绍

该方法的参数可以是一个字符串路径，或者一个描述地址的对象例如：

```js
// 字符串路径
router.push('/users/eduardo')

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

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

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

// 带 hash，结果是 /about#team
router.push({ path: '/about', hash: '#team' })
```

注意：如果提供了 path，params 会被忽略，上述例子中的 query 并不属于这种情况。取而代之的是下面例子的做法，你需要提供路由的 name 或手写完整的带有参数的 path ：

```js
const username = 'eduardo'
// 我们可以手动建立 url，但我们必须自己处理编码
router.push(`/user/${username}`) // -> /user/eduardo
// 同样
router.push({ path: `/user/${username}` }) // -> /user/eduardo
// 如果可能的话，使用 `name` 和 `params` 从自动 URL 编码中获益
router.push({ name: 'user', params: { username } }) // -> /user/eduardo
// `params` 不能与 `path` 一起使用
router.push({ path: '/user', params: { username } }) // -> /user
```

当指定 params 时，可提供 string 或 number 参数（或者对于可重复的参数可提供一个数组）。任何其他类型（如对象、布尔等）都将被自动字符串化。对于可选参数，你可以提供一个空字符串（""）或 null 来移除它

## replace

replace 是 `router` 实例上的核心路由跳转方法，Vue3 中可通过 `useRouter()` 获取，Vue2 中通过 `this.$router` 调用

**作用：**路由跳转**替换当前页面历史记录**，不会向浏览器历史栈中新增一条记录，**执行页面跳转**，且返回时无法回到跳转前的页面。

它会根据传入的路由名称/路径/参数，跳转到目标路由，并**替换当前历史记录**：

+ 无新增历史记录，浏览器返回键会跳过当前页
+ 支持 path/name 两种跳转方式
+ 支持 params/query 传参
+ 跳转后页面刷新，组件重新渲染

**语法：**
```js
// 1. 命名路由跳转（推荐，更稳定）
this.$router.replace({
  name: 'Detail',
  params: { id: 123 }, // 路径参数
  query: { tab: 'info' } // 查询参数
})

// 2. 路径字符串直接跳转
this.$router.replace('/detail/123?tab=info')

// 3. 路径对象跳转
this.$router.replace({
  path: '/detail/123',
  query: { tab: 'info' }
})
```

**使用场景：**需要**禁止用户返回上一页**、**替换当前页面**的场景：

+ 登录成功后替换登录页（禁止回退到登录页）
+ 表单提交成功后替换提交页（禁止重复提交）
+ 中间页/引导页跳转后不保留历史记录
+ 避免重复路由、无效回退的业务场景

示例：登录成功跳转，禁止回退到登录页
```js
// 登录接口请求成功后
loginApi().then(res => {
  // 替换路由，用户点击返回会直接退出到登录前的页面
  this.$router.replace({ name: 'Home' })
})
```

> Tips：router.replace **会执行跳转**，核心特性是**替换历史记录**，和 router.push（新增历史记录）是最常用的两种跳转方式。

## resolve 与 push 与 replace 对比