控件

观看视频教程

Storybook 控件为您提供了一个图形用户界面，用于动态地与组件的参数进行交互，而无需编写代码。它在组件示例（“故事”）旁边创建一个插件面板，以便您可以实时编辑它们。

控件不需要对您的组件进行任何修改。控件的故事是

便捷的。基于 React/Vue/Angular 等组件自动生成控件。
可移植的。在文档、测试，甚至设计中重用您的交互式故事。
丰富的。自定义控件和交互式数据以满足您的确切需求。

要使用控件插件，您需要使用 args 编写您的故事。Storybook 将根据您的 args 以及它可以推断出的组件信息自动生成 UI 控件。不过，您可以使用 argTypes 进一步配置控件，请参见下文。

如果您的故事是较旧的 Storybook 6 之前的风格，请查看 args & 控件迁移指南，了解如何将现有故事转换为 args。

选择控件类型

默认情况下，Storybook 将根据每个 arg 的初始值选择一个控件。这对于特定的 arg 类型（例如，boolean 或 string）效果良好。要启用它们，请将 component 注解添加到您的故事文件的默认导出中，它将用于推断控件并自动生成与您的组件匹配的 argTypes，使用 react-docgen，这是一个用于 React 组件的文档生成器，它也包括对 TypeScript 的一流支持。

Button.stories.ts|tsx

import type { Meta } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;

例如，假设您的故事中有一个 variant arg，它应该是 primary 或 secondary

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Primary: Story = {
  args: {
    variant: 'primary',
  },
};

默认情况下，Storybook 将为 variant arg 渲染一个自由文本输入框

Essential addon Controls using a string

只要您在自动生成的文本控件中键入有效的字符串，它就可以工作。但是，考虑到组件仅接受 primary 或 secondary 作为变体，这并不是我们场景的最佳 UI。让我们用 Storybook 的单选按钮组件替换它。

我们可以通过为 variant 属性声明自定义 argType 来指定使用哪些控件。 ArgTypes 编码了 args 的基本元数据，例如 args 的名称、描述和 defaultValue。这些由 Storybook 文档自动填充。

ArgTypes 还可以包含用户可以覆盖的任意注解。由于 variant 是组件属性，因此让我们将该注解放在默认导出上。

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    variant: {
      options: ['primary', 'secondary'],
      control: { type: 'radio' },
    },
  },
};
 
export default meta;

ArgTypes 是一项强大的功能，可用于自定义故事的控件。有关更多信息，请参阅有关使用 argTypes 注解自定义控件的文档。

这将输入框替换为单选按钮组，以获得更直观的体验。

Essential Control addon with a radio group

自定义控件类型匹配器

控件可以根据 arg 的名称使用 regex 自动推断，但目前仅适用于颜色选择器和日期选择器控件。如果您使用 Storybook CLI 设置项目，它应该已在 .storybook/preview.js|ts 中自动创建了以下默认值

控件	默认正则表达式	描述
颜色	`/(background\|color)$/i`	将为匹配的 args 显示颜色选择器 UI
日期	`/Date$/`	将为匹配的 args 显示日期选择器 UI

如果您未使用 CLI 设置配置，或者想要定义自己的模式，请使用 controls 参数中的 matchers 属性

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};
 
export default preview;

完全自定义 args

到目前为止，我们仅使用了基于我们正在为其编写故事的组件自动生成的控件。如果我们正在编写复杂的故事，我们可能希望为不属于组件的 args 添加控件。例如，以下是如何使用 footer arg 来填充子组件

Page.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { Page } from './Page';
 
type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & { footer?: string };
 
const meta: Meta<PagePropsAndCustomArgs> = {
  component: Page,
  render: ({ footer, ...args }) => (
    <Page {...args}>
      <footer>{footer}</footer>
    </Page>
  ),
};
export default meta;
 
type Story = StoryObj<PagePropsAndCustomArgs>;
 
export const CustomFooter: Story = {
  args: {
    footer: 'Built with Storybook',
  },
};

默认情况下，Storybook 将为所有 args 添加控件，这些 args

从组件定义中推断出来如果您的框架支持它。
出现在您的故事的 args 列表中。

使用 argTypes，您可以更改每个控件的显示和行为。

处理复杂值

在处理非原始值时，您会注意到您会遇到一些限制。最明显的问题是并非每个值都可以表示为 URL 中 args 参数的一部分，从而失去了共享和深度链接到这种状态的能力。除此之外，管理器（例如，控件插件）和预览（您的故事）之间无法同步复杂值（如 JSX）。

