Quasar 路由 Props 传参：`props: true` vs `props: (route) => ({})` 企业级应用指南

# Quasar 路由 Props 传参：`props: true` vs `props: (route) => ({})` 企业级应用指南

在 Quasar/Vue Router 中，`props: true` 和 `props: route => ({})` 是两种不同的路由参数传递方式，它们适用于不同的场景。下面我将详细解释它们的区别、适用场景以及企业级最佳实践。

## 核心区别对比

| 特性 | `props: true` | `props: route => ({})` |
|--------------------------|-----------------------------------|-----------------------------------|
| **参数来源** | 仅路径参数 (params) | 路径参数 + 查询参数 (query) |
| **参数映射** | 自动映射同名 prop | 手动映射到任意 prop 名称 |
| **参数转换** | 不支持 | 支持类型转换、计算值 |
| **默认值设置** | 不支持 | 支持设置默认值 |
| **代码复杂度** | 简单 | 中等 |
| **适用场景** | 简单参数传递 | 复杂参数处理 |
| **企业级推荐指数** | ★★☆☆☆ (简单场景) | ★★★★★ (推荐) |

## 1. `props: true` - 简单路径参数传递

### 使用方式
```javascript
// 路由配置
{
path: '/user/:userId',
component: UserProfile,
props: true // 启用自动参数传递
}

// 组件中
const props = defineProps<{
userId: string // 自动接收路由中的 userId 参数
}>()
```

### 企业级适用场景
1. **简单详情页**：只需要一个 ID 参数
```javascript
path: '/product/:productId'
```

2. **参数名称一致**：路由参数名和组件 prop 名相同
```javascript
// 路由：/department/:departmentId
// 组件：defineProps<{ departmentId: string }>()
```

3. **不需要查询参数**：仅使用路径参数

4. **原型开发**：快速开发阶段

### 优点
- 配置简单，一行代码即可
- 自动映射路径参数

### 缺点
- 无法处理查询参数
- 无法重命名参数
- 无法设置默认值
- 无法进行参数转换

## 2. `props: route => ({})` - 高级参数处理

### 使用方式
```javascript
// 路由配置
{
path: '/profile/:userId',
component: UserProfile,
props: route => ({
userId: route.params.userId,
profileId: route.params.profileId,
viewMode: route.query.mode || 'standard', // 设置默认值
isEditing: route.query.edit === 'true' // 类型转换
})
}

// 组件中
const props = defineProps<{
userId: string
profileId: string
viewMode: 'standard' | 'advanced'
isEditing: boolean
}>()
```

### 企业级适用场景
1. **多参数组合**：路径参数 + 查询参数
```javascript
path: '/project/:projectId/task/:taskId'
```

2. **参数重命名**：路由参数名与组件 prop 名不同
```javascript
props: route => ({
projectID: route.params.projectId // 重命名
})
```

3. **设置默认值**：为可选参数提供默认值
```javascript
tab: route.query.tab || 'overview'
```

4. **参数转换**：类型转换、格式处理
```javascript
pageSize: parseInt(route.query.size as string) || 10
```

5. **复杂参数处理**：计算属性、条件判断
```javascript
showDetails: route.query.details === 'true' && user.isAdmin
```

6. **敏感参数处理**：基于权限过滤参数
```javascript
showSensitive: route.query.admin === 'true' && user.isAdmin
```

### 优点
- 完整的参数控制能力
- 支持查询参数和路径参数
- 支持参数转换和默认值
- 更好的类型安全性
- 适合企业级复杂应用

### 缺点
- 配置稍复杂
- 需要手动映射参数

## 企业级最佳实践

### 1. 简单场景使用 `props: true`
```javascript
// 适用于只需传递 ID 的简单场景
{
path: '/product/:id',
component: ProductDetail,
props: true
}

// 组件中
defineProps<{ id: string }>()
```

### 2. 复杂场景使用 `props: route => ({})`
```javascript
// 企业级用户档案详情页
{
path: '/user/:userId/profile/:profileId',
component: UserProfileDashboard,
props: route => ({
userId: validateId(route.params.userId),
profileId: validateId(route.params.profileId),
tab: route.query.tab || 'overview',
viewMode: route.query.view || 'detailed',
page: parseInt(route.query.page as string) || 1,
showSensitive: route.query.admin === 'true' && isAdminUser()
})
}

// 参数验证函数
function validateId(id: unknown): string {
if (typeof id === 'string' && /^[a-f\d]{24}$/i.test(id)) {
return id;
}
throw new Error(`Invalid ID format: ${id}`);
}
```

### 3. 推荐模式：始终使用 `props: route => ({})`

在企业级应用中，我推荐**始终使用函数形式**的 props 配置，原因如下：

1. **一致性**：统一参数处理方式
2. **灵活性**：随时扩展参数处理逻辑
3. **安全性**：添加参数验证
4. **可维护性**：集中管理参数处理逻辑
5. **类型安全**：更好的 TypeScript 支持

### 4. 企业级参数处理封装

