登录
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，或者带特定标识的 IDuser-{$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 结构（如文件系统预览或多语言站点），且完全不会写错路径。
