知识库

Appearance

uni-app 路由 ​

路由概述 ​

uni-app 路由是指在应用中实现页面之间的跳转和导航功能，类似于 Web 应用中的路由系统。uni-app 提供了一套完整的路由 API，支持页面跳转、参数传递、导航栏控制等功能。

路由配置 ​

页面配置 ​

在 uni-app 中，页面需要在 pages.json 文件中进行配置，包括页面路径、导航栏标题、tabBar 等信息。

示例配置：

json
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "详情页"
      }
    }
  ],
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-active.png"
      },
      {
        "pagePath": "pages/mine/mine",
        "text": "我的",
        "iconPath": "static/tab-mine.png",
        "selectedIconPath": "static/tab-mine-active.png"
      }
    ]
  }
}

路由参数 ​

页面跳转时可以传递参数，参数会被添加到 URL 中，通过 onLoad 生命周期钩子的参数获取。

示例：

javascript
// 跳转到详情页并传递参数
uni.navigateTo({
  url: '/pages/detail/detail?id=123&name=测试'
});

// 在详情页获取参数
onLoad(options) {
  console.log(options.id); // 输出：123
  console.log(options.name); // 输出：测试
}

路由 API ​

uni.navigateTo ​

  • 功能：保留当前页面，跳转到应用内的某个页面
  • 参数：
    • url：跳转地址，支持相对路径和绝对路径
    • animationType：动画类型，支持 "slide-in-right"、"pop-in" 等
    • animationDuration：动画时长，单位为毫秒
  • 应用场景：普通页面跳转，如从列表页跳转到详情页
  • 注意：页面栈最多只能有 10 层

示例：

javascript
uni.navigateTo({
  url: '/pages/detail/detail?id=123',
  animationType: 'slide-in-right',
  animationDuration: 300
});

uni.redirectTo ​

  • 功能：关闭当前页面，跳转到应用内的某个页面
  • 参数：
    • url：跳转地址
    • animationType：动画类型
    • animationDuration：动画时长
  • 应用场景：登录成功后跳转，支付成功后跳转
  • 注意：不支持跳转到 tabBar 页面

示例：

javascript
uni.redirectTo({
  url: '/pages/home/home'
});

uni.reLaunch ​

  • 功能：关闭所有页面，跳转到应用内的某个页面
  • 参数：
    • url：跳转地址
  • 应用场景：退出登录后跳转，应用重置
  • 注意：支持跳转到 tabBar 页面

示例：

javascript
uni.reLaunch({
  url: '/pages/login/login'
});

uni.switchTab ​

  • 功能：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面
  • 参数：
    • url：跳转地址，必须是 tabBar 页面
  • 应用场景：切换底部 tab

示例：

javascript
uni.switchTab({
  url: '/pages/index/index'
});

uni.navigateBack ​

  • 功能：关闭当前页面，返回上一页面或多级页面
  • 参数：
    • delta：返回的页面数，默认值为 1
  • 应用场景：返回上一页，返回多级页面

示例：

javascript
// 返回上一页
uni.navigateBack({
  delta: 1
});

// 返回上两页
uni.navigateBack({
  delta: 2
});

导航栏控制 ​

导航栏配置 ​

在 pages.json 文件中可以配置页面的导航栏，包括标题、背景色、文字颜色等。

示例配置：

json
{
  "path": "pages/index/index",
  "style": {
    "navigationBarTitleText": "首页",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationStyle": "default"
  }
}

动态修改导航栏 ​

可以通过 API 动态修改导航栏的标题、背景色等。

示例：

javascript
// 修改导航栏标题
uni.setNavigationBarTitle({
  title: '新标题'
});

// 修改导航栏背景色和文字颜色
uni.setNavigationBarColor({
  frontColor: '#ffffff',
  backgroundColor: '#007AFF'
});

页面栈管理 ​

获取页面栈 ​

可以通过 getCurrentPages() 方法获取当前页面栈的信息。

示例：

javascript
const pages = getCurrentPages();
console.log(pages.length); // 页面栈长度
console.log(pages[pages.length - 1]); // 当前页面信息

页面栈限制 ​

  • 页面栈最多只能有 10 层
  • 超过限制时，会自动关闭最早打开的页面
  • 建议合理管理页面栈，避免页面栈过深

路由守卫 ​

uni-app 提供了全局的路由守卫功能，可以在页面跳转前进行拦截和处理。

全局前置守卫 ​

javascript
// 在 App.vue 中配置
uni.addInterceptor('navigateTo', {
  invoke(args) {
    // 跳转前处理
    console.log('navigateTo', args);
  },
  success(args) {
    // 跳转成功处理
  },
  fail(err) {
    // 跳转失败处理
  },
  complete() {
    // 跳转完成处理
  }
});

页面级守卫 ​

