参数

参数是用于在 Storybook 中配置 stories 和 addons 的静态元数据。它们在故事、元（组件）、项目（全局）级别指定。

¥Parameters are static metadata used to configure your stories and addons in Storybook. They are specified at the story, meta (component), project (global) levels.

故事参数

¥Story parameters

在故事级别指定的参数仅适用于该故事。它们在故事（名为导出）的 parameters 属性中定义：

¥Parameters specified at the story level apply to that story only. They are defined in the parameters property of the story (named export):

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

CSF 文件的元配置中指定的参数适用于该文件中的所有故事。它们在 meta（默认导出）的 parameters 属性中定义：

¥Parameter's specified in a CSF file's meta configuration apply to all stories in that file. They are defined in the parameters property of the meta (default export):

// 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,
  // 👇 Meta-level parameters
  parameters: {
    backgrounds: {
      default: 'dark',
    },
  },
};
export default meta;
 
type Story = StoryObj<typeof Button>;
 
export const Basic: Story = {};

项目参数

¥Project parameters

在项目（全局）级别指定的参数适用于 Storybook 中的所有故事。它们在 .storybook/preview.js|ts 文件中默认导出的 parameters 属性中定义：

¥Parameters specified at the project (global) level apply to all stories in your Storybook. They are defined in the parameters property of the default export in your .storybook/preview.js|ts file:

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

可用参数

¥Available parameters

Storybook 仅直接接受几个参数。

¥Storybook only accepts a few parameters directly.

layout

类型：'centered' | 'fullscreen' | 'padded'

¥Type: 'centered' | 'fullscreen' | 'padded'

默认：'padded'

¥Default: 'padded'

指定画布应如何 布局故事。

¥Specifies how the canvas should lay out the story.

• centered：将故事置于画布的中心

  ¥centered: Center the story within the canvas

• padded:(默认)为故事添加填充

  ¥padded: (default) Add padding to the story

• 全屏：按原样显示故事，无填充

  ¥fullscreen: Show the story as-is, without padding

options

类型：

¥Type:

{
  storySort?: StorySortConfig | StorySortFn;
}

options.storySort

类型：StorySortConfig | StorySortFn

¥Type: 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;

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

¥Specifies the order in which stories are displayed in the Storybook UI.

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

¥When specifying a configuration object, the following options are available:

• includeNames:是否在排序算法中包含故事名称。默认为 false。

  ¥includeNames: Whether to include the story name in the sorting algorithm. Defaults to false.

• locales:对故事进行排序时使用的语言环境。默认为你的系统语言环境。

  ¥locales: The locale to use when sorting stories. Defaults to your system locale.

• method:要使用的排序方法。默认为 alphabetical。

  ¥method: The sorting method to use. Defaults to alphabetical.

  • 按字母顺序排列：按名称字母顺序对故事进行排序。

    ¥alphabetical: Sort stories alphabetically by name.

  • 按类型按字母顺序排列：按类型字母顺序对故事进行排序，然后按名称排序。

    ¥alphabetical-by-kind: Sort stories alphabetically by kind, then by name.

  • 自定义：使用自定义排序功能。

    ¥custom: Use a custom sorting function.

• order:按指定顺序排列的故事将首先按指定顺序显示。所有其他故事将按字母顺序显示。顺序数组可以接受嵌套数组来对第二级故事类型进行排序，例如 ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']。

  ¥order: Stories in the specified order will be displayed first, in the order specified. All other stories will be displayed after, in alphabetical order. The order array can accept a nested array to sort 2nd-level story kinds, e.g. ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components'].

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

¥When specifying a custom sorting function, the function behaves like a typical JavaScript sorting function. It accepts two stories to compare and returns a number. For example:

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

有关使用示例，请参阅 指南。

¥See the guide for usage examples.

test

类型：

¥Type:

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

clearMocks

类型：boolean

¥Type: boolean

默认：false

¥Default: false

与 Vitest 类似，当故事卸载时，它将在 @storybook/test 中使用 fn() 创建的所有间谍上调用 .mockClear()。这将清除模拟历史记录，但不会将其实现重置为默认实现。

¥Similar to Vitest, it will call .mockClear() on all spies created with fn() from @storybook/test when a story unmounts. This will clear mock history, but not reset its implementation to the default one.

mockReset

类型：boolean

¥Type: boolean

默认：false

¥Default: false

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

¥Similar to Vitest, it will call .mockReset() on all spies created with fn() from @storybook/test when a story unmounts. This will clear mock history and reset its implementation to an empty function (will return undefined).

restoreMocks

类型：boolean

¥Type: boolean

默认：true

¥Default: true

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

¥Similar to Vitest, it will call .restoreMocks() on all spies created with fn() from @storybook/test when a story unmounts. This will clear mock history and reset its implementation to the original one.

dangerouslyIgnoreUnhandledErrors

类型：boolean

¥Type: boolean

默认：false

¥Default: false

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

¥Unhandled errors might cause false positive assertions. Setting this to true will prevent the play function from failing and showing a warning when unhandled errors are thrown during execution.

基本插件

¥Essential addons

所有其他参数均由插件提供。必备插件 参数记录在其各自的页面上：

¥All other parameters are contributed by addons. The essential addon's parameters are documented on their individual pages:

• 操作

  ¥Actions

• 背景

  ¥Backgrounds

• 控件

  ¥Controls

• 高亮

  ¥Highlight

• 交互

  ¥Interactions

• 测量和轮廓

  ¥Measure & Outline

• 视口

  ¥Viewport

参数继承

¥Parameter inheritance

无论在哪里指定，参数最终都会应用于单个故事。在项目（全局）级别指定的参数适用于该项目中的每个故事。在元（组件）级别指定的那些将应用于与该元相关的每个故事。为故事指定的参数仅适用于该故事。

¥No matter where they're specified, parameters are ultimately applied to a single story. Parameters specified at the project (global) level are applied to every story in that project. Those specified at the meta (component) level are applied to every story associated with that meta. And parameters specified for a story only apply to that story.

指定参数时，它们按增加特异性的顺序合并在一起：

¥When specifying parameters, they are merged together in order of increasing specificity:

1. 项目（全局）参数

   ¥Project (global) parameters

2. 元（组件）参数

   ¥Meta (component) parameters

3. 故事参数

   ¥Story parameters

换句话说，以下参数规范：

¥In other words, the following specifications of parameters:

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

// Dialog.stories.js|ts
 
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],
    },
  },
};

将导致以下参数值应用于每个故事：

¥Will result in the following parameter values applied to each 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],
  },
}