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 都能匹配同一页面。

ts
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 路由。

vue
<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>

预期结果

text
访问 /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 响应参数变化,而不是假设组件一定重新挂载。把“原始路由值 → 校验 → 强类型页面参数”固定成边界后,后续请求函数和子组件就无需反复处理字符串、空值与非法枚举。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

动态路由与参数类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通