路由跳转 API 封装 - router

这个封装集合是为了确保项目代码的一致性和规范性而设计的，旨在简化路由跳转 API、路由参数处理。

以下是包含的方法列表，强烈建议在项目中使用它们，而非使用 uni.xxx 或 wx.xxx ：

• router.push 跳转页面
• router.replace 重定向页面
• router.relaunch 关闭所有页面并打开页面
• router.tab 切换到 tab 页
• router.back 返回页面
• router.getPageDelta 获取某个页面在页面栈中的倒数第几层
• router.receiveTabPageOptions 获取切换到 tab 页时的页面参数
• router.receivePrevPageData 获取上一个页面发送的数据
• router.afterEach 后置路由守卫
• router.setDefault404Page 设置默认 404 页面
• router.stringifyQuery 将参数对象格式化成字符串
• router.parseQuery 将参数字符串格式化成对象
• router.parseUrl 解析 URL 成路径和参数对象两个部分
• router.resolveUrl 将路径和参数对象两个部分合并成完整的 URL

基本用法

TIP

这些跳转方法会自动处理诸如「页面不存在」以及「目标页面是否为 tab 页」等问题，从而触发自动回退方案。

当使用 router 跳转方法时，router 内部会自动对页面参数进行编码处理，因此不需要再手动 encode/decodeURIComponent。

push

import {router} from '@ifanrx/uni-mp'

router.push('/pages/index/index')

router.push(
  '/pages/index/index?offset=1',
  {limit: 2},
  {
    success: res => {
      // do something
    },
    fail: err => {
      // do something
    },
  }
)

// 对于 success 和 fail，更推荐使用 .then 和 .catch
router
  .push('/pages/index/index?offset=1', {limit: 2})
  .then(res => {
    // do something
  })
  .catch(err => {
    // do something
  })

replace

import {router} from '@ifanrx/uni-mp'

router.replace('/pages/index/index')

router.replace('/pages/index/index?offset=1', {limit: 2})

relaunch

import {router} from '@ifanrx/uni-mp'

router.relaunch('/pages/index/index')

router.relaunch('/pages/index/index?offset=1', {limit: 2})

tab

切换到 tab 页的情况有些不同，因为在这种情况下无法直接传递页面参数。因此， router 内部进行了一些处理，将参数保存到 globalData 中。此外，还提供了一个 receiveTabPageOptions 函数，方便在 tab 页中获取参数：

other-page.vue

import {router} from '@ifanrx/uni-mp'

router.tab('/pages/index/index')

router.tab('/pages/index/index?offset=1', {limit: 2})

index.vue

import {router} from '@ifanrx/uni-mp'

// 获取页面参数
const options = router.receiveTabPageOptions()

INFO

receiveTabPageOptions 调用后会清空现有数据，也即多次调用只有第一次有值，因此请在调用时自行保存数据。

back

import {router} from '@ifanrx/uni-mp'

router.back()
router.back(2)

getPageDelta

获取某个页面在页面栈中的倒数第几层，需要注意路径和参数要完全一致

import {router} from '@ifanrx/uni-mp'

const delta = router.getPageDelta('/pages/index/index?id=1')

如果你需要用到这个方法，那可以看一下《跳转前先尝试返回页面》。

afterEach

后置路由守卫，参考 Vue —— 全局后置钩子，可以方便地监听路由跳转：

App.vue

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

setDefault404Page

当跳转页面不存在时，会跳转到 404 页面，你可以通过 setDefault404Page 方法设置默认的 404 页面：

App.vue

import {router} from '@ifanrx/uni-mp'

router.setDefault404Page('/pages/not-found/index')

参数解析

import {router} from '@ifanrx/uni-mp'

router.stringifyQuery({a: 1}) // a=1
router.stringifyQuery('?id=1&a=2') // {id:1, a:2}
router.parseUrl('/pages/index/index?id=1&a=2') // {url:'/pages/index/index', query:{id:1, a:2}}
const fullURL = router.resolveUrl(url, query)

常见问题

页面传递对象参数

我们知道页面只能接受字符串类型的参数，然而在某些情况下传递对象参数会更加灵活，因此我们支持了这种操作，无论是使用以下哪一个方法进行跳转，你都可以在第三个参数中传入 data 字段：

1. push
2. replace
3. relaunch
4. tab

举个例子，当我们跳转到某个富文本页的时候，我们希望直接把富文本内容传递过去：

router.push(
  '/pages/richtext/index',
  {},
  {
    data: {
      richtext: activity.richtext,
    },
  }
)

然后在目标页面中通过 receivePrevPageData 方法获取该数据：

import {router} from '@ifanrx/uni-mp'

// 获取上一个页面传输的数据
const data = router.receivePrevPageData()

INFO

receivePrevPageData 调用后会清空现有数据，也即多次调用只有第一次有值，因此请在调用时自行保存数据。

跳转前先尝试返回页面

在某些情况下，我们希望在跳转到新页面之前，先检查目标页面是否已经存在于当前的页面栈中。如果存在，则直接返回该页面，避免重复创建页面实例。这种需求可以通过在路由跳转时传入 backIfExist 参数来实现。

// 如果页面栈中已存在 /pages/detail/index?id=2，则返回该页面，否则进行新的页面跳转
router.push(
  '/pages/detail/index',
  {id: 2},
  {
    backIfExist: true,
  }
)

TIP

该功能会比对页面路径及参数，仅在完全匹配时返回已有页面，否则继续完成跳转。

建议合理使用该功能，优化页面跳转流程，避免重复创建同一页面，从而提升性能和体验。

相关文档

• router - API