Storybook Controls 面板按属性禁用控件table.disable 与 control:false 详解本文基于 Storybook 官方文档中 Controls 面板的Disable controls for specific properties特性展开系统讲解如何在单个组件属性上关闭 Controls 控件argTypes中table: { disable: true }的完整多框架用法React、Vue、Svelte、Angular、Web Components含 CSF 3 与 CSF Next 两种写法它与control: false的关键区别以及在 Story 级应用的更细粒度模式。文末结合仓库源码Title.tsx、ArgsTable.tsx说明该配置在 Manager 与 Docs 两处 UI 中的实际过滤逻辑帮助你在编写 Story 时做出正确的隐藏决策。一、背景为什么需要按属性禁用 ControlsControls 是 Storybook 中用于实时编辑 Story 属性args的官方 Addon它与 Docs 共用同一套渲染引擎——因此 Controls 面板本质上是一个内嵌的Controlsdoc block即 ArgsTable 的一种形态。这意味着每个属性在面板中对应一行行内同时包含可交互的控件输入框、下拉、颜色选择器等属性的文档信息描述、默认值、表格行。当你希望某个属性对使用者只读例如内部透传的id、调试用的__testMode或文档已单独说明的私有属性时就需要单独关掉这个属性的控件。Storybook 提供了两条正交的配置路径配置位置写法效果argTypes.foo.table.disabletable: { disable: true }从 Controls 面板 UI 中完全移除该属性的控件行同时从文档表格中移除该属性行argTypes.foo.controlcontrol: false保留文档行描述/默认值仍展示但该行没有可交互控件两条路径都定义在 Story 文件的默认导出meta中且都可以在单个 Story 上覆盖与 decorators 等其它 Storybook 特性相同的meta 定义、story 覆盖层级模式。二、禁用单个属性控件table.disable: true下面的示例都针对一个想从 UI 中移除的属性foo来自官方文档代码片段 component-story-disable-controls.md并按框架整理。React / 通用 TypeScriptCSF 3// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Meta } from storybook/your-framework; import { YourComponent } from ./YourComponent; const meta { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, } satisfies Metatypeof YourComponent; export default meta;要点argTypes.foo只写table.disable不写control、options等其它字段satisfies Metatypeof YourComponent提供类型检查但不丢失字面量类型是 TS 项目推荐的声明方式。JavaScript 项目无 TS的等价写法import { YourComponent } from ./YourComponent; export default { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, };Vueimport type { Meta } from storybook/your-framework; import YourComponent from ./YourComponent.vue; const meta { component: YourComponent, argTypes: { foo: { table: { disable: true }, }, }, } satisfies Metatypeof YourComponent; export default meta;Angularimport type { Meta } from storybook/angular; import { YourComponent } from ./your-component.component; const meta: MetaYourComponent { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, }; export default meta;SvelteSvelte 框架下既有传统的 CSF 3 文件式写法也有 Svelte CSF 的script module写法// Replace your-framework with svelte-vite or sveltekit import type { Meta } from storybook/your-framework; import YourComponent from ./YourComponent.svelte; const meta { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, } satisfies Metatypeof YourComponent; export default meta;script module import { defineMeta } from storybook/addon-svelte-csf; import YourComponent from ./YourComponent.svelte; const { Story } defineMeta({ component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, }); /scriptWeb ComponentsWeb Components 没有 docgencomponent直接写标签名字符串export default { component: your-component, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, };import type { Meta } from storybook/web-components-vite; const meta: Meta { component: your-component, argTypes: { foo: { table: { disable: true, }, }, }, }; export default meta;CSF Next实验语法下的等价写法在采用 CSF Next 实验特性官方代码块标注为 CSF Next 的项目中meta 不再使用export default而是通过preview.meta()工厂函数生成配置结构完全一致import preview from ../.storybook/preview; import { YourComponent } from ./YourComponent; const meta preview.meta({ component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, });Vue / Svelte / Web Components 的 CSF Next 版本写法相同只是component字段按各自框架填组件引用或标签名。该语法当前仍处于实验阶段仓库文档中通过独立的 CSF Next 代码块 Tab 提供生产项目请确认所用 Storybook 版本支持后再切换。三、与 control: false 的关键区别保留文档行官方 controls 文档 在展示table.disable的 UI 变化后特别指出上面的示例同时把该属性的文档从表格中移除了。多数场景这样没问题但如果你希望没有控件、仍保留属性文档描述/默认值应改用control: false对应片段为 component-story-disable-controls-alt.mdimport type { Meta } from storybook/your-framework; import { YourComponent } from ./YourComponent; const meta { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { control: false, }, }, } satisfies Metatypeof YourComponent; export default meta;对比总结场景推荐写法属性完全不该出现在 Controls 面板 / Args 表格中内部属性、透传属性table: { disable: true }属性文档要保留例如说明该值由运行时注入但禁止手动修改control: false只针对某个 Story 生效其它 Story 仍可编辑在单个 Story 的argTypes中覆盖见下一节注意两者作用域table.disable影响的是 Controls 面板与 Docs 中 ArgsTable 的行级展示它不是运行时过滤——组件渲染时该属性依然会按 args 正常传入只是 UI 层不再展示对应的编辑行。四、在 Story 级应用同一模式与 decorators、parameters 等其它 Storybook 属性一致argTypes支持meta 定义、story 覆盖的层级结构因此可以在单个 Story 上做更细粒度的禁用import type { Meta, StoryObj } from storybook/your-framework; import { YourComponent } from ./YourComponent; const meta: Metatypeof YourComponent { component: YourComponent, }; export default meta; type Story StoryObjtypeof meta; // 只在 Debug 这个 Story 中隐藏 foo 的控件 export const Debug: Story { argTypes: { foo: { table: { disable: true }, }, }, };这样Primary等其它 Story 仍能看到并编辑foo而DebugStory 中该行被移除适合某个变体中该属性无意义的情况。五、源码级实现table.disable 在哪里被消费仓库源码印证了第二节的两种行为差异核心过滤点有两处Manager 侧 Controls 面板标题的计数。Controls 面板头部会显示当前可用控件数量其计数逻辑在 Title.tsxconst rows useArgTypes(); const controlsCount Object.values(rows).filter( (argType) argType?.control !argType?.table?.disable ).length;即一个 argType 被计入控件必须同时满足显式拥有controlcontrol为false时argType.control为 falsy自然被排除且table.disable不为真。这解释了为什么table.disable的属性从面板计数与 UI 中消失而control: false的属性只是没控件但行还在。Docs 侧 ArgsTable 的行过滤。Docs 的 ArgsTable 在渲染行时执行 ArgsTable.tsx 中的过滤(row) !row?.table?.disable safeIncludeConditionalArg(row, args || {}, globals || {})这里table.disable为真的行被直接剔除与 Controls 面板的title.disable表现一致而同一表达式中的safeIncludeConditionalArg则处理 Controls 的if条件控制见 controls 文档Conditional controls小节说明属性行过滤是 Controls 与 Docs 共用的引擎能力。可以推断由于两处过滤共享同一份 argTypes 解析结果table.disable的效果在 Controls 面板与 Docs 页面的 Args 表格中是同步的——这正是官方文档用一段视频展示UI 前后变化的原因文档中引用的演示视频为 addon-controls-disable-specific-prop-optimized.mp4。六、相关能力include/exclude 过滤与排序如果需求是隐藏一大批属性而非单个属性controls 文档 在 Filtering controls 小节提供了更高层的controls参数方案可选的include/exclude字段接受字符串数组或正则表达式可全局或按 Story 定义。两者可组合使用——include/exclude处理批量过滤table.disable/control: false处理精确到单个属性的展示控制。此外同一文档还说明 Controls 的排序策略默认按 args 数据处理顺序none也支持按属性名字母序alpha或必填项优先requiredFirst可在 meta 的controls参数中配置。七、小结移除某属性在 Controls 面板中的控件行与文档行argTypes.foo.table.disable true只移除控件、保留属性文档argTypes.foo.control false需要在单个 Story 生效把同样的argTypes片段写在 Story 导出上批量过滤用controls参数的include/exclude字符串数组或正则单属性精确控制用上述两种 argTypes 写法源码层面table.disable分别在 Title.tsx 的控件计数与 ArgsTable.tsx 的行过滤中被消费验证了 Controls 与 Docs 共用行级过滤机制。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Storybook Controls 面板按属性禁用控件table.disable 与 control:false 详解本文基于 Storybook 官方文档中 Controls 面板的Disable controls for specific properties特性展开系统讲解如何在单个组件属性上关闭 Controls 控件argTypes中table: { disable: true }的完整多框架用法React、Vue、Svelte、Angular、Web Components含 CSF 3 与 CSF Next 两种写法它与control: false的关键区别以及在 Story 级应用的更细粒度模式。文末结合仓库源码Title.tsx、ArgsTable.tsx说明该配置在 Manager 与 Docs 两处 UI 中的实际过滤逻辑帮助你在编写 Story 时做出正确的隐藏决策。一、背景为什么需要按属性禁用 ControlsControls 是 Storybook 中用于实时编辑 Story 属性args的官方 Addon它与 Docs 共用同一套渲染引擎——因此 Controls 面板本质上是一个内嵌的Controlsdoc block即 ArgsTable 的一种形态。这意味着每个属性在面板中对应一行行内同时包含可交互的控件输入框、下拉、颜色选择器等属性的文档信息描述、默认值、表格行。当你希望某个属性对使用者只读例如内部透传的id、调试用的__testMode或文档已单独说明的私有属性时就需要单独关掉这个属性的控件。Storybook 提供了两条正交的配置路径配置位置写法效果argTypes.foo.table.disabletable: { disable: true }从 Controls 面板 UI 中完全移除该属性的控件行同时从文档表格中移除该属性行argTypes.foo.controlcontrol: false保留文档行描述/默认值仍展示但该行没有可交互控件两条路径都定义在 Story 文件的默认导出meta中且都可以在单个 Story 上覆盖与 decorators 等其它 Storybook 特性相同的meta 定义、story 覆盖层级模式。二、禁用单个属性控件table.disable: true下面的示例都针对一个想从 UI 中移除的属性foo来自官方文档代码片段 component-story-disable-controls.md并按框架整理。React / 通用 TypeScriptCSF 3// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Meta } from storybook/your-framework; import { YourComponent } from ./YourComponent; const meta { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, } satisfies Metatypeof YourComponent; export default meta;要点argTypes.foo只写table.disable不写control、options等其它字段satisfies Metatypeof YourComponent提供类型检查但不丢失字面量类型是 TS 项目推荐的声明方式。JavaScript 项目无 TS的等价写法import { YourComponent } from ./YourComponent; export default { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, };Vueimport type { Meta } from storybook/your-framework; import YourComponent from ./YourComponent.vue; const meta { component: YourComponent, argTypes: { foo: { table: { disable: true }, }, }, } satisfies Metatypeof YourComponent; export default meta;Angularimport type { Meta } from storybook/angular; import { YourComponent } from ./your-component.component; const meta: MetaYourComponent { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, }; export default meta;SvelteSvelte 框架下既有传统的 CSF 3 文件式写法也有 Svelte CSF 的script module写法// Replace your-framework with svelte-vite or sveltekit import type { Meta } from storybook/your-framework; import YourComponent from ./YourComponent.svelte; const meta { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, } satisfies Metatypeof YourComponent; export default meta;script module import { defineMeta } from storybook/addon-svelte-csf; import YourComponent from ./YourComponent.svelte; const { Story } defineMeta({ component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, }); /scriptWeb ComponentsWeb Components 没有 docgencomponent直接写标签名字符串export default { component: your-component, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, };import type { Meta } from storybook/web-components-vite; const meta: Meta { component: your-component, argTypes: { foo: { table: { disable: true, }, }, }, }; export default meta;CSF Next实验语法下的等价写法在采用 CSF Next 实验特性官方代码块标注为 CSF Next 的项目中meta 不再使用export default而是通过preview.meta()工厂函数生成配置结构完全一致import preview from ../.storybook/preview; import { YourComponent } from ./YourComponent; const meta preview.meta({ component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { table: { disable: true, }, }, }, });Vue / Svelte / Web Components 的 CSF Next 版本写法相同只是component字段按各自框架填组件引用或标签名。该语法当前仍处于实验阶段仓库文档中通过独立的 CSF Next 代码块 Tab 提供生产项目请确认所用 Storybook 版本支持后再切换。三、与 control: false 的关键区别保留文档行官方 controls 文档 在展示table.disable的 UI 变化后特别指出上面的示例同时把该属性的文档从表格中移除了。多数场景这样没问题但如果你希望没有控件、仍保留属性文档描述/默认值应改用control: false对应片段为 component-story-disable-controls-alt.mdimport type { Meta } from storybook/your-framework; import { YourComponent } from ./YourComponent; const meta { component: YourComponent, argTypes: { // foo is the property we want to remove from the UI foo: { control: false, }, }, } satisfies Metatypeof YourComponent; export default meta;对比总结场景推荐写法属性完全不该出现在 Controls 面板 / Args 表格中内部属性、透传属性table: { disable: true }属性文档要保留例如说明该值由运行时注入但禁止手动修改control: false只针对某个 Story 生效其它 Story 仍可编辑在单个 Story 的argTypes中覆盖见下一节注意两者作用域table.disable影响的是 Controls 面板与 Docs 中 ArgsTable 的行级展示它不是运行时过滤——组件渲染时该属性依然会按 args 正常传入只是 UI 层不再展示对应的编辑行。四、在 Story 级应用同一模式与 decorators、parameters 等其它 Storybook 属性一致argTypes支持meta 定义、story 覆盖的层级结构因此可以在单个 Story 上做更细粒度的禁用import type { Meta, StoryObj } from storybook/your-framework; import { YourComponent } from ./YourComponent; const meta: Metatypeof YourComponent { component: YourComponent, }; export default meta; type Story StoryObjtypeof meta; // 只在 Debug 这个 Story 中隐藏 foo 的控件 export const Debug: Story { argTypes: { foo: { table: { disable: true }, }, }, };这样Primary等其它 Story 仍能看到并编辑foo而DebugStory 中该行被移除适合某个变体中该属性无意义的情况。五、源码级实现table.disable 在哪里被消费仓库源码印证了第二节的两种行为差异核心过滤点有两处Manager 侧 Controls 面板标题的计数。Controls 面板头部会显示当前可用控件数量其计数逻辑在 Title.tsxconst rows useArgTypes(); const controlsCount Object.values(rows).filter( (argType) argType?.control !argType?.table?.disable ).length;即一个 argType 被计入控件必须同时满足显式拥有controlcontrol为false时argType.control为 falsy自然被排除且table.disable不为真。这解释了为什么table.disable的属性从面板计数与 UI 中消失而control: false的属性只是没控件但行还在。Docs 侧 ArgsTable 的行过滤。Docs 的 ArgsTable 在渲染行时执行 ArgsTable.tsx 中的过滤(row) !row?.table?.disable safeIncludeConditionalArg(row, args || {}, globals || {})这里table.disable为真的行被直接剔除与 Controls 面板的title.disable表现一致而同一表达式中的safeIncludeConditionalArg则处理 Controls 的if条件控制见 controls 文档Conditional controls小节说明属性行过滤是 Controls 与 Docs 共用的引擎能力。可以推断由于两处过滤共享同一份 argTypes 解析结果table.disable的效果在 Controls 面板与 Docs 页面的 Args 表格中是同步的——这正是官方文档用一段视频展示UI 前后变化的原因文档中引用的演示视频为 addon-controls-disable-specific-prop-optimized.mp4。六、相关能力include/exclude 过滤与排序如果需求是隐藏一大批属性而非单个属性controls 文档 在 Filtering controls 小节提供了更高层的controls参数方案可选的include/exclude字段接受字符串数组或正则表达式可全局或按 Story 定义。两者可组合使用——include/exclude处理批量过滤table.disable/control: false处理精确到单个属性的展示控制。此外同一文档还说明 Controls 的排序策略默认按 args 数据处理顺序none也支持按属性名字母序alpha或必填项优先requiredFirst可在 meta 的controls参数中配置。七、小结移除某属性在 Controls 面板中的控件行与文档行argTypes.foo.table.disable true只移除控件、保留属性文档argTypes.foo.control false需要在单个 Story 生效把同样的argTypes片段写在 Story 导出上批量过滤用controls参数的include/exclude字符串数组或正则单属性精确控制用上述两种 argTypes 写法源码层面table.disable分别在 Title.tsx 的控件计数与 ArgsTable.tsx 的行过滤中被消费验证了 Controls 与 Docs 共用行级过滤机制。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
