Storybook for TanStack React 实战在 Story 中渲染动态参数路由/$id与 Loader 覆写本指南围绕 Storybook 的 TanStack React 框架storybook/tanstack-react展开聚焦如何在 Story 中渲染带动态参数如/$id的文件路由通过parameters.tanstack.router提供route、params与routeOverrides无需启动完整应用即可让路由组件在内存路由器中独立渲染。读完本文你将掌握动态参数注入、Loader 级数据打桩的两种主流写法CSF 3 与 CSF Next并理解其背后的路由构建与参数插值原理。为什么动态参数路由需要专门处理TanStack Router 中的动态参数路由file-based route路径形如/$id、/users/$userId在真实应用里由路由器在匹配 URL 时解析params并通过loader基于参数发起数据请求。在 Storybook 中直接渲染这类路由组件会遇到两个问题路由组件依赖路由上下文useParams、useLoaderData、useRouterState等 hooks脱离路由器无法工作loader通常会调用真实 API写 Story 时希望用固定数据替换它且不能修改原始路由对象。storybook/tanstack-react通过parameters.tanstack.router命名空间一次性解决上述问题它自动为每个 Story 包裹一个内存路由器memory-backed router提供路由上下文params负责把动态参数插值进 URLrouteOverrides则允许按路由 ID 覆写loader、beforeLoad等选项实现纯前端的数据打桩。官方文档在 TanStack React 框架指南 的 Handling dynamic params (e.g.,/$id) 一节对此作了专门说明本文即以其为核心展开。核心配置parameters.tanstack.router三要素处理动态参数路由只需在 Story 的parameters.tanstack.router下配置三个字段字段类型作用routeAnyRoute \| route options object传入从路由文件导出的 Route 对象Storybook 自动提取其 React 组件作为 Story 组件参见 loader.ts 中的routeComponentLoaderparamsResolveParamsPath动态参数对象会被插值进当前 URL 路径如{ id: 42 }对应/$idrouteOverridesPartialRecordstring, RouteOverrideOptions按路由 ID如/showcase/$id、__root__覆写loader、beforeLoad、validateSearch、loaderDeps、context等选项不触碰原始路由对象从类型定义看types.tsparams被约束为ResolveParamsPath当route是带类型的文件路由时参数名被限制为该路由路径中声明的参数例如/$id只允许{ id: string }写错参数名或类型会在编译期直接报错这就是类型安全的动态参数的含义。完整示例一CSF 3 写法假设路由文件为src/routes/showcase.$id.tsx导出Route其loader基于id拉取商品数据。在 Story 文件中按如下方式编写完整代码见 tanstack-react-dynamic-params.mdimport type { Meta } from storybook/tanstack-react; import { Route } from ./$id; const meta { parameters: { tanstack: { router: { route: Route, params: { id: 42 }, routeOverrides: { /showcase/$id: { loader: () ({ item: mockItem }), }, }, }, }, }, } satisfies Metatypeof Route; export default meta;要点说明route: Route让 Storybook 直接从路由对象提取组件同时保留 TanStack 的完整类型推导后续params、routeOverrides都能获得类型约束params: { id: 42 }被插值到路径中最终内存路由器的初始 URL 为/showcase/42routeOverrides[/showcase/$id].loader覆写了真实 loaderStory 渲染时useLoaderData()拿到的是{ item: mockItem }实现不修改应用代码即可展示指定数据状态。更完整的对照示例可参考 tanstack-react-route-story.md其中展示了在单个 Story 中覆写/items/$id的 loader 返回{ item: { id: 42, name: Loaded inside Storybook } }的写法并演示了query: { tab: details }这类搜索参数的用法。完整示例二CSF Next 写法项目启用了 CSF Next实验性语法时写法从satisfies Meta...切换为preview.meta(...)配置结构完全一致import preview from ../.storybook/preview; import { Route } from ./$id; const meta preview.meta({ parameters: { tanstack: { router: { route: Route, params: { id: 42 }, routeOverrides: { /showcase/$id: { loader: () ({ item: mockItem }), }, }, }, }, }, });随后用export const Default meta.story();生成 Story如需按 Story 级差异化覆写 loader可通过meta.story({ parameters: { ... } })传入。CSF 3 与 CSF Next 在tanstack.router参数的语义上完全等价迁移成本极低。底层原理params 如何变成 URLoverrides 如何生效1. 参数插值interpolatePath在 decorator.tsx 的createStoryRouter中路由路径的推导顺序为parameters.tanstack.router.path→ 路由的fullPath→ 规范化后的路由 ID → 沿父链计算的挂载路径。随后调用 TanStack Router 的interpolatePath把params插值进该路径let resolvedPath interpolatePath({ path: inferredPath, params: routerParameters?.params ?? {}, }).interpolatedPath;如果还提供了query则通过defaultStringifySearch序列化后拼接到路径末尾。最终用createMemoryHistory({ initialEntries: [resolvedPath] })创建内存历史再交给createRouter构建路由器——这正是无需启动完整应用的根基。2. 渲染前加载routerBeforeEachbefore-each.ts 中的routerBeforeEach在每次 Story 渲染前执行创建故事路由器并调用router.load()保证初始路由包括被覆写后的 loader在组件渲染之前完成加载同一 Story 的路由器会被缓存复用并在清理阶段从storyRouters中删除。这也解释了为什么loader返回的数据在useLoaderData()中直接可用。3. 覆写生效路由树复制routeOverrides并非直接修改原始路由。在resolveTreedecorator.tsx中Storybook 会基于传入的 Route 找到其根路由通过duplicateRouteTree复制整棵路由树并应用 overrides再把 Story 组件注入到叶子路由上。这样每个 Story 之间路由树相互隔离原始应用路由对象始终不受影响——这是覆写而不污染的设计关键。当route未连接任何根路由时框架会创建一个合成根路由挂载它routeOverrides中以__root__为键的配置即作用于该根路由。4. 导航 hooks 自动 Mock框架的 preset 会把tanstack/react-router的导入重定向到 mock 层react-router.ts。useNavigate、useParams、useLoaderData等 hooks 基于真实实现包装为fn()spy在 Story 中照常工作Link点击与Navigate渲染会触发导航尝试但被拦截同时记录到onNavigatespyspies.tsplay function 可以断言导航行为而 Story 画面保持不变。进阶搭配参数、搜索串与上下文动态参数只是tanstack.router能力的一部分按官方文档可组合出更丰富的场景搜索参数与 URL 片段query: { tab: details, page: 2 }生成?tabdetailspage2path设置初始路径可含#section-name片段。嵌套路由当route是已连接应用路由树的文件路由时Storybook 会自动包含父级布局路由Story 渲染在与应用一致的嵌套层级中可用path定位具体路由用routeOverrides打桩祖先路由上的 guard 或 loader参见 tanstack-react-route-tree-overrides.md 中/users/$userId的覆写示例。非 Route 普通组件若 Story 渲染的是普通 React 组件但内部使用了useParams、useSearch、useLoaderData等 hooks同样可以只提供parameters.tanstack.router注入路由上下文无需把 Route 本身作为 Story 组件。路由上下文注入context接受静态对象或工厂函数工厂在路由初始加载前React 渲染之外运行因此其值对loader/beforeLoad可见若某值只能在 React provider 中读取则用useRouterContexthook注意它运行于渲染阶段无法到达初始 loader参见 框架文档 的说明。验证与调试建议确认类型推导生效params的键名应与路由路径参数严格一致/$id→{ id: ... }编译报错时优先检查route是否来自带类型的文件路由导出。检查覆写是否命中routeOverrides的键必须与路由 ID 完全匹配如/showcase/$id不匹配时 loader 不会被覆写Story 会走真实数据请求。结合测试断言导航借助 mock 层导出的onNavigatespy从storybook/tanstack-react/react-router导入可在 play function 中断言Link点击或useNavigate调用实现渲染 交互的一体化验证。小结处理 TanStack Router 动态参数路由的 Story 编写范式可以概括为三步用route指定路由对象获得类型安全用params注入动态参数用routeOverrides打桩 loader 数据。底层的内存路由器 路由树复制 hooks Mock 三层机制保证了 Story 之间的隔离性、原始路由的零污染以及导航行为的可观测性使/$id这类依赖路径参数与数据加载的组件也能在 Storybook 中稳定、独立地渲染与测试。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考