ArgTypes

ArgTypes 指定 args 的行为。通过指定参数的类型，你可以限制它可以接受的值并提供有关未明确设置的参数（即 description）的信息。

¥ArgTypes specify the behavior of args. By specifying the type of an arg, you constrain the values that it can accept and provide information about args that are not explicitly set (i.e., description).

你还可以使用 argTypes 来“注释”参数，其中包含使用这些参数的插件使用的信息。例如，要指示 控件插件 渲染颜色选择器，你可以指定 'color' 控件类型。

¥You can also use argTypes to “annotate” args with information used by addons that make use of those args. For instance, to instruct the controls addon to render a color picker, you could specify the 'color' control type.

argTypes 最具体的实现是 ArgTypes 文档块（Controls 类似）。表中的每一行对应于一个 argType 和该参数的当前值。

¥The most concrete realization of argTypes is the ArgTypes doc block (Controls is similar). Each row in the table corresponds to a single argType and the current value of that arg.

自动 argType 推断

¥Automatic argType inference

如果你使用的是 Storybook docs 插件（默认作为 essentials 的一部分安装），那么 Storybook 将根据 CSF 文件的 默认导出 中指定的 component 推断每个故事的一组 argType。

¥If you are using the Storybook docs addon (installed by default as part of essentials), then Storybook will infer a set of argTypes for each story based on the component specified in the default export of the CSF file.

为此，Storybook 会根据你的框架使用各种静态分析工具。

¥To do so, Storybook uses various static analysis tools depending on your framework.

argTypes 的数据结构旨在匹配这些工具的输出。手动指定的属性将覆盖推断的内容。

¥The data structure of argTypes is designed to match the output of the these tools. Properties specified manually will override what is inferred.

手动指定 argTypes

¥Manually specifying argTypes

对于大多数 Storybook 项目，argTypes 是来自组件的 自动推断。手动指定的任何参数类型都将覆盖推断的值。

¥For most Storybook projects, argTypes are automatically inferred from your components. Any argTypes specified manually will override the inferred values.

ArgTypes 通常在元（组件）级别指定，在 CSF 文件的 默认导出 中：

¥ArgTypes are most often specified at the meta (component) level, in the default export of the CSF file:

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    // 👇 All Button stories expect a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
};
 
export default meta;

当在 preview.js|ts 配置文件中的项目（全局）级别指定时，它们可以应用于所有故事：

¥They can apply to all stories when specified at the project (global) level, in the preview.js|ts configuration file:

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  argTypes: {
    // 👇 All stories expect a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
};
 
export default preview;

或者它们只能应用于 特定故事：

¥Or they can apply only to a specific story:

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta, StoryObj } from '@storybook/your-renderer';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
 
type Story = StoryObj<typeof Button>;
 
export const Basic: Story = {
  argTypes: {
    // 👇 This story expects a label arg
    label: {
      control: 'text',
      description: 'Overwritten description',
    },
  },
};

argTypes

类型：

¥Type:

{
  [key: string]: {
    control?: ControlType | { type: ControlType; /* See below for more */ } | false;
    description?: string;
    if?: Conditional;
    mapping?: { [key: string]: { [option: string]: any } };
    name?: string;
    options?: string[];
    table?: {
      category?: string;
      defaultValue?: { summary: string; detail?: string };
      disable?: boolean;
      subcategory?: string;
      type?: { summary?: string; detail?: string };
    },
    type?: SBType | SBScalarType['name'];
  }
}

你可以使用键与 args 名称匹配的对象来配置 argTypes。每个键的值都是具有以下属性的对象：

¥You configure argTypes using an object with keys matching the name of args. The value of each key is an object with the following properties:

control

类型：

¥Type:

| ControlType
| {
    type: ControlType,
    accept?: string;
    labels?: { [option: string]: string };
    max?: number;
    min?: number;
    presetColors?: string[];
    step?: number;
  }
| false

默认：

¥Default:

1. 'select'，如果指定了 options

   ¥'select', if options are specified

2. 否则，从 type 推断

   ¥Else, inferred from type

3. 否则，'object'

   ¥Else, 'object'

指定 控件插件 对参数的行为。如果你指定一个字符串，它将用作控件的 type。如果你指定一个对象，你可以提供其他配置。指定 false 将阻止控件渲染。

¥Specify the behavior of the controls addon for the arg. If you specify a string, it's used as the type of the control. If you specify an object, you can provide additional configuration. Specifying false will prevent the control from rendering.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    value: {
      control: {
        type: 'number',
        min: 0,
        max: 100,
        step: 10,
      },
    },
  },
};
 
export default meta;

control.type

类型：ControlType | null

¥Type: ControlType | null

默认：推断；'select'，如果指定了 options；回退到 'object'