处理此问题的一种方法是使用原始值（例如，字符串）作为 arg 值，并添加自定义 render 函数以在渲染之前将它们转换为其复杂的对应值。这不是最友好的方法（见下文），但肯定是灵活性最高的方法。

YourComponent.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { YourComponent } from './your-component';
 
const meta: Meta<typeof YourComponent> = {
  component: YourComponent,
  //👇 Creates specific argTypes with options
  argTypes: {
    propertyA: {
      options: ['Item One', 'Item Two', 'Item Three'],
      control: { type: 'select' }, // Automatically inferred when 'options' is defined
    },
    propertyB: {
      options: ['Another Item One', 'Another Item Two', 'Another Item Three'],
    },
  },
};
 
export default meta;
type Story = StoryObj<typeof YourComponent>;
 
const someFunction = (valuePropertyA, valuePropertyB) => {
  // Do some logic here
};
 
export const ExampleStory: Story = {
  render: (args) => {
    const { propertyA, propertyB } = args;
    //👇 Assigns the function result to a variable
    const someFunctionResult = someFunction(propertyA, propertyB);
 
    return <YourComponent {...args} someProperty={someFunctionResult} />;
  },
  args: {
    propertyA: 'Item One',
    propertyB: 'Another Item One',
  },
};

除非您需要函数灵活性，否则在渲染之前将原始值映射到复杂值的更简单方法是定义 mapping；此外，您可以指定 control.labels 来为您的复选框、单选按钮或选择输入配置自定义标签。

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
import { ArrowUp, ArrowDown, ArrowLeft, ArrowRight } from './icons';
 
const arrows = { ArrowUp, ArrowDown, ArrowLeft, ArrowRight };
 
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    arrow: {
      options: Object.keys(arrows), // An array of serializable values
      mapping: arrows, // Maps serializable option values to complex arg values
      control: {
        type: 'select', // Type 'select' is automatically inferred when 'options' is defined
        labels: {
          // 'labels' maps option values to string labels
          ArrowUp: 'Up',
          ArrowDown: 'Down',
          ArrowLeft: 'Left',
          ArrowRight: 'Right',
        },
      },
    },
  },
};
 
export default meta;

请注意，mapping 和 control.labels 都不必详尽无遗。如果当前选择的选项未列出，则按原样使用。

从控件创建和编辑故事

控件插件允许您直接从控件面板创建或编辑故事。

创建新故事

打开故事的控件面板并调整控件的值。然后将这些更改另存为新故事。

如果您正在处理尚没有任何故事的组件，则可以单击侧边栏中的 ➕ 按钮来搜索您的组件，并为您创建一个基本故事。

编辑故事

您还可以更新控件的值，然后将更改保存到故事中。故事文件的代码将为您更新。

禁用创建和编辑故事

如果您不想允许从控件面板创建或编辑故事，则可以通过在 .storybook/preview.js|ts 文件中的 parameters.controls 参数中将 disableSaveFromUI 参数设置为 true 来禁用此功能。

配置

控件插件可以通过两种方式配置

可以通过控件注解配置单个控件。
插件的外观可以通过参数配置。

注解

如上所示，您可以使用组件或故事的 argTypes 字段中的“control”注解来配置单个控件。下面是一个简化的示例和表格，其中包含所有可用的控件。

数据类型	控件	描述
boolean	`boolean`	提供一个切换开关，用于在可能的状态之间切换。 `argTypes: { active: { control: 'boolean' }}`
number	`number`	提供一个数字输入，以包含所有可能值的范围。 `argTypes: { even: { control: { type: 'number', min:1, max:30, step: 2 } }}`
	`range`	提供一个范围滑块组件，以包含所有可能的值。 `argTypes: { odd: { control: { type: 'range', min: 1, max: 30, step: 3 } }}`
object	`object`	提供一个基于 JSON 的编辑器组件来处理对象的值。也允许在原始模式下编辑。 `argTypes: { user: { control: 'object' }}`
array	`object`	提供一个基于 JSON 的编辑器组件来处理数组的值。也允许在原始模式下编辑。 `argTypes: { odd: { control: 'object' }}`
	`file`	提供一个文件输入组件，该组件返回 URL 数组。可以进一步自定义以接受特定的文件类型。 `argTypes: { avatar: { control: { type: 'file', accept: '.png' } }}`
