背景

背景工具栏插件允许你设置故事在 UI 中渲染的背景颜色：

¥The backgrounds toolbar addon allows you to set the background color on which the story renders in the UI:

配置

¥Configuration

默认情况下，背景工具栏包含浅色和深色背景。

¥By default, the backgrounds toolbar includes a light and dark background.

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

¥But you're not restricted to these backgrounds. You can configure your own set of colors with the backgrounds parameter in your .storybook/preview.js.

你可以使用 values 属性 定义可用的背景颜色，并使用 default 属性 设置初始背景颜色：

¥You can define the available background colors using the values property and set the initial background color using the default property:

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  parameters: {
    backgrounds: {
      values: [
        // 👇 Default values
        { name: 'Dark', value: '#333' },
        { name: 'Light', value: '#F7F9F2' },
        // 👇 Add your own
        { name: 'Maroon', value: '#400' },
      ],
      // 👇 Specify which background is shown by default
      default: 'Light',
    },
  },
};
 
export default preview;

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
 
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;

定义故事的背景

¥Defining the background for a story

Backgrounds 插件使你可以通过从工具栏中预定义的背景颜色列表中进行选择来更改应用于故事的背景颜色。如果需要，你可以使用 parameters.backgrounds.default 参数将故事默认设置为特定的背景颜色：

¥The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can set a story to default to a specific background color, by using the parameters.backgrounds.default parameter:

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    backgrounds: {
      // 👇 Set default background value for all component stories
      default: 'Gray',
    },
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const OnDark: Story = {
  parameters: {
    backgrounds: {
      // 👇 Override default background value for this story
      default: 'Dark',
    },
  },
};

顾名思义，此方法仅设置故事的默认背景颜色。查看故事时，你仍然可以使用工具栏更改背景颜色。

¥As implied by the name, this method only sets the default background color for a story. You can still change the background color using the toolbar when viewing the story.

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

扩展配置

¥Extending the configuration

你还可以通过 参数继承 在每个组件或每个故事的基础上配置背景。

¥You can also configure backgrounds on a per-component or per-story basis through parameter inheritance.

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

¥To set the available background colors, use the values property. In this example, we'll adjust the colors for all of the Button component's stories:

import type { Meta } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    backgrounds: {
      default: 'Light',
      values: [
        // 👇 Add a new value
        { name: 'Gray', value: '#CCC' },
      ],
    },
  },
};
 
export default meta;

import type { Meta } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    backgrounds: {
      options: {
        // 👇 Override the default `dark` option
        dark: { name: 'Dark', value: '#000' },
        // 👇 Add a new option
        gray: { name: 'Gray', value: '#CCC' },
      },
    },
  },
};
 
export default meta;

禁用背景

¥Disable backgrounds

如果你想关闭故事中的背景，你可以通过配置 backgrounds 参数来实现，如下所示：

¥If you want to turn off backgrounds in a story, you can do so by configuring the backgrounds parameter like so:

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Meta, StoryObj } from '@storybook/your-renderer';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Large: Story = {
  parameters: {
    backgrounds: { disable: true },
  },
};

网格

¥Grid

Backgrounds 工具栏还包括一个网格选择器，可让你快速查看组件是否对齐。

¥The Backgrounds toolbar also includes a Grid selector, which allows you to quickly see if your components are aligned.

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

¥You don't need additional configuration to get started. But its properties are fully customizable; if you don't supply any value to any of its properties, they'll default to the following values:

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
// To apply a set of backgrounds to all stories of Button:
const meta: Meta<typeof Button> = {
  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'
      },
    },
  },
};
 
export default meta;

API

参数

¥Parameters

此插件将以下 参数 贡献给 Storybook，位于 backgrounds 命名空间下：

¥This addon contributes the following parameters to Storybook, under the backgrounds namespace:

default

类型：string

¥Type: string

必需：参见说明

¥Required: See description

默认背景颜色。必须与 values（或 options）属性中定义的可用颜色之一的 name 属性匹配。

¥Default background color. Must match the name property of one of the available colors defined in the values (or options) property.

disable

类型：boolean

¥Type: boolean

关闭此插件的行为。如果你希望为整个 Storybook 关闭此插件，你应该在注册 addon-essentials 时这样做。有关更多信息，请参阅 必备插件文档。

¥Turn off this addon's behavior. If you wish to turn off this addon for the entire Storybook, you should do so when registering addon-essentials. See the essential addon's docs for more information.

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

¥This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to true at the project level, it could be re-enabled by setting it to false at the meta (component) or story level.

grid

类型：

¥Type:

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

背景网格 的配置。

¥Configuration for the background grid.

grid.cellAmount

类型：number

¥Type: number

默认：5

¥Default: 5

指定次要网格线的大小。

¥Specify the size of the minor grid lines.

grid.cellSize

类型：number

¥Type: number

默认：20

¥Default: 20

指定主要网格线的大小。

¥Specify the size of the major grid lines.

grid.disable

类型：boolean

¥Type: boolean

关闭网格。

¥Turn off the grid.

grid.offsetX

类型：number

¥Type: number

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

¥Default: 0 if story layout is 'fullscreen'; 16 if story layout is 'padded'

网格的水平偏移。

¥Horizontal offset of the grid.

grid.offsetY

类型：number

¥Type: number

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

¥Default: 0 if story layout is 'fullscreen'; 16 if story layout is 'padded'

网格的垂直偏移。

¥Vertical offset of the grid.

grid.opacity

类型：number

¥Type: number

默认：0.5

¥Default: 0.5

网格线的不透明度。

¥The opacity of the grid lines.

values

(必需，请参阅说明)

¥(Required, see description)

类型：{ name: string; value: string }[]

¥Type: { name: string; value: string }[]

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

¥Available background colors. See above for a usage example.

在项目级别（在 .storybook/preview.js|ts 中）定义 backgrounds 参数时，必须定义 values 属性。

¥When defining the backgrounds parameter at the project level (in .storybook/preview.js|ts), you must define the values property.

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