控件

Storybook Controls 为你提供了一个图形 UI，可以动态地与组件的参数进行交互，而无需编写代码。它会在你的组件示例 ("stories") 旁边创建一个插件面板，以便你可以实时编辑它们。

¥Storybook Controls gives you a graphical UI to interact with a component's arguments dynamically without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live.

控件不需要对你的组件进行任何修改。控件的故事为：

¥Controls do not require any modification to your components. Stories for controls are:

• 方便。基于 React/Vue/Angular/等自动生成控件。组件。

  ¥Convenient. Auto-generate controls based on React/Vue/Angular/etc. components.

• 可移植。在文档、测试甚至设计中重用你的交互式故事。

  ¥Portable. Reuse your interactive stories in documentation, tests, and even in designs.

• 丰富。自定义控件和交互式数据以满足你的确切需求。

  ¥Rich. Customize the controls and interactive data to suit your exact needs.

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

¥To use the Controls addon, you need to write your stories using args. Storybook will automatically generate UI controls based on your args and what it can infer about your component. Still, you can configure the controls further using argTypes, see below.

选择控件类型

¥Choosing the control type

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

¥By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., boolean or string). To enable them, add the component annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching argTypes for your component using react-docgen, a documentation generator for React components that also includes first-class support for TypeScript.

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

例如，假设你的故事中有一个 variant 参数，应该是 primary 或 secondary：

¥For instance, suppose you have a variant arg on your story that should be primary or secondary:

// 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 参数渲染自由文本输入：

¥By default, Storybook will render a free text input for the variant arg:

只要你在自动生成的文本控件中输入有效字符串，它就会起作用。不过，由于组件仅接受 primary 或 secondary 作为变体，因此它不是我们场景的最佳 UI。让我们用 Storybook 的 radio 组件替换它。

¥It works as long as you type a valid string into the auto-generated text control. Still, it's not the best UI for our scenario, given that the component only accepts primary or secondary as variants. Let’s replace it with Storybook’s radio component.

我们可以通过为 variant 属性声明自定义 argType 来指定使用哪些控件。ArgTypes 对参数的基本元数据进行编码，例如参数的名称、描述和默认值。这些文件将由 Storybook Docs 自动填写。

¥We can specify which controls get used by declaring a custom argType for the variant property. ArgTypes encode basic metadata for args, such as name, description, and defaultValue for an arg. These get automatically filled in by Storybook Docs.

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

¥ArgTypes can also contain arbitrary annotations, which the user can override. Since variant is a property of the component, let's put that annotation on the default export.

// 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;

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

¥This replaces the input with a radio group for a more intuitive experience.

自定义控件类型匹配器

¥Custom control type matchers

控件可以通过 regex 从参数名称中自动推断，但目前仅适用于颜色选择器和日期选择器控件。如果你使用 Storybook CLI 设置了你的项目，它应该已经在 .storybook/preview.js 中自动创建了以下默认值：

¥Controls can automatically be inferred from arg's name with regex, but currently only for the color picker and date picker controls. If you've used the Storybook CLI to setup your project, it should have automatically created the following defaults in .storybook/preview.js:

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

¥If you haven't used the CLI to set the configuration, or if you want to define your patterns, use the matchers property in the controls parameter:

// 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;

完全自定义参数

¥Fully custom args

到目前为止，我们仅使用基于我们正在为其编写故事的组件的自动生成的控件。如果我们正在编写 复杂故事，我们可能想要为不属于组件的参数添加控件。例如，以下是你可以使用 footer 参数填充子组件的方法：

¥Until now, we only used auto-generated controls based on the component for which we're writing stories. If we are writing complex stories, we may want to add controls for args that aren’t part of the component. For example, here's how you could use a footer arg to populate a child component:

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 将为所有参数添加控件：

¥By default, Storybook will add controls for all args that:

• 它从组件定义 如果你的框架支持它 推断出来。

  ¥It infers from the component definition if your framework supports it.

• 出现在故事​​的参数列表中。

  ¥Appear in the list of args for your story.

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

¥Using argTypes, you can change the display and behavior of each control.

处理复杂值

¥Dealing with complex values

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

