背景

背景功能允许你设置故事在 UI 中渲染的背景颜色：

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

配置

¥Configuration

默认情况下，背景功能包含明暗背景。

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

但是你不限于这些背景。你可以使用 .storybook/preview.js|ts 中的 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|ts.

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

¥You can define the available background colors using the options property and set the initial background color using the initialGlobals property:

// 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: {
        // 👇 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

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

¥The backgrounds feature 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 globals option:

// 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' },
  },
};

扩展配置

¥Extending the configuration

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

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

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

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

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

禁用背景

¥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-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 Large: Story = {
  parameters: {
    backgrounds: { disable: true },
  },
};

网格

¥Grid

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

¥The backgrounds feature 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 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 贡献了以下全局变量：

¥This module contributes the following globals to Storybook, under the backgrounds namespace:

grid

类型：boolean

¥Type: boolean

是否显示 grid。

¥Whether the grid is displayed.

value

类型：string

¥Type: string

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

¥When set, the background color is applied and cannot be changed using the toolbar. Must match the key of one of the available colors.

参数

¥Parameters

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

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

disable

类型：boolean

¥Type: boolean

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

¥Disable this feature's behavior. If you wish to disable this feature for the entire Storybook, you should do so in your main configuration file.

此参数最有用，允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 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 then 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.

options

(必需，请参阅说明)

¥(Required, see description)

类型：

¥Type:

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

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

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