Storybook Controls 面板展开模式（expanded）配置完全指南：从 Preview 参数到源码原理

Storybook Controls 面板展开模式expanded配置完全指南从 Preview 参数到源码原理【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读Controls 是 Storybook 中最常用的调试工具之一而parameters.controls.expanded决定了 Controls 面板是只展示紧凑的可编辑控件还是同时内嵌完整的属性文档含描述与默认值。本文以docs/_snippets/storybook-preview-expanded-controls.md为骨架系统讲解在 CSF 3 与 CSF Next 两种语法下、横跨 React/Vue/Angular/Web Components 等主流渲染器时如何全局开启 expanded 模式并结合官方文档 docs/essentials/controls.mdx 与仓库源码剖析其工作原理、覆盖规则与最佳实践读完后你将能精准控制 Controls 面板的信息密度并能在组件级、故事级灵活覆盖这一全局配置。一、expanded参数是什么Controls 与 Docs 共用引擎的关键开关Storybook Controls 为每个 story 的 args 自动生成图形化交互控件。默认情况下expanded: falseControls 面板只展示每一行的编辑控件本体界面紧凑而一旦将expanded设为true面板会同时渲染完整的属性文档——包括每个 arg 的描述description与默认值default value。这一能力源于 Controls 与 Storybook Docs 共用同一套渲染引擎按官方文档 docs/essentials/controls.mdx 所述开启expanded后相当于在 Controls 面板中内嵌了一个完整的Controls文档块doc block。也就是说expanded 模式下每个属性都从仅一行控件扩展为文档表格 控件的完整形态适合在开发调试时快速核对属性的含义与缺省行为也方便向团队展示组件 API。从源码角度可以印证这一机制code/addons/docs/src/blocks/blocks/types.ts中定义了Controls文档块的类型其属性中即包含expanded?: boolean字段这说明expanded是文档块与 Controls 面板共享的同一份参数契约。仓库中 addons/docs/src/blocks/examples/ControlsParameters.tsx 及其配套 stories 文件正是用真实 story 演示Controls文档块如何消费这些参数。二、全局开启 expanded.storybook/preview配置详解expanded属于controls命名空间下的参数可以在全局项目级、**组件级meta或故事级story**三个层面设置。全局开启需要写入项目根目录的.storybook/preview配置文件。2.1 CSF 3 语法当前主流写法CSF 3 时代preview 文件通过export default导出一个包含parameters的配置对象。对于使用 JS 的项目文件名.storybook/preview.js或.jsxexport default { parameters: { controls: { expanded: true }, }, };对于 TypeScript 项目文件名.storybook/preview.ts或.tsx强烈建议使用框架自带的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: { controls: { expanded: true }, }, }; export default preview;其中storybook/your-framework需要替换为实际渲染器包名例如storybook/react-vite、storybook/nextjs、storybook/vue3-vite、storybook/angular等。Preview类型会约束parameters.controls的结构expanded: true即声明开启展开模式。2.2 CSF Next 语法 实验性definePreview在 Storybook 的下一代 CSF仓库中标记为 CSF Next 中preview 配置改为通过definePreview()工厂函数声明。这一写法在仓库的 CLI 初始化流程中已被采用例如 code/core/src/cli/skills/content/setup-prompts/pattern-copy-play.ts 与 setup.ts 生成的 preview 模板均为import { definePreview } from storybook/preview; export default definePreview({ ... })可见该 API 正逐步成为官方推荐的 preview 声明方式。React 系渲染器react-vite、nextjs、nextjs-vite 等.storybook/preview.tsx// 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: { controls: { expanded: true }, }, });JS 版本.storybook/preview.jsx// 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: { controls: { expanded: true }, }, });Vue 3 渲染器.storybook/preview.tsimport { definePreview } from storybook/vue3-vite; export default definePreview({ parameters: { controls: { expanded: true }, }, });JS 版本.storybook/preview.jsimport { definePreview } from storybook/vue3-vite; export default definePreview({ parameters: { controls: { expanded: true }, }, });Angular 渲染器.storybook/preview.tsimport { definePreview } from storybook/angular; export default definePreview({ parameters: { controls: { expanded: true }, }, });Web Components 渲染器.storybook/preview.tsimport { definePreview } from storybook/web-components-vite; export default definePreview({ parameters: { controls: { expanded: true }, }, });JS 版本.storybook/preview.jsimport { definePreview } from storybook/web-components-vite; export default definePreview({ parameters: { controls: { expanded: true }, }, });注意CSF Next 的definePreview写法目前仍标注为实验性。生产项目若追求稳定可优先使用 2.1 节的 CSF 3export default写法两者的parameters结构完全一致切换成本极低。三、expanded 的实际效果与覆盖规则3.1 开启后的界面形态开启expanded后Controls 面板会从纯控件列表变为属性文档表 控件的混合形态每个属性行展示名称、类型、描述与默认值正下方才是可交互的编辑控件。官方文档 docs/essentials/controls.mdx 给出了开启后的界面示意该截图对应docs/_assets/essentials/addon-controls-expanded.png。由于expanded与 Docs 文档块共用渲染引擎其描述与默认值的呈现方式也可以像文档块一样自定义参见官方文档中关于mapping与control.labels的说明见 docs/essentials/controls.mdx。3.2 全局 vs 组件级 vs 故事级expanded的默认值为false见 docs/essentials/controls.mdx 中expanded参数的 API 说明。在.storybook/preview中开启后它作用于整个 Storybook 的所有 story。若某些组件或单个 story 需要不同的展示密度可以沿用 Storybook 的参数合并规则逐级覆盖——例如在某个 meta 的parameters.controls中设expanded: false即可关闭该组件下的展开模式实现全局展开、局部紧凑的精细控制。这一低层覆盖高层的模式与controls命名空间下的其他参数如disable、sort、include/exclude一致官方文档明确指出disable参数在项目级设为true后仍可在 meta 或 story 级设false重新启用见 docs/essentials/controls.mdxexpanded遵循同样的覆盖语义。四、controls参数族速查expanded 的邻居们expanded只是parameters.controls命名空间下的参数之一。理解整个参数族有助于做出更合理的组合决策以下是官方文档 docs/essentials/controls.mdx 中列出的全部参数参数类型默认值作用expandedbooleanfalse在 Controls 面板展示每个属性的完整文档描述 默认值disableboolean—关闭 Controls 行为常用于在 meta/story 级重新启用includestring[] \| RegExp—仅显示名字匹配的属性控件excludestring[] \| RegExp—排除名字匹配的属性控件sortnone \| alpha \| requiredFirstnone控件排序处理顺序 / 按名称字母序 / 必填优先presetColors(string \| { color: string; title?: string })[]—为 color 控件预置色板disableSaveFromUIbooleanfalse禁止从 Controls 面板直接创建/编辑 story典型组合示例需要展开 必填参数优先 只显示核心属性的高密度调试面板时可以在 preview 中这样声明export default { parameters: { controls: { expanded: true, sort: requiredFirst, include: [/^[a-z]/i], // 仅保留以字母开头的属性示例用法可按需调整 }, }, };五、相关阅读与进一步探索完整的 Controls 指南含控件类型表、argTypes注解、条件控件、疑难排查docs/essentials/controls.mdxControls文档块 APIexpanded 模式内嵌的渲染引擎docs/api/doc-blocks/doc-block-controls.mdx参数Parameters体系的通用概念docs/writing-stories/parameters.mdxargTypes详解如何为单个属性定制控件类型与文档docs/api/arg-types.mdx仓库中的Controls文档块类型定义code/addons/docs/src/blocks/blocks/types.tsCSF NextdefinePreview的实际用法模板CLI 初始化生成code/core/src/cli/skills/content/setup-prompts/setup.ts结语parameters.controls.expanded是 Storybook Controls 面板最直观的信息密度开关一行配置即可让每个属性从孤立的控件变成带描述与默认值的完整文档条目且与 Docs 文档块共用引擎、支持全局到 story 的逐级覆盖。无论你使用 CSF 3 的export default还是实验性的definePreview也无论你基于 React、Vue、Angular 还是 Web Components配置方式都保持高度一致可以无缝迁移。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考