uni-app 之 页面路由

概述

uni-app 的路由功能用于管理应用中的页面跳转和导航。与传统 Web 开发不同，uni-app 支持多端运行，因此其路由机制针对不同平台进行了优化和适配。

路由配置

pages.json 配置

在 pages.json 文件中配置应用的页面路径和窗口表现：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "详情页"
      }
    }
  ]
}

页面跳转方式

1. navigator 组件跳转

在模板中使用 navigator 组件实现页面跳转：

<navigator url="/pages/detail/detail?id=123" hover-class="navigator-hover">
  跳转到详情页
</navigator>

2. API 编程式跳转

uni.navigateTo()

保留当前页面，跳转到应用内的某个页面：

uni.navigateTo({
  url: "/pages/detail/detail?id=123",
});

uni.redirectTo()

关闭当前页面，跳转到应用内的某个页面：

uni.redirectTo({
  url: "/pages/detail/detail?id=123",
});

uni.switchTab()

跳转到 tabBar 页面：

uni.switchTab({
  url: "/pages/index/index",
});

uni.reLaunch()

关闭所有页面，打开到应用内的某个页面：

uni.reLaunch({
  url: "/pages/index/index",
});

uni.navigateBack()

关闭当前页面，返回上一页面或多级页面：

uni.navigateBack({
  delta: 1,
});

路由传参

URL 参数传递

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

// 接收参数
onLoad(options) {
  console.log(options.id)   // 123
  console.log(options.name) // test
}

对象参数传递

// 使用 encodeURIComponent 传递复杂对象
const params = { id: 123, data: { name: 'test' } }
uni.navigateTo({
  url: `/pages/detail/detail?params=${encodeURIComponent(JSON.stringify(params))}`
})

// 接收参数
onLoad(options) {
  const params = JSON.parse(decodeURIComponent(options.params))
}

路由生命周期

页面生命周期函数

export default {
  onLoad(options) {
    // 页面加载时触发
  },
  onShow() {
    // 页面显示时触发
  },
  onReady() {
    // 页面初次渲染完成时触发
  },
  onHide() {
    // 页面隐藏时触发
  },
  onUnload() {
    // 页面卸载时触发
  },
};

页面栈管理

获取当前页面栈：

// 获取当前页面栈实例
const pages = getCurrentPages();
const currentPage = pages[pages.length - 1];

注意事项

1. 页面栈限制：小程序端页面栈最多 10 层
2. tabBar 页面 ：只能使用 uni.switchTab() 跳转
3. 返回按钮：非 tabBar 页面左上角有返回按钮
4. 参数长度限制：URL 参数过长可能导致截断
5. 跨端兼容：不同平台路由行为可能存在差异

常见问题解决

页面传参丢失

确保参数正确编码：

// 错误示例
url: "/pages/detail/detail?data=" + JSON.stringify(obj);

// 正确示例
url: `/pages/detail/detail?data=${encodeURIComponent(JSON.stringify(obj))}`;

页面返回不刷新

在 onShow 生命周期中处理数据更新逻辑：

export default {
  onShow() {
    // 每次页面显示时重新加载数据
    this.loadData();
  },
};