TanStack Router 路径参数（Path Params）速查表

路径参数是 URL 中以 $ 开头的变量，用于捕获动态内容。

功能	语法示例	URL 匹配示例	捕获到的变量
标准参数	$postId	/posts/123	{ postId: '123' }
带前缀	post-{$id}	/posts/post-abc	{ id: 'abc' }
带后缀	{$name}.pdf	/files/cv.pdf	{ name: 'cv' }
通配符 (Splat)	$	/files/a/b/c.txt	{ _splat: 'a/b/c.txt' }
可选参数	{-$lang}	/about 或 /en/about	{ lang: undefined } 或 'en'

---

详细功能解析

1. 基础用法 (Standard Usage)

在文件路由中，文件名即路径。使用 $ 声明变量。

• 获取参数：

  • 在 Loader 中：通过参数对象 params 访问。

  • 在 组件 中：使用 Route.useParams() 钩子。

• 代码分割技巧 ：如果组件是单独定义的，可用 getRouteApi('/path').useParams() 来保持类型安全。

2. 前缀与后缀 (Prefixes and Suffixes)

这是 TanStack Router 的一大特色，允许你在动态部分前后添加固定文本。

• 语法 ：用花括号 {} 包裹变量名。

• 场景 ：比如文件名匹配 {$id}.json，或者带特定标识的 ID user-{$userId}。

• 通配符组合 ：你甚至可以写 storage-{$}/$ 来匹配极其复杂的路径结构。

3. 可选路径参数 (Optional Path Parameters) ✨ 重点

使用 {-$variable} 语法。这意味着该段路径可以存在也可以不存在。

• 匹配逻辑 ：/posts/{-$category} 既能匹配 /posts（参数为 undefined），也能匹配 /posts/tech。

• 导航 ：在 Link 中，如果想去掉可选参数，将值设为 undefined 即可。

4. 国际化 (i18n) 应用场景

可选参数最强大的地方在于处理语言前缀。

• 设计 ：/{-$locale}/about

• 效果：

  • 用户访问 /about -> 默认语言（如中文）。

  • 用户访问 /en/about -> 英文。

• 这样你不需要为每种语言创建文件夹，只需一个路由逻辑即可搞定。

5. 类型安全 (Type Safety)

TanStack Router 的核心优势。

• 当你跳转（Link 或 Maps）到一个带参数的路由时，TypeScript 会强制要求你提供该参数。

• 如果是可选参数，TS 会自动推断其类型为 string | undefined，提醒你做空值处理。

---

常见疑问解答

Q: 怎么在组件外获取参数？

使用全局的 useParams({ strict: false })。但建议尽可能在路由内部使用，以获得完整的类型提示。

Q: 参数里能包含特殊字符（如 @）吗？

默认会进行 URL 编码。如果你想让它直接显示，需要在 createRouter 的配置中设置 pathParamsAllowedCharacters: ['@']。

Q: 导航时如何保留现有的参数？

在 Link 或 Maps 的 params 中使用函数式写法：

params={(prev) => ({ ...prev, newParam: 'value' })}

---

一句话总结：

路径参数不仅是 $id 这么简单，通过 前缀/后缀、可选标志 和 强类型校验，你可以极其优雅地处理复杂的 URL 结构（如文件系统预览或多语言站点），且完全不会写错路径。