背景

背景功能允许您设置 Story 在 UI 中渲染时的背景颜色

配置

默认情况下，背景功能包含浅色和深色背景。

但您不限于这些背景。您可以在您的 .storybook/preview.js|ts 中使用 backgrounds 参数配置您自己的颜色集。

您可以使用 options 属性定义可用的背景颜色，并使用 initialGlobals 属性设置初始背景颜色

.storybook/preview.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    backgrounds: {
      options: {
        // 👇 Default options
        dark: { name: 'Dark', value: '#333' },
        light: { name: 'Light', value: '#F7F9F2' },
        // 👇 Add your own
        maroon: { name: 'Maroon', value: '#400' },
      },
    },
  },
  initialGlobals: {
    // 👇 Set the initial background color
    backgrounds: { value: 'light' },
  },
};
 
export default preview;

为 Story 定义背景

背景功能允许您通过从工具栏中预定义的背景颜色列表中选择，来更改应用于 Story 的背景颜色。如果需要，您可以使用 globals 选项将 Story 默认为特定的背景颜色

Button.stories.ts|tsx

// Replace your-framework with the name of your framework (e.g., react-vite, vue3-vite, etc.)
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
  globals: {
    // 👇 Set background value for all component stories
    backgrounds: { value: 'gray', grid: false },
  },
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const OnDark: Story = {
  globals: {
    // 👇 Override background value for this story
    backgrounds: { value: 'dark' },
  },
};

当您使用 globals 为 Story（或组件的 Stories）指定背景颜色时，该颜色会被应用且不能使用工具栏更改。这对于确保 Story 始终在特定背景颜色上渲染非常有用。

扩展配置

您还可以通过参数继承按组件或按 Story 配置背景。

要设置可用的背景颜色，请使用 options 属性。在此示例中，我们将调整 Button 组件所有 Stories 的颜色

Button.stories.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
  parameters: {
    backgrounds: {
      options: {
        // 👇 Override the default `dark` option
        dark: { name: 'Dark', value: '#000' },
        // 👇 Add a new option
        gray: { name: 'Gray', value: '#CCC' },
      },
    },
  },
} satisfies Meta<typeof Button>;
 
export default meta;

禁用背景

如果您想在 Story 中关闭背景，可以通过如下方式配置 backgrounds 参数

Button.stories.ts|tsx

// Replace your-framework with svelte-vite or sveltekit
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import Button from './Button.svelte';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Large: Story = {
  parameters: {
    backgrounds: { disable: true },
  },
};

网格

背景功能还包含一个网格选择器，允许您快速查看组件是否对齐。

您无需额外配置即可开始使用。但其属性是完全可自定义的；如果您不为其任何属性提供任何值，它们将默认为以下值

Button.stories.ts|tsx

// 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';
 
// To apply a set of backgrounds to all stories of Button:
const meta = {
  component: Button,
  parameters: {
    backgrounds: {
      grid: {
        cellSize: 20,
        opacity: 0.5,
        cellAmount: 5,
        offsetX: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
        offsetY: 16, // Default is 0 if story has 'fullscreen' layout, 16 if layout is 'padded'
      },
    },
  },
} satisfies Meta<typeof Button>;
 
export default meta;

API

Globals

此模块在 backgrounds 命名空间下为 Storybook 贡献以下 globals

`grid`

类型：boolean

是否显示网格。

`value`

类型：string

设置后，将应用背景颜色且无法使用工具栏更改。必须与可用颜色之一的键匹配。

参数

此模块在 backgrounds 命名空间下为 Storybook 贡献以下参数

`disable`

类型：boolean

禁用此功能的行为。如果您希望为整个 Storybook 禁用此功能，应在主配置文件中执行此操作。

此参数最适用于允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 true，则可以通过在 meta（组件）或 Story 级别将其设置为 false 来重新启用它。

`grid`

类型

{
  cellAmount?: number;
  cellSize?: number;
  disable?: boolean;
  offsetX?: number;
  offsetY?: number;
  opacity?: number;
}

关于背景网格的配置。

`grid.cellAmount`

类型：number

默认值：5

指定次要网格线的大小。

`grid.cellSize`

类型：number

默认值：20

指定主要网格线的大小。

`grid.disable`

类型：boolean

关闭网格。

`grid.offsetX`

类型：number

默认值：如果故事布局为 'fullscreen' 则为 0；如果故事布局为 'padded' 则为 16

网格的水平偏移。

`grid.offsetY`

类型：number

默认值：如果故事布局为 'fullscreen' 则为 0；如果故事布局为 'padded' 则为 16

网格的垂直偏移。

`grid.opacity`

类型：number

默认值：0.5

网格线的透明度。

`options`

（必需，参见描述）

类型

{
  [key: string]: {
    name: string;
    value: string;
  };
}

可用的背景颜色。有关使用示例，请参见上文。