ArgTypes

ArgTypes 指定了 args 的行为。通过指定 arg 的类型，您可以约束它可以接受的值，并提供有关未显式设置的 args 的信息（即，description）。

您还可以使用 argTypes “注解” args，其中包含插件使用的信息，这些插件利用这些 args。例如，要指示 controls 插件渲染颜色选择器，您可以指定 'color' control 类型。

argTypes 最具体的实现是 ArgTypes doc block（Controls 类似）。表格中的每一行对应一个 argType 以及该 arg 的当前值。

ArgTypes table

自动 argType 推断

如果您正在使用 Storybook 文档插件（默认安装，作为 essentials 的一部分），那么 Storybook 将基于 CSF 文件的 default export 中指定的 component，为每个 story 推断一组 argTypes。

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

框架	静态分析工具
React	react-docgen (默认) 或 react-docgen-typescript
Vue	vue-docgen-api
Angular	compodoc
WebComponents	custom-element.json
Ember	YUI doc

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

手动指定 argTypes

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

ArgTypes 最常在 meta（组件）级别指定，位于 CSF 文件的 default export 中

Button.stories.ts|tsx

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

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

.storybook/preview.ts

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

或者它们可以仅应用于特定 story

Button.stories.ts|tsx

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

类型

{
  [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'];
  }
}

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

`control`

类型

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

默认值

如果指定了 options，则为 'select'
否则，从 type 推断
否则，为 'object'

指定 controls 插件对 arg 的行为。如果您指定一个字符串，它将用作 control 的 type。如果您指定一个对象，您可以提供额外的配置。指定 false 将阻止渲染 control。

Example.stories.ts|tsx

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

默认值: 推断；如果指定了 options，则为 'select'；回退到 'object'

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

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

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

`control.accept`

类型: string

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

`control.labels`

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

将 options 映射到标签。labels 不必是详尽的。如果某个选项不在对象的键中，则按原样使用。

`control.max`

类型: number

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

`control.min`

类型: number

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

`control.presetColors`

类型: string[]

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

`control.step`

类型: number

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

`description`

类型: string

默认值: 推断

描述 arg。（如果您打算描述 arg 的类型，则应使用 table.type。）

Example.stories.ts|tsx

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

类型

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

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

Example.stories.ts|tsx

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

将 options 映射到值。

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

mapping 不必是详尽的。如果当前选择的选项未列出，则按原样使用。可以与 control.labels 一起使用。

Example.stories.ts|tsx

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

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

Example.stories.ts|tsx

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

以这种方式重命名 args 时要小心。您正在记录的组件的用户将无法使用文档化的名称作为组件的属性，并且实际名称将不会显示。

因此，当定义仅用于文档目的而不是组件的实际属性的 argType 时，最好使用 name 属性。例如，当为对象的每个属性提供 argTypes 时。

`options`

类型: string[]

默认值: 推断

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

Example.stories.ts|tsx

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

类型

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

默认值: 推断

指定如何在 ArgTypes doc block、Controls doc block 和 Controls 插件面板中记录 arg。

Example.stories.ts|tsx

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

默认值: 推断，在某些框架中

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

`table.defaultValue`

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

默认值: 推断

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

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

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

`type`

SBType 的完整类型是

SBType

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;

默认值: 推断

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

如果你只需要指定文档类型，则应使用 table.type。

Example.stories.ts|tsx

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

(⛔️ 已弃用)

类型：any

定义 argType 的默认值。已弃用，建议直接定义 arg 值。

Example.stories.ts|tsx

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

ArgTypes

自动 argType 推断

手动指定 argTypes

`argTypes`

`control`

`control.type`

`control.accept`

`control.labels`

`control.max`

`control.min`

`control.presetColors`

`control.step`

`description`

`if`

`mapping`

`name`

`options`

`table`

`table.category`

`table.defaultValue`

`table.disable`

`table.readonly`

`table.subcategory`

`table.type`

`type`

`defaultValue`