uni-app——路由API

• 路由API

  路由概要

  在 uni-app 开发过程中，路由是实现页面间导航跳转的关键机制。通过路由 API，开发者可在 JavaScript 文件内轻松执行页面跳转操作，进而为用户打造流畅的交互流程。uni-app 的navigator组件设有open - type属性，其具备 5 种取值，每种取值分别对应一种独特的跳转方式，且每种跳转方式均关联一个特定的跳转 API 。具体如下：

  1. navigator - uni.navigateTo(OBJECT)
  • • 采用这种方式进行跳转时，当前页面会被保留，同时跳转到应用内的目标页面。若后续需要返回，可借助uni.navigateBack实现回退至先前页面。
  • • OBJECT 参数详情：
  • • • url（必填）：此为要跳转的应用内非tabBar页面路径，路径起始需加上/，例如/pages/productDetail/productDetail。
  • • • delta：该参数用于明确返回的页面层数。若delta的值超出当前已打开页面的数量，最终将跳转回应用首页。例如，当前页面栈中有四个页面，若设置delta为 5，页面将直接跳转回首页。
  • • • animationType：用于设定窗口切换时显示的动画效果，常见效果包含pop - in（淡入）、pop - out（淡出）等，不过不同平台所支持的动画效果可能存在细微差别。
  • • • animationDuration：用于指定窗口动画的持续时长，单位为毫秒。假设设置为500，则动画将持续 500 毫秒。
  • • • events：这是一个页面间通信接口，借助它可监听被打开页面向当前页面发送的数据。举例来说，在页面 A 通过uni.navigateTo跳转到页面 B 后，页面 B 可通过this.$emit('dataTransfer', {msg: 'Hello'})发送数据，页面 A 在events中监听dataTransfer事件即可接收数据。
  • • • success、fail、complete：这三个均为回调函数。success会在页面成功跳转后触发；fail在跳转过程中遭遇错误（比如路径错误）时触发；complete无论跳转操作成功与否，只要操作结束就会执行。
  • • 示例代码：

  // 从首页跳转到详情页
  uni.navigateTo({
      url: '/pages/productDetail/productDetail?id=123&category=electronics',
      animationType: 'pop-in',
      animationDuration: 300,
      events: {
          receiveData (data) {
              console.log('从详情页接收到的数据', data);
          }
      },
      success: function () {
          console.log('页面跳转成功');
      },
      fail: function (err) {
          console.log('页面跳转失败', err);
      },
      complete: function () {
          console.log('跳转操作结束');
      }
  });
  

  1. redirect - uni.redirectTo(OBJECT)
  • • 该跳转方式会关闭当前页面，然后跳转到应用内的目标页面。与uni.navigateTo不同之处在于，它不会将当前页面保留在页面栈中。
  • • OBJECT 参数特点：与uni.navigateTo的参数大致相似。
  • • • url（必填）：同样是跳转的应用内非tabBar页面路径。
  • • • delta：尽管此参数存在，但在uni.redirectTo中基本不会用到，因为它是关闭当前页面进行跳转，不存在返回页面数的概念。
  • • • animationType、animationDuration、success、fail、complete：这些参数的作用与uni.navigateTo中的对应参数一致。
  • • 示例代码：

  // 从登录页面重定向到首页
  uni.redirectTo({
      url: '/pages/home/home',
      animationType: 'pop-out',
      animationDuration: 300,
      success: function () {
          console.log('页面重定向成功');
      },
      fail: function (err) {
          console.log('页面重定向失败', err);
      },
      complete: function () {
          console.log('重定向操作结束');
      }
  });
  

  1. switchTab - uni.switchTab(OBJECT)
  • • 此 API 主要用于跳转到tabBar页面，同时关闭其他所有非tabBar页面，在实现底部导航栏页面切换的场景中应用广泛。
  • • OBJECT 参数要点：
  • • • url（必填）：所跳转的tabBar页面路径，此路径必须是在pages.json文件中被注册为tabBar的页面。例如/pages/home/home，其中home页面属于tabBar的一部分。
  • • • success、fail、complete：回调函数功能与上述其他跳转 API 相同。
  • • 示例代码：

  // 从某个非tabBar页面切换到“我的”tabBar页面
  uni.switchTab({
      url: '/pages/my/my',
      success: function () {
          console.log('成功切换到tabBar页面');
      },
      fail: function (err) {
          console.log('切换tabBar页面失败', err);
      },
      complete: function () {
          console.log('切换tabBar页面操作结束');
      }
  });
  

  1. reLaunch - uni.reLaunch(OBJECT)
  • • uni.reLaunch会关闭应用内所有页面，随后打开指定的某一页面。该 API 常用于需要重置页面栈的情况，比如从一个复杂的业务流程页面直接跳转到应用首页。
  • • OBJECT 参数说明：
  • • • url（必填）：即要打开的应用内页面路径。
  • • • success、fail、complete：回调函数的功能与其他跳转 API 保持一致。
  • • 示例代码：

  // 从订单确认页面重新启动并打开首页
  uni.reLaunch({
      url: '/pages/home/home',
      success: function () {
          console.log('成功重新启动并打开页面');
      },
      fail: function (err) {
          console.log('重新启动并打开页面失败', err);
      },
      complete: function () {
          console.log('重新启动并打开页面操作结束');
      }
  });
  

  1. navigateBack - uni.navigateBack(OBJECT)
  • • 该 API 用于关闭当前页面，返回上一级页面或者返回多级页面。
  • • OBJECT 参数细节：
  • • • delta：用于指定返回的页面数，默认值为 1。若设置delta为 3，则会返回上三级页面。若delta的值大于当前页面栈中的页面总数，页面将直接返回首页。
  • • • success、fail、complete：这些回调函数会在返回操作完成后触发相应的反馈。
  • • 示例代码：

  // 从详情页返回上一级页面
  uni.navigateBack({
      delta: 1,
      success: function () {
          console.log('成功返回上一级页面');
      },
      fail: function (err) {
          console.log('返回上一级页面失败', err);
      },
      complete: function () {
          console.log('返回操作结束');
      }
  });
  

  值得注意的是，uni.navigateTo(OBJECT)的success回调函数参数res具有eventChannel属性，其类型为EventChannel，主要用于与被打开的页面进行通信。比如，在目标页面中可通过this.$eventChannel.emit('message', {info: 'Some data'})向源页面发送数据，源页面则在success回调的res.eventChannel中监听message事件来接收数据。

  数据传递

  在 uni-app 的路由跳转中，uni.navigateTo、uni.redirectTo、uni.reLaunch这三个路由 API 的url参数均支持携带数据。传递参数的格式为"path?key=value&key2=value2"。例如，/pages/detail/detail?id = 123&name = productName。

  uni-app 在接收路由参数的方式上与 Vue 有所不同：

  • 在 uni-app 中，接收路由参数的操作是在页面的onLoad生命周期函数内完成的。

  • onLoad函数接收的参数为一个Object对象，该对象会自动将上级页面传递过来的参数进行序列化处理。例如，若上级页面通过uni.navigateTo({url: '/pages/detail/detail?id = 123&name = productName'})传递参数，在detail页面的onLoad函数中，可通过options => {console.log([options.id](http://options.id)); console.log(options.name);}来获取传递的参数。

  • • 示例代码（接收参数）：

  export default {
      data() {
          return {
              productId: '',
              productName: ''
          };
      },
      onLoad(options) {
          this.productId = options.id;
          this.productName = options.name;
          console.log('产品ID:', this.productId);
          console.log('产品名称:', this.productName);
      }
  };