enum	`radio`	根据可用选项提供一组单选按钮。 `argTypes: { contact: { control: 'radio', options: ['email', 'phone', 'mail'] }}`
	`inline-radio`	根据可用选项提供一组内联单选按钮。 `argTypes: { contact: { control: 'inline-radio', options: ['email', 'phone', 'mail'] }}`
	`check`	提供一组复选框组件，用于选择多个选项。 `argTypes: { contact: { control: 'check', options: ['email', 'phone', 'mail'] }}`
	`inline-check`	提供一组内联复选框组件，用于选择多个选项。 `argTypes: { contact: { control: 'inline-check', options: ['email', 'phone', 'mail'] }}`
	`select`	提供一个下拉列表组件来处理单值选择。 `argTypes: { age: { control: 'select', options: [20, 30, 40, 50] }}`
	`multi-select`	提供一个下拉列表，允许选择多个值。 `argTypes: { countries: { control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }}`
string	`text`	提供一个自由格式的文本输入框。 `argTypes: { label: { control: 'text' }}`
	`颜色`	提供一个颜色选择器组件来处理颜色值。可以额外配置以包含一组预设颜色。 `argTypes: { color: { control: { type: 'color', presetColors: ['red', 'green']} }}`
	`日期`	提供一个日期选择器组件来处理日期选择。 `argTypes: { startDate: { control: 'date' }}`

date 控件将在值更改时将日期转换为 UNIX 时间戳。这是一个已知的限制，将在未来的版本中修复。如果您需要表示实际日期，则需要更新故事的实现并将值转换为日期对象。

Gizmo.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Gizmo } from './Gizmo';
 
const meta: Meta<typeof Gizmo> = {
  component: Gizmo,
  argTypes: {
    canRotate: {
      control: 'boolean',
    },
    width: {
      control: { type: 'number', min: 400, max: 1200, step: 50 },
    },
    height: {
      control: { type: 'range', min: 200, max: 1500, step: 50 },
    },
    rawData: {
      control: 'object',
    },
    coordinates: {
      control: 'object',
    },
    texture: {
      control: {
        type: 'file',
        accept: '.png',
      },
    },
    position: {
      control: 'radio',
      options: ['left', 'right', 'center'],
    },
    rotationAxis: {
      control: 'check',
      options: ['x', 'y', 'z'],
    },
    scaling: {
      control: 'select',
      options: [10, 50, 75, 100, 200],
    },
    label: {
      control: 'text',
    },
    meshColors: {
      control: {
        type: 'color',
        presetColors: ['#ff0000', '#00ff00', '#0000ff'],
      },
    },
    revisionDate: {
      control: 'date',
    },
  },
};
 
export default meta;

数字数据类型将默认为 number 控件，除非提供其他配置。

参数

控件支持以下配置参数，可以是全局的，也可以是每个故事单独配置

显示每个属性的完整文档

由于控件是基于与 Storybook 文档相同的引擎构建的，因此它还可以使用 expanded 参数（默认为 false）在控件旁边显示属性文档。这意味着您可以在控件面板中嵌入完整的 Controls 文档块。描述和默认值渲染可以像文档块一样进行自定义。

要全局启用展开模式，请将以下内容添加到 .storybook/preview.js|ts

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    controls: { expanded: true },
  },
};
 
export default preview;

这是结果 UI 的外观

Controls addon expanded

指定初始预设颜色色板

对于 color 控件，您可以在 argTypes 中的 control 上，或作为 controls 命名空间下的参数，指定 presetColors 数组

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    controls: {
      presetColors: [{ color: '#ff4785', title: 'Coral' }, 'rgba(0, 159, 183, 1)', '#fe4a49'],
    },
  },
};
 
export default preview;

颜色预设可以定义为具有 color 和 title 的对象或简单的 CSS 颜色字符串。这些将作为色板在颜色选择器中提供。当您将鼠标悬停在颜色色板上时，您将能够看到其标题。如果未指定标题，则默认设置为最接近的 CSS 颜色名称。

过滤控件

在特定情况下，您可能需要仅在控件面板中显示有限数量的控件，或显示除特定集合之外的所有控件。

为了实现这一点，您可以使用 controls 参数中的可选 include 和 exclude 配置字段，您可以将其定义为字符串数组或正则表达式。

考虑以下故事片段

YourComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { YourComponent } from './YourComponent';
 
const meta: Meta<typeof YourComponent> = {
  component: YourComponent,
};
 
export default meta;
type Story = StoryObj<typeof YourComponent>;
 
export const ArrayInclude: Story = {
  parameters: {
    controls: { include: ['foo', 'bar'] },
  },
};
 