可以在页面的生命周期钩子中实现页面级的路由守卫。

示例：

javascript
// 在页面的 onLoad 中进行权限检查
onLoad(options) {
  // 检查是否登录
  const token = uni.getStorageSync('token');
  if (!token) {
    uni.redirectTo({
      url: '/pages/login/login'
    });
    return;
  }
  // 正常加载页面
}

路由参数传递 ​

URL 参数传递 ​

通过 URL 传递参数，适用于简单的参数传递。

示例：

javascript
// 传递参数
uni.navigateTo({
  url: '/pages/detail/detail?id=123&name=测试'
});

// 获取参数
onLoad(options) {
  console.log(options.id); // 输出：123
  console.log(options.name); // 输出：测试
}

全局数据传递 ​

通过全局变量或状态管理传递参数，适用于复杂的参数传递。

示例：

javascript
// 在 App.vue 中定义全局变量
App({
  globalData: {
    userInfo: null
  }
});

// 存储数据
getApp().globalData.userInfo = { name: '张三', age: 18 };

// 获取数据
const userInfo = getApp().globalData.userInfo;

事件总线传递 ​

通过事件总线传递参数，适用于跨页面通信。

示例：

javascript
// 定义事件总线
const eventBus = {
  events: {},
  on(name, callback) {
    if (!this.events[name]) {
      this.events[name] = [];
    }
    this.events[name].push(callback);
  },
  emit(name, data) {
    if (this.events[name]) {
      this.events[name].forEach(callback => {
        callback(data);
      });
    }
  }
};

// 监听事件
eventBus.on('userInfoChange', (data) => {
  console.log('用户信息变化：', data);
});

// 触发事件
eventBus.emit('userInfoChange', { name: '张三', age: 18 });

路由动画 ​

内置动画 ​

uni-app 提供了内置的路由动画，包括：

  • slide-in-right：从右侧滑入
  • slide-in-left：从左侧滑入
  • slide-in-top：从顶部滑入
  • slide-in-bottom：从底部滑入
  • pop-in：弹出
  • fade-in：淡入

示例：

javascript
uni.navigateTo({
  url: '/pages/detail/detail',
  animationType: 'slide-in-right',
  animationDuration: 300
});

自定义动画 ​

可以通过 CSS 自定义路由动画。

示例：

css
/* 自定义进入动画 */
.page-enter-active {
  animation: page-enter 0.3s ease-out;
}

@keyframes page-enter {
  from {
    transform: translateX(100%);
    opacity: 0;
  }
  to {
    transform: translateX(0);
    opacity: 1;
  }
}

/* 自定义离开动画 */
.page-leave-active {
  animation: page-leave 0.3s ease-in;
}

@keyframes page-leave {
  from {
    transform: translateX(0);
    opacity: 1;
  }
  to {
    transform: translateX(-100%);
    opacity: 0;
  }
}

路由最佳实践 ​

合理使用路由 API ​

  • 普通页面跳转使用 uni.navigateTo
  • 登录成功后跳转使用 uni.redirectTo
  • 退出登录后跳转使用 uni.reLaunch
  • 切换底部 tab 使用 uni.switchTab

页面栈管理 ​

  • 避免页面栈过深，最多 10 层
  • 合理使用 uni.redirectTo 和 uni.reLaunch 清理页面栈
  • 使用 uni.navigateBack 返回上一页

参数传递 ​

  • 简单参数使用 URL 传递
  • 复杂参数使用全局数据或状态管理传递
  • 跨页面通信使用事件总线

导航栏控制 ​

  • 在 pages.json 中统一配置导航栏
  • 动态修改导航栏使用 API
  • 自定义导航栏使用 navigationStyle: "custom"

路由守卫 ​

  • 使用全局前置守卫进行权限检查
  • 使用页面级守卫进行页面特定的处理
  • 合理使用路由守卫，避免影响用户体验

常见问题 ​

页面跳转失败 ​

  • 检查页面路径是否正确
  • 检查页面是否在 pages.json 中配置
  • 检查页面栈是否超过 10 层

参数传递失败 ​

  • 检查参数格式是否正确
  • 检查参数是否包含特殊字符
  • 检查参数长度是否超过限制

导航栏不显示 ​

  • 检查 pages.json 中的导航栏配置
  • 检查是否设置了 navigationStyle: "custom"
  • 检查是否动态修改了导航栏

路由动画不生效 ​

  • 检查动画类型是否正确
  • 检查动画时长是否合理
  • 检查是否使用了自定义动画

总结 ​

uni-app 路由系统提供了完整的页面跳转和导航功能，支持多种跳转方式、参数传递、导航栏控制等。合理使用路由 API，可以提高应用的用户体验，实现流畅的页面切换效果。

基于 VitePress 的本地知识库

Copyright © 2026