Storybooklayout参数全局配置指南在 .storybook/preview 中掌控组件画布布局【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 的layout参数用于控制预览画布canvas中故事的呈现方式支持centered、fullscreen、padded三种取值。本指南以仓库中的配置片段 storybook-preview-layout-param.md 为骨架系统讲解如何在.storybook/preview项目级配置中全局设置该参数并结合 WebView.ts 源码剖析其底层实现原理。读完本文你将掌握layout参数的全部取值语义、CSF 3 与 CSF Next实验性两套语法下的配置方法以及项目级、组件级、故事级三级继承规则。layout参数是什么layout是 Storybook 官方提供的内置参数parameter之一专门用于定义故事在预览画布中的布局方式。依据 parameters.mdx 的权威说明它的类型与默认值如下类型centered | fullscreen | padded默认值padded语义centered将故事内容在画布中水平、垂直居中显示padded默认为故事四周添加内边距fullscreen无内边距、原样展示故事通常用于需要占满整个画布的场景如弹窗、整页组件。值得注意的是Storybook 直接接受的参数数量有限layout正是其中被官方一等支持的内置参数之一因此它不依赖任何第三方 addon开箱即用。在 preview 中全局配置 layout原文档核心内容当你希望整个 Storybook 项目中的所有故事都采用同一种布局时应把layout配置在.storybook/preview.js或preview.ts文件的parameters中。这是项目级project level配置会作用于全部故事。原片段提供了 CSF 3 与 CSF Next 两代语法、覆盖多个渲染框架的完整示例以下逐一展开。CSF 3面向所有框架的通用写法renderercommon的片段适用于绝大多数框架react-vite、nextjs、vue3-vite 等。JavaScript 版本无需类型标注export default { parameters: { layout: centered, }, };TypeScript 版本需要从当前框架包导入Preview类型示例中的storybook/your-framework需替换为实际使用的框架例如storybook/react-vite、storybook/nextjs、storybook/vue3-vite等并借助satisfies之外的Preview类型标注获得完整的参数提示// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Preview } from storybook/your-framework; const preview: Preview { parameters: { layout: centered, }, }; export default preview;CSF Next实验性definePreview 统一入口CSF Next 是 Storybook 正在演进的新一代 CSF 语法通过框架包导出的definePreview()函数集中声明项目级配置。仓库中同一组片段覆盖了 React、Vue、Angular、Web Components 四个渲染器JS 与 TS 各一份。Reactrendererreact例如storybook/react-vite、storybook/nextjs、storybook/nextjs-vite// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { definePreview } from storybook/your-framework; export default definePreview({ parameters: { layout: centered, }, });// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { definePreview } from storybook/your-framework; export default definePreview({ parameters: { layout: centered, }, });Vue 3storybook/vue3-viteimport { definePreview } from storybook/vue3-vite; export default definePreview({ parameters: { layout: centered, }, });import { definePreview } from storybook/vue3-vite; export default definePreview({ parameters: { layout: centered, }, });Angularstorybook/angularimport { definePreview } from storybook/angular; export default definePreview({ parameters: { layout: centered, }, });Web Componentsstorybook/web-components-viteimport { definePreview } from storybook/web-components-vite; export default definePreview({ parameters: { layout: centered, }, });import { definePreview } from storybook/web-components-vite; export default definePreview({ parameters: { layout: centered, }, });无论是 CSF 3 的默认导出对象还是 CSF Next 的definePreview其parameters.layout的书写位置与含义完全一致只是声明方式不同。源码级原理layout 如何被应用到画布layout参数并非魔法其底层实现位于 code/core/src/preview-api/modules/preview-web/WebView.ts 中。核心逻辑如下。布局类映射表WebView.ts 第 31-36 行 定义了参数值与 CSS 类的映射const layoutClassMap { centered: sb-main-centered, fullscreen: sb-main-fullscreen, padded: sb-main-padded, } as const; type Layout keyof typeof layoutClassMap | none;从类型定义可以看出合法取值在centered | fullscreen | padded之外还额外允许一个none——它表示“不应用任何布局类”用于移除画布上残留的布局样式。切换逻辑 applyLayoutWebView.ts 第 115-129 行 的applyLayout是应用布局的核心方法applyLayout(layout: Layout padded) { if (layout none) { document.body.classList.remove(this.currentLayoutClass!); this.currentLayoutClass null; return; } this.checkIfLayoutExists(layout); const layoutClass layoutClassMap[layout]; document.body.classList.remove(this.currentLayoutClass!); document.body.classList.add(layoutClass); this.currentLayoutClass layoutClass; }其工作原理可概括为三点作用目标是document.bodyStorybook 通过向body元素添加/移除sb-main-centered、sb-main-fullscreen、sb-main-padded这类 CSS 类来切换布局这些类的样式由 Storybook 内置样式表提供sb-main-padded添加内边距、sb-main-centered配合 flex 实现居中、sb-main-fullscreen无内边距幂等切换每次应用新布局前先移除上一次记录的currentLayoutClass避免多个布局类叠加冲突默认值兜底方法签名默认padded与文档所述默认值一致——即使某层参数未显式设置画布也会保持 padded 布局。调用时机与继承applyLayout在 prepareForStory 中被调用每当一个故事准备渲染时story.parameters.layout会被取出并应用。由于 Storybook 的参数解析遵循project → meta → story的继承合并规则最终进入prepareForStory的story.parameters.layout已经是三级参数合并后的结果这也是“在 preview 中全局设置、局部可覆盖”得以成立的根本原因。非法取值的防御checkIfLayoutExists 会对不存在的布局名输出警告日志The desired layout: xxx is not a valid option. The possible options are: centered, fullscreen, padded, none.即传入未知值不会导致崩溃而是回退到默认行为并打印提示方便排查拼写错误。从全局到局部三级参数继承实践在 preview 中全局配置适合统一基线但真实项目中往往需要局部差异。仓库中的两个兄弟片段展示了另外两个层级组件级meta在Button.stories.ts的默认导出meta中配置parameters.layout作用于该组件下的全部故事参见 storybook-component-layout-param.md故事级story在单个故事的parameters中配置只影响这一个故事参见 storybook-story-layout-param.md。组件级示例meta 中设置import type { Meta } from storybook/your-framework; import { Button } from ./Button; const meta { component: Button, // Sets the layout parameter component wide. parameters: { layout: centered, }, } satisfies Metatypeof Button; export default meta;故事级示例story 中设置import type { Meta, StoryObj } from storybook/your-framework; import { Button } from ./Button; const meta { component: Button, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; export const WithLayout: Story { parameters: { layout: centered, }, };Svelte CSF 中则通过Story parameters{{ layout: centered }} /或defineMeta的parameters声明写法与 CSF 3 一一对应。使用建议与注意事项选择合理的默认值大多数组件库项目建议在 preview 中保持默认padded或全局centered只有弹窗、整页、背景铺满类组件才在故事级单独使用fullscreen避免大面积组件被迫在受限画布中展示。Docs 视图的特殊性在 docs 视图下Storybook 会强制以fullscreen方式渲染文档参见 prepareForDocs 中applyLayout(fullscreen)的调用这是文档模式的既定行为无需也不应通过参数覆盖。按层级就近覆盖遵循 project → meta → story 的继承链在 preview 中设全局基线在 meta 中设组件基线在 story 中做单点微调避免到处重复书写。留意实验性语法CSF NextdefinePreview目前仍处于实验阶段代码片段以 标注生产项目建议以 CSF 3 写法为准待其稳定后再迁移。小结layout参数是 Storybook 控制故事呈现方式的核心内置参数。通过在.storybook/preview.js|ts中配置parameters.layout即可为整个项目设定统一的画布布局基线配合组件级与故事级的覆盖又能灵活适配单个组件的特殊需求。其实现依托 WebView.ts 中对body的布局类切换语义清晰、可预测是搭建高质量组件工作坊时最常打交道的参数之一。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考