用途:在 TanStack Router 中定义与读取 URL 动态路径参数,把动态段捕获为命名变量。
主要能力:$paramName 捕获到下一个 / 为止的动态段,支持跨层级多个动态段;以裸 $ 结尾的路由为全捕获(splat),值在 _splat 键下;{-$paramName} 定义可选参数,缺失时为 undefined,可用于多个可选段及 i18n 可选 locale;{$paramName} 大括号支持同一段内前后缀,如 /posts/post-{$postId}、/files/{$fileName}.txt 及组合写法。useParams 可带 from 读取指定路由参数,或用 strict: false 读取全部可能参数;参数在 loader 和 beforeLoad 的 params 中也可用;Link 与 navigate 通过 params 传参,函数式 params 可保留其它参数。
关键用法与限制:绝对不要把参数插入 to 字符串,应始终用 params 属性;类型全自动推断,不要给 useParams() 返回值加注解;参数默认按 encodeURIComponent 编码,可在 createRouter 中通过 pathParamsAllowedCharacters 增加允许字符(;, :, @, &, =, +, $, ,);参数始终是字符串,需要数字时在 loader 中解析,或用 params.parse / params.stringify 做双向转换。splat 请用 $ 与 _splat,v1 中 * 仅为兼容、v2 将移除;大括号仅用于前后缀与可选参数,基本动态段用裸 $。
适用场景:帖子、团队/成员、文件浏览、带可选分类或语言前缀的路由。