用途:在 TanStack Router 中把 URL 动态片段捕获为命名变量,用于动态路由匹配与参数传递。
主要能力:1) 动态段:路由路径中以 $ 前缀的段捕获到下一个 / 为止的文本,如 /posts/$postId,可在多个层级叠加(/teams/$teamId/members/$memberId)。2) Splat/全捕获:路径以裸 $ 结尾捕获其后全部内容,值位于 _splat 键,如 /files/$ 的 _splat = "documents/report.pdf"。3) 可选参数:用 {-$paramName},缺失时为 undefined,如 /posts/{-$category},可多重可选,也常用于 i18n 的 /{-$locale}/about。4) 前后缀模式:用花括号包裹,如 /posts/post-{$postId} 得 postId="123",/files/{$fileName}.txt 得 fileName="readme",也可前后缀组合。
使用方式:在 createFileRoute 中声明路径;组件内用 Route.useParams() 或 useParams({ from: '/posts/$postId' }) 读取,跨组件可用 useParams({ strict: false });loader 与 beforeLoad 的 params 参数中直接可用。导航时用 <Link to="/posts/$postId" params={{ postId }} />,导航目标含其他参数时 params 可用函数形式 (prev) => ({ ...prev, postId }) 保留;编程式导航用 navigate({ to: '/posts/$postId', params: { postId } })。可选参数通过 params 中传值或 undefined 控制是否出现。默认用 encodeURIComponent 编码,可在 createRouter 的 pathParamsAllowedCharacters 中允许额外字符:;, :, @, &, =, +, $, ,。
限制与注意:不要把参数插值进 to 字符串,必须用 params 属性,否则破坏类型安全与编码;不要为 useParams() 返回值加类型注解,类型已完全推断;splat 用 $ 而非 ,值取 _splat, 在 v1 仅向后兼容、v2 将移除;花括号只用于前后缀与可选参数,基础动态段用裸 $;路径参数始终为字符串,需数字时在 loader/组件中解析,或使用路由的 params.parse 与 params.stringify 做双向转换。