¥When dealing with non-primitive values, you'll notice that you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the args param in the URL, losing the ability to share and deep link to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls addon) and the preview (your story).

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

¥One way to deal with this is to use primitive values (e.g., strings) as arg values and add a custom render function to convert them to their complex counterpart before rendering. It isn't the nicest way to do it (see below), but certainly the most flexible.

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 来为你的复选框、单选按钮或选择输入配置自定义标签。

¥Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a mapping; additionally, you can specify control.labels to configure custom labels for your checkbox, radio, or select input.

// 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 都不必详尽无遗。如果未列出当前选定的选项，则逐字使用。

¥Note that both mapping and control.labels don't have to be exhaustive. If the currently selected option is not listed, it's used verbatim.

从控件创建和编辑故事

¥Creating and editing stories from controls

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

¥The Controls addon allows you to create or edit stories, directly from the Controls panel.

创建新故事

¥Create a new story

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

¥Open the Controls panel for a story and adjust the value of a control. Then save those changes as a new story.

如果你正在开发尚无任何故事的组件，则可以单击侧栏中的 ➕ 按钮来搜索你的组件并为你创建一个基本故事。

¥If you're working on a component that does not yet have any stories, you can click the ➕ button in the sidebar to search for your component and have a basic story created for you.

编辑故事

¥Edit a story

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

¥You can also update a control's value, then save the changes to the story. The story file's code will be updated for you.

禁用故事的创建和编辑

¥Disable creating and editing of stories

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

¥If you don't want to allow the creation or editing of stories from the Controls panel, you can disable this feature by setting the disableSaveFromUI parameter to true in the parameters.controls parameter in your .storybook/preview.js file.

配置

¥Configuration

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

¥The Controls addon can be configured in two ways:

• 可以通过控件注释配置单个控件。

  ¥Individual controls can be configured via control annotations.

• 插件的外观可以通过参数配置。

  ¥The addon's appearance can be configured via parameters.

注释

¥Annotation

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

¥As shown above, you can configure individual controls with the “control" annotation in the argTypes field of either a component or story. Below is a condensed example and table featuring all available controls.

// 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;

参数

¥Parameters

控件支持以下配置 参数，无论是全局配置还是基于每个故事配置：

¥Controls supports the following configuration parameters, either globally or on a per-story basis:

显示每个属性的完整文档

¥Show full documentation for each property

由于 Controls 与 Storybook Docs 建立在相同的引擎上，因此它还可以使用扩展参数（默认为 false）在控件旁边显示属性文档。这意味着你在控制面板中嵌入了一个完整的 Controls 文档块。描述和默认值渲染可以像文档块一样是 customized。

¥Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete Controls doc block in the controls panel. The description and default value rendering can be customized like the doc block.

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

¥To enable expanded mode globally, add the following to .storybook/preview.js:

// 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 的样子：

¥Here's what the resulting UI looks like:

指定初始预设颜色样本

¥Specify initial preset color swatches

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

¥For color controls, you can specify an array of presetColors, either on the control in argTypes, or as a parameter under the controls namespace:

// 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 颜色名称。

¥Color presets can be defined as an object with color and title or a simple CSS color string. These will then be available as swatches in the color picker. When you hover over the color swatch, you'll be able to see its title. It will default to the nearest CSS color name if none is specified.

过滤控件

¥Filtering controls

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

¥In specific cases, you may be required to display only a limited number of controls in the controls panel or all except a particular set.

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

¥To make this possible, you can use optional include and exclude configuration fields in the controls parameter, which you can define as an array of strings or a regular expression.

考虑以下故事片段：

¥Consider the following story snippets:

// 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*/ },
  },
};

排序控件

¥Sorting controls

默认情况下，控件未排序，并使用在 (none) 中处理参数数据的任何顺序。此外，你可以按参数名称（alpha）的字母顺序对它们进行排序，也可以按所需参数优先（requiredFirst）对它们进行排序。

¥By default, controls are unsorted and use whatever order the args data is processed in (none). Additionally, you can sort them alphabetically by the arg's name (alpha) or with the required args first (requiredFirst).

考虑以下代码片段以首先强制必需的参数：

¥Consider the following snippet to force required args first:

// 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;

