为什么需要 Router props？

先别急着往下翻，咱们来看一段“经典”代码——没错，就是你在无数项目里见过的那一种：

 复制代码

乍一看挺正常，对吧？但仔细琢磨一下，这里面藏着三个“定时冲击波”：

• 组件强依赖 $route —— 想测它？得先造一个路由对象出来，测试成本瞬间翻倍。
• 复用基本不可能 —— 换个场景，你没有 $route 可不行，组件得跟着路由“绑死”。
• 代码可读性堪忧 —— 数据从哪里来，到哪里去，全凭开发者记忆力，传参链路一片模糊。

而 Router props 的出现，就是来收拾这个烂摊子的——它把路由参数包装成组件标准的 props 注入，组件根本不用关心自己是在路由里还是在测试环境里。干干净净，各司其职。

Vue Router 3（Vue2）中的 props 配置

Vue Router 3.x 在路由声明里新增了 props 字段，一共支持 3 种模式，咱们一个一个看。

布尔模式 —— props: true

简单粗暴，直接把 $route.params 全部映射为组件 props，最常见的使用姿势：

 复制代码// router/index.js
const routes = [
  {
    path: '/user/:id',
    component: User,
    props: true   //  将 params.id 映射为 props.id
  }
]

 复制代码

对象模式 —— props: { ... }

这种模式用来传递静态数据，跟路由参数一毛钱关系没有：

 复制代码{
  path: '/promotion',
  component: Promotion,
  props: { banner: 'summer_sale.jpg' }
}

适用场景： 配置化组件、A/B 测试、功能开关——总之那些不需要从 URL 读取的参数，直接写死就行。

函数模式 —— props: (route) => ({ ... })

最灵活的模式，没有之一。你可以自由组合 params、query 甚至自定义逻辑，想怎么揉就怎么揉：

 复制代码{
  path: '/search',
  component: SearchResult,
  props: (route) => ({
    keyword: route.query.q,
    page: Number(route.query.page) || 1,
    from: 'search'           // 可注入静态数据
  })
}

 复制代码

Vue Router 4（Vue3）中的 props 配置

先说个好消息：Vue Router 4 的 props API 与 Vue Router 3 完全兼容，零迁移成本。下面的示例用 Composition API 演示，但实际上 Options API 也照样能用。

三种模式示例（Vue3 Composition API）

 复制代码import { createRouter, createWebHistory } from 'vue-router'const routes = [
  // 布尔模式
  {
    path: '/user/:id',
    component: () => import('@/views/User.vue'),
    props: true
  },
  // 对象模式
  {
    path: '/about',
    component: () => import('@/views/About.vue'),
    props: { title: '关于我们' }
  },
  // 函数模式
  {
    path: '/products',
    component: () => import('@/views/Products.vue'),
    props: (route) => ({
      category: route.query.category || 'all',
      sort: route.query.sort || 'default'
    })
  }
]export default createRouter({
  history: createWebHistory(),
  routes
})

 复制代码

命名视图的 props

路由里有多个命名视图时，可以给每个视图单独设置 props，互不干扰：

 复制代码{
  path: '/dashboard/:id',
  components: {
    default: Dashboard,
    sidebar: Sidebar,
    header: HeaderNa v
  },
  props: {
    default: true,               // 将 params.id 传给 Dashboard
    sidebar: (route) => ({       // 函数模式
      menu: route.query.menu || 'main'
    }),
    header: { title: '控制台' }   // 静态数据
  }
}

嵌套路由的 props 传递

嵌套路由时，父级和子级各自需要 props，但 Vue Router 不会自动透传——你得手动配置：

 复制代码{
  path: '/user/:userId',
  component: UserLayout,
  props: true,  // userId 传给 UserLayout
  children: [
    {
      path: 'profile',
      component: UserProfile,
      props: true  // userId 也传给 UserProfile
    },
    {
      path: 'posts',
      component: UserPosts,
      props: (route) => ({
        userId: route.params.userId,  // 父级参数需要手动传递
        page: Number(route.query.page) || 1
      })
    }
  ]
}

Vue2 vs Vue3 对比一览

实际场景对比

不用的糟糕写法

 复制代码

三个问题： 耦合 $route、无法复用、难以测试——一个不落。

使用 props 的最佳实践

 复制代码// 路由配置
{
  path: '/user/:id/articles',
  component: UserArticles,
  props: (route) => ({
    userId: route.params.id,
    category: route.query.category || 'all'
  })
}

 复制代码

三大优势：

• 组件纯组件化——传入什么渲染什么，跟路由没关系
• 单元测试只需 mount(Component, { props })，路由不用管
• 这个组件可以在任何地方复用——甚至不需要路由

函数模式进阶用法

参数类型转换

URL 参数全是字符串，但组件可能需要数字、数组。函数模式里直接转换：

 复制代码props: (route) => ({
  id: Number(route.params.id),   // 字符串 → 数字
  page: parseInt(route.query.page) || 1,
  tags: route.query.tags ? route.query.tags.split(',') : []
})

路由级权限控制

从 route.meta 里取权限信息，直接变成组件 props，干净利落：

 复制代码props: (route) => ({
  permission: route.meta.requiredPermission || 'guest',
  role: route.meta.role
})

合并多个来源

想要同时拿到 params、query 再加点静态标记？用展开运算符一把梭：

 复制代码props: (route) => ({
  ...route.params,
  ...route.query,
  from: 'router',
  timestamp: Date.now()
})

默认值与兜底

解构赋值 + 默认值，优雅处理缺失参数：

 复制代码props: (route) => {
  const { id, tab = 'overview' } = route.params
  return {
    id: id || 'default',
    tab,
    query: route.query
  }
}

总结：一句话记住

最佳实践建议： 新项目对所有带路由参数的组件统一使用 props 配置，养成“路由只管路由，组件只管 props”的习惯。这对长期维护和团队协作有百利而无一害。

实战小贴士

如果你正在从 Vue2 迁移到 Vue3，props 配置的迁移成本几乎为零——API 完全兼容。唯一需要留意的几个点：

1. Vue3 script setup 中用 defineProps 接收即可，写法更简洁
2. TypeScript 项目下类型推导比 Vue2 好得多，强烈建议配合 TS 使用，props 类型一目了然
3. 大型项目建议团队统一约定：所有带路由参数的页面组件都必须配合 props 配置

如果你已经用了 props: true，不妨逐步升级为函数模式——多花 3 行代码，换来组件完全解耦，这笔买卖绝对值。