ArgTypes

ArgTypes 指定 args 的行為。藉由指定 arg 的類型，您可以限制它可接受的值，並提供有關未明確設定之 args 的資訊 (即，描述)。

您也可以使用 argTypes 來「註解」args，其中包含使用這些 args 的附加元件所用的資訊。例如，若要指示 controls 附加元件渲染色彩選擇器，您可以指定 'color' 控制項類型。

argTypes 最具體的實現是 ArgTypes 文件區塊 (Controls 類似)。表格中的每一列都對應至單一 argType 和該 arg 的目前值。

ArgTypes table

自動 argType 推斷

如果您使用 Storybook 文件附加元件 (預設安裝為基本的一部分)，則 Storybook 會根據 CSF 檔案預設匯出中指定的 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 檔案的預設匯出中

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 設定檔中指定時，它們可以套用至所有 story

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

您可以使用索引鍵與 args 名稱相符的物件來設定 argTypes。每個索引鍵的值都是具有下列屬性的物件

`control`

類型

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

預設

'select'，如果指定了 options
否則，從 type 推斷
否則為 'object'

指定 controls 附加元件對於 arg 的行為。如果您指定字串，它會用作控制項的 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

預設值：已推斷；'select'，如果指定了 options；否則會回復為 'object'

指定用於透過controls addon變更 arg 值的控制項類型。以下是可用的類型，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 時間戳記。這是一個已知限制，將在未來版本中修復。如果您需要表示實際日期，則需要更新 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或全域變數的值，有條件地渲染 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 addon）和預覽（您的 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 物件使用參數的名稱作為鍵值。預設情況下，在 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

自動 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`