Storybook Autodocs 主题覆盖为自动生成的文档页定制 Light / Dark 主题【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook Autodocs 生成的文档页默认跟随内置的light与dark两套 UI 主题。若你的组件库、设计系统或团队规范要求文档呈现与既有视觉一致可在.storybook/preview.js|ts中通过docs.theme参数直接覆盖主题。本指南基于 Storybook 官方文档与仓库源码完整演示如何在 CSF 3 与 CSF Next 两种写法下覆盖 Autodocs 默认主题并深入讲解ensure、ThemeVars与DocsContainer的底层实现帮助你按品牌色、字号或深色模式精确定制文档外观。在 preview 中覆盖 Autodocs 默认主题Storybook 为 UI 提供了两套内置主题light和dark定义于 light.ts 与 dark.ts。官方文档在 autodocs.mdx 中说明文档页默认独立于主 UI 使用自己的主题你可以通过 Storybook UI 配置文件.storybook/preview.js|ts更新并应用它。核心做法是在parameters.docs上声明theme属性// .storybook/preview.js import { themes, ensure } from storybook/theming; export default { parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { theme: ensure(themes.dark), // The replacement theme to use }, }, };对 TypeScript 用户需从框架包如react-vite、nextjs、vue3-vite导入Preview类型以获取类型提示// .storybook/preview.ts import type { Preview } from storybook/your-framework; // 替换为实际框架如 react-vite、nextjs、vue3-vite 等 import { themes, ensure } from storybook/theming; const preview: Preview { parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { theme: ensure(themes.dark), // The replacement theme to use }, }, }; export default preview;官方文档autodocs.mdx指出docs.theme需要包裹在ensure()中——这是确保主题对象结构完整、缺失字段回退为默认值的推荐写法下文会解释其必要性。CSF Next 写法CSF Next 是 Storybook 新一代的 preview 写法通过definePreview替代默认导出。官方文档同一节提供了对应变体以 React 为例// .storybook/preview.tsx import { definePreview } from storybook/your-framework; // 例如 react-vite、nextjs、nextjs-vite import addonDocs from storybook/addon-docs; import { ensure, themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, docs: { theme: ensure(themes.dark), // The replacement theme to use }, }, });Vue 3、Angular 与 Web Components 的写法结构一致只需将definePreview的导入源替换为对应框架包// .storybook/preview.ts —— Vue 3 import { definePreview } from storybook/vue3-vite; import addonDocs from storybook/addon-docs; import { ensure, themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { /* ... */ docs: { theme: ensure(themes.dark), }, }, });// .storybook/preview.ts —— Angular import { definePreview } from storybook/angular;// .storybook/preview.ts —— Web Components import { definePreview } from storybook/web-components-vite;非 TS 项目如 JSX 与纯 JS同样支持 CSF Next对应代码可见原文档完整示例storybook-preview-auto-docs-override-theme.md。ensure保证主题对象始终完整可用ensure是 Storybook 主题系统的关键函数定义于 ensure.tsexport const ensure (input: ThemeVars): StorybookTheme { if (!input) { return convert(light); } const missing deletedDiff(light, input); if (Object.keys(missing).length) { logger.warn( dedent Your theme is missing properties, you should update your theme! theme-data missing: , missing ); } return convert(input); };从源码可确认ensure的行为当传入为空值时回退到convert(light)即默认浅色主题当传入的主题对象缺少字段时与light做deletedDiff对比会在控制台输出Your theme is missing properties警告指出缺失的theme-data最终通过convert()将ThemeVars转为 Storybook 组件可消费的完整StorybookTheme。因此ensure(themes.dark)不只是“包一层”它同时完成校验、警告与转换保证docs.theme一定是一个结构完整的主题对象。这也是官方文档在覆盖主题时统一使用ensure的原因。ThemeVars主题对象的结构契约ThemeVars是主题输入的接口契约定义于 types.ts。它由两部分组成ThemeVarsBasebase: light | dark声明主题基准ThemeVarsColors完整的颜色与字体变量包括品牌色、UI 背景、字体、文本色、工具栏色与表单色等 20 余个字段。其中关键字段说明以 dark.ts 的实际值为例字段含义dark 主题示例值colorPrimary品牌主色Storybook 珊瑚色#FF4785colorSecondary品牌次色#479DFFappBg/appContentBg应用背景与内容背景#1B1C1D/#222325appBorderRadiusUI 圆角4fontBase/fontCode正文字体与等宽字体继承typography.fonts.base/monotextColor/textMutedColor正文色与弱化文本色#C9CCCF/#95999DbarBg/barSelectedColor工具栏背景与选中色#222325/#479DFFinputBg/inputBorder输入控件背景与边框#1B1C1D/hsl(0 0% 100% / 0.1)若需品牌化文档外观你可以基于ThemeVarsPartial自定义主题对象再交给ensure()补全例如import { ensure } from storybook/theming; const brandTheme { base: light as const, colorPrimary: #7B1FA2, colorSecondary: #5E35B1, appContentBg: #FAFAFA, textColor: #212121, brandTitle: My Design System, }; // 将自定义主题传入 docs.theme docs: { theme: ensure(brandTheme) },从参数到渲染docs.theme的底层消费链路docs.theme并非魔法它有明确的消费链路可从源码逐层确认类型声明addon-docs 的 types.ts 中DocsParameters显式声明theme?: ThemeVars并注明“Override the default theme”Docs 组件取值Docs.tsx 将docsParameter.theme传给Container默认即DocsContainerDocsContainer 应用主题DocsContainer.tsx 内部使用ThemeProvider theme{ensureTheme(theme as ThemeVars)}包裹整个文档页面theme缺失时ensureTheme回退浅色主题。也就是说docs.theme最终通过ThemeProvider注入到文档页的所有组件Title、Subtitle、Description、Controls、Stories 等 Doc Blocks中实现全局统一换肤。作用域与注意事项全局生效在.storybook/preview.js|ts中声明后项目内所有 Autodocs 页面都会使用该主题若只需单个组件的文档换肤可在该 story 文件的 meta 中覆盖parameters.docs.themeensure缺一不可直接传themes.dark虽能工作但缺少缺失字段校验与结构转换官方文档统一推荐ensure()包裹文档与主 UI 独立主界面主题在.storybook/manager.js中通过addons.setConfig({ theme })配置文档页主题则独立配置于 preview参见 theming.md两者互不干扰兼容性CSF 3 与 CSF NextdefinePreview写法均支持JS、TS、TSX 项目均可直接套用CSF Next 需额外注册addonDocs()到addons数组。小结覆盖 Autodocs 主题只需三步从storybook/theming导入themes与ensure在.storybook/preview.js|ts的parameters.docs.theme中写入ensure(themes.dark)或自定义ThemeVars其余交给DocsContainer的ThemeProvider完成注入。若还需进一步微调文档样式可参考官方文档的 CSS escape hatches 与 MDX 组件覆盖 两级方案构建完整的品牌化文档体验。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
