ArgTypes

ArgTypes 指定参数的行为。通过指定参数的类型，您可以限制其可以接受的值，并提供有关未显式设置的参数（即描述）的信息。

您还可以使用 ArgTypes 对参数进行“注释”，这些注释包含使用这些参数的插件使用的信息。例如，要指示控件插件渲染一个颜色选择器，您可以指定 'color' 控件类型。

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

ArgTypes table

自动推断 ArgTypes

如果您使用 Storybook 文档插件（默认情况下作为基本功能的一部分安装），Storybook 会根据 CSF 文件的默认导出中指定的 component 为每个故事推断出一组 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 最常在元数据（组件）级别指定，在 CSF 文件的默认导出中

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;

它们可以在项目（全局）级别指定时应用于所有故事，在 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;

或者它们可以只应用于特定故事

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，该对象的键与参数的名称匹配。每个键的值是一个具有以下属性的对象

`control`

类型

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

默认

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

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

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 附加组件更改参数值的控件类型。以下是可用类型，ControlType，按它们处理的数据类型分组。

数据类型	ControlType	描述
数组	`'object'`	提供一个基于 JSON 的编辑器来处理数组的值。还允许以原始模式编辑。 `{ control: 'object' }`
布尔值	`'boolean'`	提供一个切换按钮，用于在可能的狀態之间切换。 `{ control: 'boolean' }`
枚举	`'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'`	提供一个数字输入，包括所有可能值的范围。 `{ control: { type: 'number', min:1, max:30, step: 2 } }`
	`'range'`	提供一个范围滑块，包括所有可能的值。 `{ control: { type: 'range', min: 1, max: 30, step: 3 } }`
对象	`'file'`	提供一个文件输入，它返回一个 URL 数组。可以进一步自定义以接受特定的文件类型。 `{ control: { type: 'file', accept: '.png' } }`
	`'object'`	提供一个基于 JSON 的编辑器来处理对象的值。还允许以原始模式编辑。 `{ control: 'object' }`
字符串	`'color'`	提供一个颜色选择器，用于选择颜色值。可以额外配置以包括一组颜色预设。 `{ control: { type: 'color', presetColors: ['red', 'green']} }`
	`'date'`	提供一个日期选择器，用于选择日期。 `{ control: 'date' }`
	`'text'`	提供一个自由格式的文本输入。 `{ control: 'text' }`

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

`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

默认值：推断

描述参数。 (如果您打算描述参数的类型，您应该使用 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;
}

根据另一个参数或全局变量的值，有条件地呈现一个 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 附加组件）和预览（您的故事）之间同步。

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 对象使用参数的名称作为键。默认情况下，该键用于在 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;

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

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

`options`

类型：string[]

默认值：推断

如果参数接受有限的值集，您可以使用 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 文档块、Controls 文档块和 Controls 附加组件面板中记录。

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

自动推断 ArgTypes

手动指定 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`