¥Default: Inferred; 'select', if options are specified; falling back to 'object'

指定用于使用 控件插件 更改参数值的控件类型。以下是可用的类型 ControlType，按它们处理的数据类型分组：

¥Specifies the type of control used to change the arg value with the controls addon. Here are the available types, ControlType, grouped by the type of data they handle:

control.accept

类型：string

¥Type: string

当 type 为 'file' 时，你可以指定接受的文件类型。该值应该是逗号分隔的 MIME 类型的字符串。

¥When type is 'file', you can specify the file types that are accepted. The value should be a string of comma-separated MIME types.

control.labels

类型：{ [option: string]: string }

¥Type: { [option: string]: string }

将 options 映射到标签。labels 不必详尽无遗。如果某个选项不在对象的键中，则按字面意思使用。

¥Map options to labels. labels doesn't have to be exhaustive. If an option is not in the object's keys, it's used verbatim.

control.max

类型：number

¥Type: number

当 type 为 'number' 或 'range' 时，设置允许的最大值。

¥When type is 'number' or 'range', sets the maximum allowed value.

control.min

类型：number

¥Type: number

当 type 为 'number' 或 'range' 时，设置允许的最小值。

¥When type is 'number' or 'range', sets the minimum allowed value.

control.presetColors

类型：string[]

¥Type: string[]

当 type 为 'color' 时，定义除通用颜色选择器之外可用的颜色集。数组中的值应该是有效的 CSS 颜色值。

¥When type is 'color', defines the set of colors that are available in addition to the general color picker. The values in the array should be valid CSS color values.

control.step

类型：number

¥Type: number

当 type 为 'number' 或 'range' 时，设置增加/减少值时允许的粒度。

¥When type is 'number' or 'range', sets the granularity allowed when incrementing/decrementing the value.

description

类型：string

¥Type: string

默认：推断

¥Default: Inferred

描述参数。（如果你打算描述参数的类型，则应改用 table.type。）

¥Describe the arg. (If you intend to describe the type of the arg, you should use table.type, instead.)

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    value: {
      description: 'The value of the slider',
    },
  },
};
 
export default meta;

if

类型：

¥Type:

{
  [predicateType: 'arg' | 'global']: string;
  eq?: any;
  exists?: boolean;
  neq?: any;
  truthy?: boolean;
}

根据另一个 arg 或 global 的值有条件地渲染 argType。

¥Conditionally render an argType based on the value of another arg or global.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    parent: { control: 'select', options: ['one', 'two', 'three'] },
 
    // 👇 Only shown when `parent` arg exists
    parentExists: { if: { arg: 'parent', exists: true } },
 
    // 👇 Only shown when `parent` arg does not exist
    parentDoesNotExist: { if: { arg: 'parent', exists: false } },
 
    // 👇 Only shown when `parent` arg value is truthy
    parentIsTruthy: { if: { arg: 'parent' } },
    parentIsTruthyVerbose: { if: { arg: 'parent', truthy: true } },
 
    // 👇 Only shown when `parent` arg value is not truthy
    parentIsNotTruthy: { if: { arg: 'parent', truthy: false } },
 
    // 👇 Only shown when `parent` arg value is 'three'
    parentIsEqToValue: { if: { arg: 'parent', eq: 'three' } },
 
    // 👇 Only shown when `parent` arg value is not 'three'
    parentIsNotEqToValue: { if: { arg: 'parent', neq: 'three' } },
 
    // Each of the above can also be conditional on the value of a globalType, e.g.:
 
    // 👇 Only shown when `theme` global exists
    parentExists: { if: { global: 'theme', exists: true } },
  },
};
 
export default meta;

mapping

类型：{ [key: string]: { [option: string]: any } }

¥Type: { [key: string]: { [option: string]: any } }

将 options 映射到值。

¥Map options to 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 deeplink 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).

mapping 不必详尽无遗。如果未列出当前选定的选项，则逐字使用。可以与 control.labels 一起使用。

¥mapping doesn't have to be exhaustive. If the currently selected option is not listed, it's used verbatim. Can be used with control.labels.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    label: {
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
};
 
export default meta;

name

类型：string

¥Type: string

argTypes 对象使用参数的名称作为键。默认情况下，该键用于在 Storybook 中显示 argType。你可以通过指定 name 属性来覆盖显示的名称。

¥The argTypes object uses the name of the arg as the key. By default, that key is used when displaying the argType in Storybook. You can override the displayed name by specifying a name property.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    actualArgName: {
      name: 'Friendly name',
    },
  },
};
 
export default meta;

options

类型：string[]

¥Type: string[]

默认：推断

¥Default: Inferred

