Parameters

参数是用于在 Storybook 中配置你的 故事 和 插件 的静态元数据。它们可以在故事、meta（组件）和项目（全局）级别进行指定。

故事参数

在故事级别指定的参数仅适用于该故事。它们在故事的 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 配置中指定的参数适用于该文件中的所有故事。它们在 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;

项目参数

项目（全局）级别指定的参数适用于你 Storybook 中的所有故事。它们在你的 .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

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

默认值：'padded'

指定画布如何 布局故事。

• centered：在画布中居中显示故事
• padded：（默认）为故事添加填充
• fullscreen：按原样显示故事，无填充

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;

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

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

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

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

(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，它将在故事卸载时调用 .mockClear() 到所有由 storybook/test 的 fn() 创建的间谍上。这将清除模拟历史，但不会将其实现重置为默认值。

mockReset

类型：boolean

默认：false

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

restoreMocks

类型：boolean

默认：true

类似于 Vitest，它将在故事卸载时调用 .restoreMocks() 到所有由 storybook/test 的 fn() 创建的间谍上。这将清除模拟历史并将其实现恢复到原始状态。

dangerouslyIgnoreUnhandledErrors

类型：boolean

默认：false

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

Essentials

所有其他参数由功能贡献。 核心功能 的参数记录在其各自的页面上。

• Actions
• Backgrounds
• Controls
• Highlight
• 测量与大纲
• Viewport

参数继承

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

在指定参数时，它们会按照由低到高的特异性顺序进行合并

1. 项目（全局）参数
2. Meta（组件）参数
3. 故事参数

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

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],
    },
  },
};

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

// 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],
  },
}