Storybook for TanStack React：使用 parameters.tanstack.router 将 TanStack Route 渲染为 Story 的完整指南

Storybook for TanStack React使用 parameters.tanstack.router 将 TanStack Route 渲染为 Story 的完整指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南聚焦于 Storybook 官方框架 storybook/tanstack-react 的核心路由能力通过parameters.tanstack.router将 TanStack Router 的 Route 对象直接作为 Story 渲染并利用类型安全的route、params、query、routeOverrides等参数控制初始 URL、动态路径参数与 loader 行为。读完本文你将掌握在 Storybook 中渲染带路由上下文的组件、在不修改原始 Route 的前提下为单个 Story 覆写路由加载逻辑的完整实战方案。背景为什么需要“路由感知”的 Story在 TanStack Router 应用中页面组件往往依赖路由上下文才能工作——例如通过useLoaderData()读取loader返回的数据、通过useParams()读取 URL 动态参数、通过useSearch()读取查询串。传统的storybook/react-vite框架不会为 Story 提供任何路由环境直接渲染这类组件会立刻崩溃或得到空白内容。Storybook for TanStack React 正是为此设计的它在storybook/react-vite的基础上自动为每个 Story 包裹一个基于createMemoryHistory的内存路由器见 decorator.tsx从而无需启动完整的应用外壳即可获得可用的路由上下文。核心 APIparameters.tanstack.router本框架向 Storybook 贡献了一组位于tanstack.router命名空间下的 parameters。其类型定义位于 types.ts参数类型作用routeAnyRoute \| route options 对象直接提供 Route 实例或提供纯配置对象以创建临时 Story 路由pathstring设置故事路由的初始 URL 路径paramsResolveParamsPath将动态路径参数插值进 URL如$id对应{ id: 42 }queryRecordstring, unknown追加到初始 URL 的搜索参数即 query stringrouteOverridesPartialRecordstring, RouteOverrideOptions按路由 ID 覆写loader、beforeLoad、validateSearch、loaderDeps、context等选项context对象或工厂函数注入故事路由的路由上下文工厂在路由初次加载前运行useRouterContextReact Hook在渲染期间计算路由上下文可读取 React Provider 的值完整示例把 Route 渲染为 Story关联文档 tanstack-react-route-story.md 给出了 CSF 3 与 CSF Next 两种写法的完整示例。其核心思路是从./Page导入 Route 对象通过parameters.tanstack.router.route交给 StorybookStorybook 会自动提取该 Route 的 React 组件作为 Story 渲染。CSF 3 写法// Page.stories.ts import type { Meta, StoryObj } from storybook/tanstack-react; import { Route } from ./Page; const meta { parameters: { layout: fullscreen, tanstack: { router: { route: Route, // 在此提供 Route // 其余属性均为类型安全 params: { id: 42 }, query: { tab: details }, }, }, }, } satisfies Metatypeof Route; export default meta; type Story StoryObjtypeof meta; export const Default: Story {}; export const WithCustomLoader: Story { parameters: { tanstack: { router: { route: Route, // 在此提供 Route // 其余属性均为类型安全 params: { id: 42 }, routeOverrides: { /items/$id: { loader: async () ({ item: { id: 42, name: Loaded inside Storybook }, }), }, }, }, }, }, };CSF Next 写法实验性// Page.stories.ts import preview from ../.storybook/preview; import { Route } from ./Page; const meta preview.meta({ parameters: { layout: fullscreen, tanstack: { router: { route: Route, // 在此提供 Route // 其余属性均为类型安全 params: { id: 42 }, query: { tab: details }, }, }, }, }); export const Default meta.story(); export const WithCustomLoader meta.story({ parameters: { tanstack: { router: { route: Route, // 在此提供 Route // 其余属性均为类型安全 params: { id: 42 }, routeOverrides: { /items/$id: { loader: async () ({ item: { id: 42, name: Loaded inside Storybook }, }), }, }, }, }, }, });注意两个示例中layout: fullscreen属于 Storybook 通用参数让故事全屏渲染tanstack.router下的所有属性route、params、query、routeOverrides才是本框架的路由控制面。逐项拆解每个参数怎么用routeStory 的路由主体route接受一个 TanStack Route 实例可以从文件路由模块中导入Storybook 会自动提取其 React 组件。从源码结构看resolveTree 按以下优先级解析要渲染的路由parameters.tanstack.router.route如果它是 Route 实例Story meta 上的route如果它是 Route 实例parameters.tanstack.router.route中的纯配置对象构建合成根路由 子路由无任何输入时创建不含选项的合成根路由与子路由把 Story 注入其中。如果解析出的路由还不是根路由框架会沿getParentRoute()向上找到其根并复制整棵路由树duplicateRouteTree以保证各 Story 之间的路由状态相互隔离。当你传入的是连接到应用路由树的文件路由时父级布局路由会自动包含进来Story 渲染在与应用相同的嵌套层级中。params动态路径参数的插值对于形如/$id的动态路由params对象会被插值进初始 URL。在 createStoryRouter 中可以看到其底层实现通过 TanStack Router 的interpolatePath将{ id: 42 }拼入路径再交给createMemoryHistory作为初始条目。当route是带类型的文件路由时params的类型会被约束为该路由路径中声明的参数名——例如/$id只允许{ id: string }。这正是“其余属性均为类型安全”的保障来源。query搜索参数query用于追加 query string。源码中使用defaultStringifySearch将对象序列化为?tabdetails形式的查询串并拼接到解析后的路径上。这在展示列表页、筛选页等依赖搜索参数的场景非常实用。routeOverrides不修改原路由的加载逻辑覆写这是最有实战价值的能力当 Route 的loader或beforeLoad会调用真实 API 时你可以在不修改原始 Route 对象的前提下按路由 ID 覆写这些选项。每个 key 是一个路由 ID如/items/$id、/about、__root__value 可覆写 RouteOverrideOptions 中定义的全部选项component覆写路由组件loader覆写数据加载函数如示例中返回 mock 数据beforeLoad覆写加载前守卫常用于跳过鉴权validateSearch覆写搜索参数校验loaderDeps覆写加载依赖context覆写路由上下文。用__root__作为 key 可以定位根路由。在 decorator.tsx 的实现中覆写会先作用于复制后的路由树duplicateRouteTree(tree, { overrides })再通过injectStoryComponent把 Story 组件注入到叶子路由——除非用户显式覆写了该叶子的component。动态参数 loader 覆写的组合拳关联文档还配套了动态参数场景的示例 tanstack-react-dynamic-params.md// Showcase.stories.ts import 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;这里的配合关系是params负责让 URL 变为可解析的/showcase/42routeOverrides负责拦截真实的loader调用并返回mockItem。两者缺一不可——没有params动态路由无法匹配没有routeOverridesStory 渲染时会真实请求后端。更复杂的嵌套路由场景如路径式布局、守卫、多个祖先 loader可以在 tanstack-react-route-tree-overrides.md 与 tanstack-react-route-tree-story.md 中找到对应示例。源码级原理Story 路由器是如何构建的框架在渲染前通过routerBeforeEach钩子见 before-each.ts完成路由器的创建与首次加载读取context.parameters.tanstack?.router若提供了context工厂函数则在 React 渲染外执行使返回值对loader和beforeLoad可见调用 createStoryRouter 构建内存路由器解析路由树 → 推断初始路径优先级为path参数 路由fullPath 归一化的路由 ID mountPathFor推算的挂载路径→ 插值 params → 拼接 query → 创建createMemoryHistory→createRouter执行router.load()完成初次加载并缓存路由器按context.id以便复用渲染阶段tanstackRouteDecorator通过RouterProvider包裹 Story并将 Story 组件经StoryContext传递到注入点StoryFromContext。这套机制保证导航 HookuseNavigate、useSearch、useParams等在 Story 中可用且每个 Story 的路由树相互隔离。routerBeforeEach的报错信息也明确指出本框架不支持 portable stories原因就是渲染前的路由器注入依赖 Storybook 的 beforeEach 生命周期。使用注意与边界动态参数的类型安全params的键名受文件路由路径约束编译期即可发现拼写错误自定义 Route 未注册进路由树时类型会放宽为Recordstring, unknown。routeOverrides的 key 语义key 使用路由 ID即路径形式__root__指根路由示例中的/items/$id应与你应用中的实际路径一致。不支持的场景官方框架文档 tanstack-react.mdx 明确说明本框架在浏览器中以内存路由器运行不支持 React Server Components若组件是 Server Component需将客户端部分抽取为 Client Component 再编写 Story。从storybook/react-vite迁移官方提供自动化迁移工具运行npx storybook automigrate react-vite-to-tanstack-react即可替换依赖与配置迁移后应移除手写的RouterProvider/createRouter/createMemoryHistory/createRootRoute装饰器改用parameters.tanstack.router对应实现见 react-vite-to-tanstack-react.ts。总结parameters.tanstack.router是 Storybook for TanStack React 的路由控制中枢route决定“渲染哪个路由”params/query/path决定“URL 长什么样”routeOverrides决定“加载逻辑如何被安全覆写”。通过这一套类型安全的参数体系你可以为每个 Story 独立构造路由上下文用 mock 数据驱动 loader从而轻松文档化加载中、成功、失败等各类界面状态全程无需改动任何应用代码。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考