如果参数接受一组有限的值，你可以使用 options 指定它们。如果这些值是 complex，如 JSX 元素，则可以使用 mapping 将它们映射到字符串值。你可以使用 control.labels 为选项提供自定义标签。

¥If the arg accepts a finite set of values, you can specify them with options. If those values are complex, like JSX elements, you can use mapping to map them to string values. You can use control.labels to provide custom labels for the options.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    icon: {
      options: ['arrow-up', 'arrow-down', 'loading'],
    },
  },
};
 
export default meta;

table

类型：

¥Type:

{
  category?: string;
  defaultValue?: {
    detail?: string;
    summary: string;
  };
  disable?: boolean;
  subcategory?: string;
  type?: {
    detail?: string;
    summary: string;
  };
}

默认：推断

¥Default: Inferred

指定如何在 ArgTypes 文档块、Controls 文档块 和 控件插件面板 中记录参数。

¥Specify how the arg is documented in the ArgTypes doc block, Controls doc block, and Controls addon panel.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    value: {
      table: {
        defaultValue: { summary: 0 },
        type: { summary: 'number' },
      },
    },
  },
};
 
export default meta;

table.category

类型：string

¥Type: string

默认：推断，在某些框架中

¥Default: Inferred, in some frameworks

在类别标题下显示 argType，标签由 category 指定。

¥Display the argType under a category heading, with the label specified by category.

table.defaultValue

类型：{ detail?: string; summary: string }

¥Type: { detail?: string; summary: string }

默认：推断

¥Default: Inferred

argType 的记录默认值。summary 通常用于值本身，而 detail 用于附加信息。

¥The documented default value of the argType. summary is typically used for the value itself, while detail is used for additional information.

table.disable

类型：boolean

¥Type: boolean

设置为 true 以从表中删除 argType 的行。

¥Set to true to remove the argType's row from the table.

table.readonly

类型：boolean

¥Type: boolean

设置为 true 以指示 argType 是只读的。

¥Set to true to indicate that the argType is read-only.

table.subcategory

类型：string

¥Type: string

在子类别标题（显示在 [category] 标题下）下显示 argType，标签由 subcategory 指定。

¥Display the argType under a subcategory heading (which displays under the [category] heading), with the label specified by subcategory.

table.type

类型：{ detail?: string; summary: string }

¥Type: { detail?: string; summary: string }

默认：从 type 推断

¥Default: Inferred from type

argType 的记录类型。summary 通常用于类型本身，而 detail 用于附加信息。

¥The documented type of the argType. summary is typically used for the type itself, while detail is used for additional information.

如果你需要指定实际的语义类型，则应该使用 type。

¥If you need to specify the actual, semantic type, you should use type, instead.

type

类型：'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType

¥Type: 'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType

SBType 的完整类型是：

¥The full type of SBType is:

interface SBBaseType {
  required?: boolean;
  raw?: string;
}
 
type SBScalarType = SBBaseType & {
  name: 'boolean' | 'string' | 'number' | 'function' | 'symbol';
};
 
type SBArrayType = SBBaseType & {
  name: 'array';
  value: SBType;
};
type SBObjectType = SBBaseType & {
  name: 'object';
  value: Record<string, SBType>;
};
type SBEnumType = SBBaseType & {
  name: 'enum';
  value: (string | number)[];
};
type SBIntersectionType = SBBaseType & {
  name: 'intersection';
  value: SBType[];
};
type SBUnionType = SBBaseType & {
  name: 'union';
  value: SBType[];
};
type SBOtherType = SBBaseType & {
  name: 'other';
  value: string;
};
 
type SBType =
  | SBScalarType
  | SBEnumType
  | SBArrayType
  | SBObjectType
  | SBIntersectionType
  | SBUnionType
  | SBOtherType;

默认：推断

¥Default: Inferred

指定 argType 的语义类型。当 argType 为 inferred 时，来自各种工具的信息将汇总在此属性中，然后用于推断其他属性，如 control 和 table.type。

¥Specifies the semantic type of the argType. When an argType is inferred, the information from the various tools is summarized in this property, which is then used to infer other properties, like control and table.type.

如果你只需要指定记录的类型，则应该使用 table.type。

¥If you only need to specify the documented type, you should use table.type, instead.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    value: { type: 'number' },
  },
};
 
export default meta;

defaultValue

（⛔️ 已弃用）

¥(⛔️ Deprecated)

类型：any

¥Type: any

定义 argType 的默认值。已弃用，改为直接定义 arg 值。

¥Define the default value of the argType. Deprecated in favor of defining the arg value directly.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    value: {
      // ⛔️ Deprecated, do not use
      defaultValue: 0,
    },
  },
  // ✅ Do this instead
  args: {
    value: 0,
  },
};
 
export default meta;