Vue / 系统课时
动态路由与参数类型
动态路由与参数类型
动态路由把 URL 中的路径片段和查询条件带进页面,但这些值本质上仍是外部输入。本节用 TypeScript 建立统一解析层,正确处理 params、query、可选参数与非法值,让页面内部只接触已经校验过的强类型数据。
学习目标
- 区分
params与query的来源、缺省值和可能的运行时形态。 - 为数字、枚举和可选参数建立可复用的解析与校验规则。
- 在同一页面参数变化时保持类型安全,并对非法 URL 做确定性跳转。
先把路由参数当作外部输入
params 来自路径占位符,例如 /users/:id;query 来自问号后的查询串,例如 ?page=3。即使业务把 id 定义为数字,浏览器地址栏传入的仍是字符串。重复查询参数还可能形成数组,可选参数则可能完全不存在。
因此不要用 route.params.id as number 这类断言跳过校验。类型断言只改变 TypeScript 的静态视图,不会把 "42" 转成 42,也不会阻止用户输入 /users/abc。
| 输入 | URL 示例 | 页面边界应做的事 |
|---|---|---|
| 必填路径参数 | /users/42 |
校验存在性并转换类型 |
| 可选路径参数 | /users/42/settings |
缺省时给默认值,存在时校验枚举 |
| 查询参数 | ?page=3&q=vue |
处理缺省、数组和格式错误 |
定义路由并保留可选参数
下面是路由配置片段,依赖项目中已有的 UserPage.vue。tab 后面的 ? 表示它可以省略,因此 /users/42 与 /users/42/settings 都能匹配同一页面。
import type { RouteRecordRaw } from 'vue-router'
import UserPage from '@/views/UserPage.vue'
export const userRoutes: RouteRecordRaw[] = [
{
path: '/users/:id/:tab?',
name: 'user-detail',
component: UserPage,
},
]生效后可在浏览器分别访问 /users/42、/users/42/settings?page=3 验证匹配结果。这里只定义“哪些 URL 能进入页面”,真正的类型转换与业务校验应放在页面边界完成。
在页面边界完成解析与校验
下面的 UserPage.vue 把路由原始值统一转换为 UserPageParams。辅助函数接收 unknown,先处理字符串或数组,再验证正整数和页签枚举;任何关键参数不合法时都跳转到项目已有的 not-found 路由。
<script setup lang="ts">
import { computed, watch } from 'vue'
import { useRoute, useRouter } from 'vue-router'
const route = useRoute()
const router = useRouter()
const tabs = ['profile', 'settings'] as const
type UserTab = (typeof tabs)[number]
interface UserPageParams {
id: number
tab: UserTab
page: number
keyword: string
}
function first(value: unknown): string | undefined {
if (typeof value === 'string') return value
if (Array.isArray(value) && typeof value[0] === 'string') return value[0]
return undefined
}
function positiveInt(value: unknown): number | null {
const text = first(value)
if (!text || !/^\d+$/.test(text)) return null
const result = Number(text)
return Number.isSafeInteger(result) && result > 0 ? result : null
}
function parseTab(value: unknown): UserTab | null {
const text = first(value)
if (text === undefined) return 'profile'
return tabs.includes(text as UserTab) ? (text as UserTab) : null
}
// 解析层是页面的边界:模板和后续业务代码只读取已校验值。
const pageParams = computed<UserPageParams | null>(() => {
const id = positiveInt(route.params.id)
const tab = parseTab(route.params.tab)
const page = route.query.page === undefined ? 1 : positiveInt(route.query.page)
const keyword = first(route.query.q)?.trim() ?? ''
if (id === null || tab === null || page === null) return null
return { id, tab, page, keyword }
})
// 同一组件被复用时参数仍会变化,因此持续验证而不是只在挂载时检查一次。
watch(
pageParams,
(value) => {
if (value === null) void router.replace({ name: 'not-found' })
},
{ immediate: true },
)
</script>
<template>
<section v-if="pageParams">
<p>用户 ID:{{ pageParams.id }}</p>
<p>页签:{{ pageParams.tab }}</p>
<p>页码:{{ pageParams.page }}</p>
<p>关键字:{{ pageParams.keyword }}</p>
</section>
</template>预期结果
访问 /users/42/settings?page=3&q=vue
用户 ID:42
页签:settings
页码:3
关键字:vue
访问 /users/42
页签使用默认值 profile,页码使用默认值 1
访问 /users/abc 或 /users/42/other
跳转到名为 not-found 的路由实际地址、页面样式和目标路由名称取决于项目配置,但参数解析结果应与上面一致。
类型安全要覆盖导航和运行时
企业项目可以进一步为命名路由生成或声明类型,让 router.push、RouterLink 在编译期发现漏传参数或参数名拼错。不过静态类型不能替代运行时校验,因为用户仍可手工输入 URL、打开旧书签或访问外部链接。
同一路由从 /users/41 切到 /users/42 时,Vue Router 可能复用当前页面组件。此时应让 computed、watch 或 onBeforeRouteUpdate 响应参数变化,而不是假设组件一定重新挂载。把“原始路由值 → 校验 → 强类型页面参数”固定成边界后,后续请求函数和子组件就无需反复处理字符串、空值与非法枚举。