參數

參數是靜態元數據，用於在 Storybook 中設定您的 stories 和 附加元件。它們在 story、meta（元件）、專案（全域）層級中指定。

Story 參數

在 story 層級指定的參數僅適用於該 story。它們在 story（具名匯出）的 parameters 屬性中定義

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
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 OnDark: Story = {
  // 👇 Story-level parameters
  parameters: {
    backgrounds: {
      default: 'dark',
    },
  },
};

Meta 參數

在 CSF 檔案的 meta 設定中指定的參數適用於該檔案中的所有 story。它們在 meta（預設匯出）的 parameters 屬性中定義

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  //👇 Creates specific parameters at the component level
  parameters: {
    backgrounds: {
      default: 'dark',
    },
  },
};
 
export default meta;

專案參數

在專案（全域）層級指定的參數適用於您 Storybook 中的**所有 stories**。它們在您的 .storybook/preview.js|ts 檔案中預設匯出的 parameters 屬性中定義

// Replace your-renderer with the renderer you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  parameters: {
    backgrounds: {
      values: [
        { name: 'light', value: '#fff' },
        { name: 'dark', value: '#333' },
      ],
    },
  },
};
 
export default preview;

可用參數

Storybook 僅直接接受少數參數。

layout

類型：'centered' | 'fullscreen' | 'padded'

預設值：'padded'

指定畫布應如何佈置 story。

• centered：將 story 置於畫布中央
• padded：（預設）在 story 周圍新增邊距
• fullscreen：按原樣顯示 story，不含邊距

options

類型

{
  storySort?: StorySortConfig | StorySortFn;
}

options.storySort

類型：StorySortConfig | StorySortFn

type StorySortConfig = {
  includeNames?: boolean;
  locales?: string;
  method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom';
  order?: string[];
};
 
type Story = {
  id: string;
  importPath: string;
  name: string;
  title: string;
};
 
type StorySortFn = (a: Story, b: Story) => number;

指定 story 在 Storybook UI 中顯示的順序。

當指定設定物件時，可以使用以下選項

• includeNames：是否在排序演算法中包含 story 名稱。預設為 false。
• locales：排序 story 時要使用的地區設定。預設為您的系統地區設定。
• method：要使用的排序方法。預設為 alphabetical。
  • alphabetical：依名稱字母順序排序 story。
  • alphabetical-by-kind：依種類字母順序排序 story，然後依名稱排序。
  • custom：使用自訂排序函數。
• order：指定順序中的 story 將首先顯示，依指定的順序排列。所有其他 story 將在之後依字母順序顯示。order 陣列可以接受巢狀陣列來排序第二層 story 種類，例如 ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']。

當指定自訂排序函數時，該函數的行為類似於典型的 JavaScript 排序函數。它接受兩個要比較的 story 並傳回一個數字。例如

(a, b) => (a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }));

請參閱指南以取得使用範例。

test

類型

{
  clearMocks?: boolean;
  mockReset?: boolean;
  restoreMocks?: boolean;
  dangerouslyIgnoreUnhandledErrors?: boolean;
}

clearMocks

類型：boolean

預設值：false

類似於 Vitest，當 story 卸載時，它將對使用 @storybook/test 中的 fn() 建立的所有間諜呼叫 .mockClear()。這將清除模擬歷史記錄，但不會將其實作重設為預設實作。

mockReset

類型：boolean

預設值：false

類似於 Vitest，當 story 卸載時，它將對使用 @storybook/test 中的 fn() 建立的所有間諜呼叫 .mockReset()。這將清除模擬歷史記錄，並將其實作重設為空函數（將傳回 undefined）。

restoreMocks

類型：boolean

預設值：true

類似於 Vitest，當 story 卸載時，它將對使用 @storybook/test 中的 fn() 建立的所有間諜呼叫 .restoreMocks()。這將清除模擬歷史記錄，並將其實作重設為原始實作。

dangerouslyIgnoreUnhandledErrors

類型：boolean

預設值：false

未處理的錯誤可能會導致錯誤的肯定斷言。將此設定為 true 將防止 play 函數 失敗，並在執行期間拋出未處理的錯誤時顯示警告。

必要的附加元件

所有其他參數都由附加元件貢獻。必要附加元件的參數記錄在其個別頁面上

• 動作
• 背景
• 控制項
• 醒目提示
• 測量與外框
• 視窗

參數繼承

無論參數在哪裡指定，最終都會應用於單個 story。在專案（全域）層級指定的參數會應用於該專案中的每個 story。在 meta（元件）層級指定的參數會應用於與該 meta 關聯的每個 story。而為 story 指定的參數僅適用於該 story。

當指定參數時，它們會依特異性遞增的順序合併在一起

1. 專案（全域）參數
2. Meta（元件）參數
3. Story 參數

換句話說，以下參數規格

const preview = {
  // 👇 Project-level parameters
  parameters: {
    layout: 'centered',
    demo: {
      demoProperty: 'a',
      demoArray: [1, 2],
    },
  },
  // ...
};
export default preview;

const meta = {
  component: Dialog,
  // 👇 Meta-level parameters
  parameters: {
    layout: 'fullscreen',
    demo: {
      demoProperty: 'b',
      anotherDemoProperty: 'b',
    },
  },
};
export default meta;
 
// (no additional parameters specified)
export const Basic = {};
 
export const LargeScreen = {
  // 👇 Story-level parameters
  parameters: {
    layout: 'padded',
    demo: {
      demoArray: [3, 4],
    },
  },
};

將導致以下參數值應用於每個 story

// Applied story parameters
 
// For the Basic story:
{
  layout: 'fullscreen',
  demo: {
    demoProperty: 'b',
    anotherDemoProperty: 'b',
    demoArray: [1, 2],
  },
}
 
// For the LargeScreen story:
{
  layout: 'padded',
  demo: {
    demoProperty: 'b',
    anotherDemoProperty: 'b',
    demoArray: [3, 4],
  },
}