export const RegexInclude: Story = {
  parameters: {
    controls: { include: /^hello*/ },
  },
};
 
export const ArrayExclude: Story = {
  parameters: {
    controls: { exclude: ['foo', 'bar'] },
  },
};
 
export const RegexExclude: Story = {
  parameters: {
    controls: { exclude: /^hello*/ },
  },
};

排序控件

默认情况下，控件是未排序的，并使用 args 数据处理的任何顺序 (none)。此外，您可以按 arg 的名称 (alpha) 或首先显示必需的 args (requiredFirst) 对它们进行字母排序。

考虑以下代码片段以强制首先显示必需的 args

YourComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { YourComponent } from './YourComponent';
 
const meta: Meta<typeof YourComponent> = {
  component: YourComponent,
  parameters: { controls: { sort: 'requiredFirst' } },
};
 
export default meta;

禁用特定属性的控件

除了此处已记录的功能外，还可以为单个属性禁用控件。

假设您要关闭组件故事中名为 foo 的属性的控件。以下示例说明了如何操作

YourComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { YourComponent } from './YourComponent';
 
const meta: Meta<typeof YourComponent> = {
  component: YourComponent,
  argTypes: {
    // foo is the property we want to remove from the UI
    foo: {
      table: {
        disable: true,
      },
    },
  },
};
 
export default meta;

导致 Storybook UI 中发生以下更改

前面的示例还从表中删除了 prop 文档。在某些情况下，这很好。但是，有时您可能希望渲染 prop 文档而不带控件。以下示例说明了如何操作

YourComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { YourComponent } from './YourComponent';
 
const meta: Meta<typeof YourComponent> = {
  component: YourComponent,
  argTypes: {
    // foo is the property we want to remove from the UI
    foo: {
      control: false,
    },
  },
};
 
export default meta;

与其他 Storybook 属性（如装饰器）一样，您可以在故事级别应用相同的模式以获得更细粒度的用例。

条件控件

在某些情况下，能够根据另一个控件的值有条件地排除控件很有用。控件使用 if 支持这些用例的基本版本，它可以采用简单的查询对象来确定是否包含控件。

考虑一组“高级”设置，这些设置仅在用户切换“高级”开关时可见。

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    label: { control: 'text' }, // Always shows the control
    advanced: { control: 'boolean' },
    // Only enabled if advanced is true
    margin: { control: 'number', if: { arg: 'advanced' } },
    padding: { control: 'number', if: { arg: 'advanced' } },
    cornerRadius: { control: 'number', if: { arg: 'advanced' } },
  },
};
 
export default meta;

或者考虑一个约束，如果用户设置了一个控件值，则用户能够设置另一个值就没有意义了。

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    // Button can be passed a label or an image, not both
    label: {
      control: 'text',
      if: { arg: 'image', truthy: false },
    },
    image: {
      control: { type: 'select', options: ['foo.jpg', 'bar.jpg'] },
      if: { arg: 'label', truthy: false },
    },
  },
};
 
export default meta;

查询对象必须包含 arg 或 global 目标之一

字段	类型	含义
arg	string	要测试的 arg 的 ID。
global	string	要测试的 global 的 ID。

它还可以最多包含以下运算符之一

运算符	类型	含义
truthy	boolean	目标值是否为 truthy？
exists	boolean	目标值是否已定义？
eq	any	目标值是否等于提供的值？
neq	any	目标值是否不等于提供的值？

如果未提供运算符，则等效于 { truthy: true }。

此参数最有用，它允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 true，则可以通过在 meta（组件）或 story 级别将其设置为 false 来重新启用它。

指定控件的排序方式。

none: 无排序，按照参数类型处理的顺序显示
alpha: 按字母顺序排序，按参数类型的名称
requiredFirst: 与 alpha 相同，但任何必需的参数类型都优先显示

`disableSaveFromUI`

类型: boolean

默认值: false

禁用从 Controls 面板创建或编辑 story 的功能。

控件

选择控件类型

自定义控件类型匹配器

完全自定义 args

处理复杂值

从控件创建和编辑故事

创建新故事

编辑故事

禁用创建和编辑故事

配置

注解

参数

显示每个属性的完整文档

指定初始预设颜色色板

过滤控件

排序控件

禁用特定属性的控件

条件控件

故障排除

控件未在自动生成的文档中更新 story

API

参数

`disable`

`exclude`

`expanded`

`include`

`presetColors`

`sort`

`disableSaveFromUI`