```javascript
// src/utils/routeParams.ts

/**
* 企业级路由参数处理工具
* @param route 路由对象
* @param mapping 参数映射配置
*/
export function processRouteParams(
route: RouteLocationNormalizedLoaded,
mapping: {
params?: Record<string, (val: unknown) => any>
query?: Record<string, (val: unknown) => any>
}
) {
const result: Record<string, any> = {};

// 处理路径参数
if (mapping.params) {
for (const [key, transform] of Object.entries(mapping.params)) {
try {
result[key] = transform(route.params[key]);
} catch (error) {
console.error(`Invalid route param ${key}:`, error);
throw new Error(`Route validation failed for ${key}`);
}
}
}

// 处理查询参数
if (mapping.query) {
for (const [key, transform] of Object.entries(mapping.query)) {
try {
result[key] = transform(route.query[key]);
} catch (error) {
console.error(`Invalid query param ${key}:`, error);
throw new Error(`Query validation failed for ${key}`);
}
}
}

return result;
}

// 路由配置中使用
import { processRouteParams } from '@/utils/routeParams';

{
path: '/project/:projectId',
component: ProjectView,
props: route => processRouteParams(route, {
params: {
projectId: (val) => {
if (typeof val === 'string' && /^PROJ-\d+$/.test(val)) return val;
throw new Error('Invalid project ID format');
}
},
query: {
tab: (val) => val || 'dashboard',
page: (val) => parseInt(val as string) || 1,
view: (val) => (val === 'compact' ? 'compact' : 'full')
}
})
}
```

## 企业级应用场景示例

### 场景 1：电商产品列表页

```javascript
// 路由配置
{
path: '/products',
component: ProductList,
props: route => ({
category: route.query.category || 'all',
sortBy: route.query.sort || 'price',
sortOrder: route.query.order === 'desc' ? 'desc' : 'asc',
page: parseInt(route.query.page as string) || 1,
itemsPerPage: parseInt(route.query.perPage as string) || 24,
filters: route.query.filters
? JSON.parse(decodeURIComponent(route.query.filters as string))
: {}
})
}

// 组件中
defineProps<{
category: string
sortBy: 'price' | 'rating' | 'date'
sortOrder: 'asc' | 'desc'
page: number
itemsPerPage: number
filters: Record<string, string[]>
}>()
```

### 场景 2：数据分析仪表板

```javascript
// 路由配置
{
path: '/analytics/:dashboardId',
component: AnalyticsDashboard,
props: route => ({
dashboardId: route.params.dashboardId,
dateRange: route.query.range || '30d',
interval: route.query.interval || 'daily',
metrics: route.query.metrics
? (route.query.metrics as string).split(',')
: ['visitors', 'conversion'],
compareTo: route.query.compare || 'previous_period'
})
}

// 组件中
defineProps<{
dashboardId: string
dateRange: string
interval: 'hourly' | 'daily' | 'weekly'
metrics: string[]
compareTo: 'previous_period' | 'year_ago' | 'custom'
}>()
```

### 场景 3：CRM 联系人详情页

```javascript
{
path: '/crm/contact/:contactId',
component: ContactDetail,
props: route => ({
contactId: route.params.contactId,
tab: route.query.tab || 'overview',
showActivities: route.query.activities === 'true',
showNotes: route.query.notes !== 'false', // 默认true
editMode: route.query.edit === 'true' && user.hasPermission('edit_contact')
})
}
```

## 企业级最佳实践总结

1. **优先使用函数形式**：`props: route => ({})` 提供最大的灵活性和控制力
2. **参数验证**：对所有传入参数进行验证
3. **类型转换**：在路由层完成字符串到其他类型的转换
4. **设置默认值**：为可选参数提供合理的默认值
5. **集中处理**：封装参数处理逻辑到可重用函数
6. **安全过滤**：基于用户权限过滤敏感参数
7. **文档化**：为每个参数添加 JSDoc 注释

```javascript
/**
* 用户档案路由参数处理
* @param route 路由对象
* @returns {Object} 组件props对象
*/
props: route => ({
// 用户ID (必须)
userId: validateUserId(route.params.userId),

// 显示模式 (可选，默认'standard')
viewMode: ['standard', 'compact', 'advanced'].includes(route.query.mode as string)
? route.query.mode
: 'standard',

// 当前页码 (可选，默认1)
currentPage: parseInt(route.query.page as string) || 1,

// 是否编辑模式 (可选，默认false)
isEditing: route.query.edit === 'true' && checkEditPermission()
})
```

## 何时使用 `props: true`？

虽然在企业级应用中我推荐始终使用函数形式，但 `props: true` 在以下场景仍然适用：

1. **简单原型开发**：快速验证想法时
2. **内部工具**：简单工具类应用
3. **参数单一的只读视图**：如 `/document/:docId`
4. **学习/演示项目**：简化配置

## 结论

在企业级 Quasar 应用中：

- 使用 **`props: route => ({})`** 处理复杂参数场景
- 保留 **`props: true`** 用于最简单的参数传递
- 始终添加 **参数验证** 和 **类型转换**
- 为可选参数设置 **合理的默认值**
- **封装重用** 参数处理逻辑

遵循这些实践，您可以构建出健壮、可维护的企业级路由参数处理系统，既能处理简单场景，又能应对复杂的参数需求。