Storybook Autodocs 自定义 Docs Container 完全指南：用 preview 配置定制文档容器

Storybook Autodocs 自定义 Docs Container 完全指南用 preview 配置定制文档容器【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookAutodocs 是 Storybook 根据 CSF 故事自动生成组件文档页的机制而Docs Container是包裹整个文档页面的外层组件决定了文档页如何在 Storybook UI 中渲染。本指南基于docs/_snippets/storybook-preview-auto-docs-custom-docs-container.md中的官方代码片段结合code/addons/docs的源码实现讲解如何在.storybook/preview.jsx|tsx中通过docs.container参数替换默认容器涵盖 CSF 3 与 CSF Next 两种写法以及 React、Vue、Angular、Web Components 多框架适配读完即可在真实项目中落地自定义文档容器。Docs Container 是什么文档页的外层包装器在 Storybook 的文档体系中一个自动生成的文档页由两层结构组成Container容器与Page页面模板。Container 负责包住页面模板提供上下文、主题、目录TOC、代码源Source等基础能力Page 则负责具体排版内容如Title、Primary、Controls等 Doc Block 的排列。从源码 Docs.tsx 可以清晰看到二者的协作关系const Container: ComponentTypePropsWithChildren{ context; theme } docsParameter.container || DocsContainer; const Page docsParameter.page || DocsPage; return ( Container context{context} theme{docsParameter.theme} Page / /Container );这里揭示了两个关键事实docs.container与docs.page是相互独立的两个参数container决定外层包裹组件page决定页面内容模板。自定义容器时无需动模板反之亦然。未配置时使用内置默认值容器默认是DocsContainer页面默认是DocsPage。你的自定义组件会接收context文档上下文含当前组件的元数据、频道channel等和theme主题变量两个 props。因此自定义 Docs Container 本质上是用一个自己的 React 组件替换DocsContainer在保留 Storybook 文档核心能力的前提下注入自定义的逻辑、样式或包装层。在 preview 中配置自定义容器完整代码示例官方推荐在.storybook/preview.jsx|tsx中通过parameters.docs.container指定自定义组件。核心写法是定义一个接收children与其余 props 的组件内部渲染storybook/addon-docs/blocks导出的DocsContainer该导出在 blocks/index.ts 中确认存在并把{...props}与{children}透传下去。这样你可以在不丢失默认容器全部能力的前提下外层包裹自己的内容。CSF 3JavaScript 写法.storybook/preview.js|jsximport * as React from react; import { DocsContainer } from storybook/addon-docs/blocks; const ExampleContainer ({ children, ...props }) { return DocsContainer {...props}{children}/DocsContainer; }; export default { parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { container: ExampleContainer, }, }, };CSF 3TypeScript 写法.storybook/preview.ts|tsximport * as React from react; // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Preview } from storybook/your-framework; import { DocsContainer } from storybook/addon-docs/blocks; const ExampleContainer ({ children, ...props }) { return DocsContainer {...props}{children}/DocsContainer; }; const preview: Preview { parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { container: ExampleContainer, }, }, }; export default preview;注意 TypeScript 写法中Preview类型应替换为你实际使用的框架如storybook/react-vite、storybook/nextjs、storybook/vue3-vite等以获得完整的参数类型校验。CSF Next使用 definePreview 的现代写法CSF Next 是 Storybook 面向下一代 CSF 的实验性 API使用definePreview聚合 addons 与参数配置。若使用该模式需通过addons: [addonDocs()]显式注册 docs addon再在parameters.docs.container中挂载自定义容器。React.storybook/preview.tsx 与 .storybook/preview.jsximport * as React from react; // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; import { DocsContainer } from storybook/addon-docs/blocks; const ExampleContainer ({ children, ...props }) { return DocsContainer {...props}{children}/DocsContainer; }; export default definePreview({ addons: [addonDocs()], parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { container: ExampleContainer, }, }, });.storybook/preview.jsx的 JS 版本除definePreview来自storybook/your-framework无需类型导入外结构完全一致可直接照搬上述代码去掉类型注解。Vue 3.storybook/preview.ts / preview.jsimport * as React from react; import { definePreview } from storybook/vue3-vite; import addonDocs from storybook/addon-docs; import { DocsContainer } from storybook/addon-docs/blocks; const ExampleContainer ({ children, ...props }) { return DocsContainer {...props}{children}/DocsContainer; }; export default definePreview({ addons: [addonDocs()], parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { container: ExampleContainer, }, }, });Vue 项目的.storybook/preview.jsJS 版本写法相同仅需去掉definePreview的类型来源差异。即使项目使用 VueDocsContainer依然是 React 组件——因为 Storybook 的 docs 渲染层基于 React这一约束对所有非 React 框架Vue、Angular、Web Components 等同样成立。Angular.storybook/preview.tsimport * as React from react; import { definePreview } from storybook/angular; import addonDocs from storybook/addon-docs; import { DocsContainer } from storybook/addon-docs/blocks; const ExampleContainer ({ children, ...props }) { return DocsContainer {...props}{children}/DocsContainer; }; export default definePreview({ addons: [addonDocs()], parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { container: ExampleContainer, }, }, });Web Components.storybook/preview.ts / preview.jsimport * as React from react; import { definePreview } from storybook/web-components-vite; import addonDocs from storybook/addon-docs; import { DocsContainer } from storybook/addon-docs/blocks; const ExampleContainer ({ children, ...props }) { return DocsContainer {...props}{children}/DocsContainer; }; export default definePreview({ addons: [addonDocs()], parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { container: ExampleContainer, }, }, });.storybook/preview.js的 JS 变体结构与上述一致仅将definePreview导入来源保持为对应框架包即可。关于 controls.matchers 的说明上述所有示例中都包含controls.matchers配置它并非容器自定义所必需而是 Storybook 自动为argTypes匹配控件类型的基础配置匹配器含义示例color用正则匹配参数名自动推断颜色控件/(background\|color)$/i匹配background、textColor等date用正则匹配参数名自动推断日期控件/Date$/匹配updatedAt、releaseDate等保留它可以让你的preview配置同时获得完善的控件推断能力若项目已有该配置合并时注意不要覆盖。自定义容器的典型用途在不丢失默认能力的前提下扩展直接把children和props透传给DocsContainer是最安全的做法因为默认容器承担了大量基础设施职责。从源码 DocsContainer.tsx 可以看到它内置了以下能力自定义容器若完全替换它会丢失这些功能Docs Slugger 上下文DocsSluggerContext为文档内的标题生成稳定的锚点 ID保证目录跳转与深链可用。Docs 上下文DocsContext向所有 Doc Block 提供组件元数据、频道等数据是Primary、Controls等块正常工作的前提。Source 容器SourceContainer承载代码面板等源码展示能力。主题提供ThemeProviderensureTheme将themeprop 规范化并注入文档树配合 自定义主题 使用。目录渲染TableOfContents读取docs.toc参数并按docs.lang设置语言对应 autodocs 的 TOC 配置 中的contentsSelector、headingSelector、ignoreSelector、title、unsafeTocbotOptions等选项。锚点滚动页面加载时根据 URL hash 自动滚动到对应标题。因此推荐的扩展模式是外层包裹自定义逻辑如品牌化页头、全局样式容器、统计分析脚本、条件渲染内部始终渲染DocsContainer并透传 props 与 children。同时Docs组件还会把docsParameter.theme作为themeprop 传给容器见 Docs.tsx自定义容器需保证透传该 prop 才能让主题覆盖生效。参数类型container 在 DocsParameters 中的定义从类型定义 types.ts 可以确认docs.container的类型是ComponentTypeDocsContainerProps即一个接收DocsContainerProps的 React 组件类型export interface DocsContainerPropsTFramework extends Renderer Renderer { context: DocsContextPropsTFramework; theme?: ThemeVars; }而DocsContainerProps由contextDocsContextProps携带解析后的组件元数据与频道与可选的themeThemeVarsStorybook 主题变量组成。这意味着你的自定义组件若想访问当前文档对应的组件信息可以从props.context中读取例如调用context.resolveOf(meta, [meta])获取 meta 参数这正是默认容器读取docs.toc与docs.lang的方式。同一接口还给出了docs参数族的其他成员便于理解容器在整个 docs 参数体系中的位置argTypes、canvas、codePanel、controls、description、disable、page、source、toc等详见 types.ts。自定义容器通常与page搭配使用container管外壳、page管内容模板。从自定义容器到自定义文档能力边界与延伸自定义 Docs Container 只是 Autodocs 定制体系的一环官方文档 autodocs.mdx 中与它并列的能力还包括自定义模板docs.page通过返回 React 组件的page函数替换整个文档页面排版内部可用Title、Primary、Controls、Stories等 Doc Block 自由组合非 React 项目可用带isTemplate的 MDX 文件作为模板。自定义主题docs.theme为文档页覆盖light/dark主题与容器透传的themeprop 配合生效。自定义 MDX 组件MDXProvider替换 Markdown 语法渲染的组件注意原生 HTML 元素如h1不会被替换。目录定制docs.toc控制文档页目录的标题选择器、忽略规则与标题文案。实际项目中一个典型的落地组合是docs.container负责全局外壳品牌页头、布局约束docs.page负责内容模板docs.theme负责视觉风格三者各司其职、互不冲突。小结自定义 Docs Container 是 Storybook Autodocs 高级定制中最关键的一环通过.storybook/preview.jsx|tsx中的parameters.docs.container即可无缝替换默认容器。官方示例展示了 CSF 3JS/TS与 CSF NextReact、Vue 3、Angular、Web Components两种体系的完整写法源码 Docs.tsx 证实了container || DocsContainer的默认回退机制DocsContainer.tsx 则揭示了默认容器承载的上下文、主题、TOC、锚点滚动等基础设施。遵循自定义组件透传{...props}与{children}并渲染DocsContainer的推荐模式即可在保持全部默认能力的前提下为团队文档体系注入一致的品牌外壳与扩展逻辑。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考