参数

参数是静态元数据，用于在 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 配置中指定的参数适用于该文件中的所有 stories。它们在 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;

指定 stories 在 Storybook UI 中显示的顺序。

当指定配置对象时，以下选项可用

• includeNames: 是否在排序算法中包含 story 名称。默认为 false。
• locales: 排序 stories 时要使用的区域设置。默认为您的系统区域设置。
• method: 要使用的排序方法。默认为 alphabetical。
  • alphabetical: 按名称字母顺序排序 stories。
  • alphabetical-by-kind: 先按种类，然后按名称字母顺序排序 stories。
  • custom: 使用自定义排序函数。
• order: 指定顺序中的 Stories 将首先显示，按照指定的顺序排列。所有其他 stories 将在之后按字母顺序显示。 order 数组可以接受嵌套数组来排序二级 story 种类，例如 ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']。

当指定自定义排序函数时，该函数的行为类似于典型的 JavaScript 排序函数。它接受两个 stories 进行比较并返回一个数字。例如

(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() 创建的所有 spies 调用 .mockClear()。这将清除模拟历史记录，但不会将其实现重置为默认实现。

mockReset

类型: boolean

默认值: false

类似于 Vitest，当 story 卸载时，它将对使用 @storybook/test 中的 fn() 创建的所有 spies 调用 .mockReset()。这将清除模拟历史记录并将其实现重置为空函数（将返回 undefined）。

restoreMocks

类型: boolean

默认值: true

类似于 Vitest，当 story 卸载时，它将对使用 @storybook/test 中的 fn() 创建的所有 spies 调用 .restoreMocks()。这将清除模拟历史记录并将其实现重置为原始实现。

dangerouslyIgnoreUnhandledErrors

类型: boolean

默认值: false

未处理的错误可能会导致误报断言。将此设置为 true 将阻止 play 函数 在执行期间抛出未处理的错误时失败并显示警告。

基本插件

所有其他参数都由插件贡献。基本插件的参数记录在其各自的页面上

• Actions
• 背景
• Controls
• Highlight
• 测量 & 轮廓
• Viewport

参数继承

无论参数在何处指定，最终都将应用于单个 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],
  },
}