参数

参数是用于配置你的stories和插件的静态元数据。它们可以在 Story（故事）、Meta（组件）和 Project（全局）级别指定。

Story 参数

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

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Primary: Story = {
  // 👇 Story-level parameters
  parameters: {
    backgrounds: {
      options: {
        red: { name: 'Red', value: '#f00' },
        green: { name: 'Green', value: '#0f0' },
        blue: { name: 'Blue', value: '#00f' },
      },
    },
  },
};

Meta 参数

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

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

Project 参数

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

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    backgrounds: {
      options: {
        light: { name: 'Light', value: '#fff' },
        dark: { name: 'Dark', value: '#333' },
      },
    },
  },
};
 
export default preview;

可用参数

Storybook 直接接受的参数很少。

layout

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

Default: 'padded'

指定 canvas 如何布局 Story。

• centered: 在 canvas 中居中 Story
• padded: （默认）给 Story 添加内边距
• fullscreen: 按原样显示 Story，不带内边距

options

类型

{
  storySort?: StorySortConfig | StorySortFn;
}

options.storySort

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;

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

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

• includeNames: 是否将 story 名称包含在排序算法中。默认为false。
• locales: 排序 stories 时使用的区域设置（locale）。默认为系统区域设置。
• method: 要使用的排序方法。默认为alphabetical。
  • alphabetical: 按名称的字母顺序排序 stories。
  • alphabetical-by-kind: 按 kind 的字母顺序排序 stories，然后按名称排序。
  • custom: 使用自定义排序函数。
• order: 按指定顺序排列的 stories 将首先显示，顺序即为指定顺序。所有其他 stories 将在其后显示，并按字母顺序排列。order 数组可以接受嵌套数组以排序二级 story kinds，例如['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

Type: boolean

Default: false

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

mockReset

Type: boolean

Default: false

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

restoreMocks

Type: boolean

Default: true

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

dangerouslyIgnoreUnhandledErrors

Type: boolean

Default: false

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

基础插件

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

• Actions
• Backgrounds
• Controls
• Highlight
• 测量 & 轮廓
• 视口

参数继承

无论在哪里指定，参数最终都应用于单个 story。在 Project（全局）级别指定的参数应用于该项目中的每个 story。在 Meta（组件）级别指定的参数应用于与该 meta 相关联的每个 story。为某个 story 指定的参数仅适用于该 story。

指定参数时，它们按特异性递增的顺序合并

1. Project（全局）参数
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],
  },
}