禁用特定属性的控件

¥Disable controls for specific properties

除了这里已经记录的功能之外，还可以为单个属性禁用控件。

¥Aside from the features already documented here, Controls can also be disabled for individual properties.

假设你想关闭组件故事中名为 foo 的属性的控件。以下示例说明了如何：

¥Suppose you want to turn off Controls for a property called foo in a component's story. The following example illustrates how:

// 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 发生以下变化：

¥Resulting in the following change in Storybook UI:

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

¥The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation without a control. The following example illustrates how:

// 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;

条件控制

¥Conditional controls

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

¥In some cases, it's useful to be able to conditionally exclude a control based on the value of another control. Controls supports basic versions of these use cases with the if, which can take a simple query object to determine whether to include the control.

考虑只有当用户切换 "advanced" 切换时才可见的 "advanced" 设置集合。

¥Consider a collection of "advanced" settings only visible when the user toggles an "advanced" toggle.

// 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;

或者考虑一个约束，如果用户设置了一个控制值，则用户设置另一个值是没有意义的。

¥Or consider a constraint where if the user sets one control value, it doesn't make sense for the user to be able to set another value.

// 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 目标：

¥The query object must contain either an arg or global target:

它还可能包含以下最多一个运算符：

¥It may also contain at most one of the following operators:

如果没有提供运算符，则相当于 { truthy: true }。

¥If no operator is provided, that is equivalent to { truthy: true }.

API

参数

¥Parameters

此插件将以下 参数 贡献给 Storybook，位于 controls 命名空间下：

¥This addon contributes the following parameters to Storybook, under the controls namespace:

disable

类型：boolean

¥Type: boolean

禁用此插件的行为。如果你希望为整个 Storybook 禁用此插件，你应该在注册 addon-essentials 时这样做。有关更多信息，请参阅 必备插件文档。

¥Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering addon-essentials. See the essential addon's docs for more information.

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

¥This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to true at the project level, it could then be re-enabled by setting it to false at the meta (component) or story level.

exclude

类型：string[] | RegExp

¥Type: string[] | RegExp

指定要从控件插件面板中排除哪些属性。任何名称与正则表达式匹配或属于数组一部分的属性都将被忽略。参见上面的 使用示例。

¥Specifies which properties to exclude from the Controls addon panel. Any properties whose names match the regex or are part of the array will be left out. See usage example, above.

expanded

类型：boolean

¥Type: boolean

显示控件插件面板中每个属性的完整文档，包括描述和默认值。参见上面的 使用示例。

¥Show the full documentation for each property in the Controls addon panel, including the description and default value. See usage example, above.

include

类型：string[] | RegExp

¥Type: string[] | RegExp

指定在控件插件面板中包含哪些属性。任何名称与正则表达式不匹配或不属于数组一部分的属性都将被忽略。参见上面的 使用示例。

¥Specifies which properties to include in the Controls addon panel. Any properties whose names don't match the regex or are not part of the array will be left out. See usage example, above.

presetColors

类型：(string | { color: string; title?: string })[]

¥Type: (string | { color: string; title?: string })[]

为颜色选择器控件指定预设颜色样本。颜色值可以是任何有效的 CSS 颜色。参见上面的 使用示例。

¥Specify preset color swatches for the color picker control. The color value may be any valid CSS color. See usage example, above.

sort

类型：'none' | 'alpha' | 'requiredFirst'

¥Type: 'none' | 'alpha' | 'requiredFirst'

默认：'none'

¥Default: 'none'

指定控件的排序方式。

¥Specifies how the controls are sorted.

• none:未排序，以处理参数类型的相同顺序显示

  ¥none: Unsorted, displayed in the same order the arg types are processed in

• alpha：按参数类型的名称按字母顺序排序

  ¥alpha: Sorted alphabetically, by the arg type's name

• requiredFirst:与 alpha 相同，首先显示任何所需的参数类型

  ¥requiredFirst: Same as alpha, with any required arg types displayed first

disableSaveFromUI

类型：boolean

¥Type: boolean

默认：false

¥Default: false

禁用从控制面板创建或编辑故事的功能。

¥Disable the ability to create or edit stories from the Controls panel.