背景

背景工具栏附加组件允许您设置故事在 UI 中渲染的背景颜色。

globals API

此附加组件已更新为使用 globals API，前提是 backgroundsStoryGlobals 功能标志已启用。使用 globals，当您为故事指定背景值时，它无法从工具栏中覆盖，这确保了在故事之间导航时的体验一致性。这将成为 Storybook 9 中的默认行为和 API。

配置

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

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

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

.storybook/preview.ts

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

使用 globals API

当使用 globals API 时，您必须使用 options 属性定义可用的背景颜色。初始背景颜色可以使用 initialGlobals 属性设置，该属性接受与此附加组件的 globals 相同的对象属性。

.storybook/preview.ts

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

定义故事的背景

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

Button.stories.ts|tsx

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

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

使用 globals API

当您使用 globals 为故事（或组件的故事）指定背景颜色时，背景颜色将被应用，并且无法使用工具栏更改。当您希望确保故事始终在特定背景颜色上呈现时，这很有用。

Button.stories.ts|tsx

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

扩展配置

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

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

Button.stories.tsx

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;

使用 globals API

可用的背景颜色是使用 options 属性定义的。在本示例中，我们将调整所有 Button 组件故事的颜色。

Button.stories.tsx

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;

禁用背景

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

使用 globals API

请注意，此属性已重命名为 disabled。

Button.stories.ts|tsx

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

网格

背景工具栏还包含一个网格选择器，可让您快速查看组件是否对齐。

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

Button.stories.ts|tsx

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

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

`disable`

使用 globals API

请注意，此属性已重命名为 disabled。

类型：boolean

关闭此插件的行为。如果您希望为整个 Storybook 关闭此插件，则应在注册 addon-essentials 时进行操作。有关更多信息，请参见基本插件文档。

此参数最有用的是允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 true，则可以通过在元数据（组件）或故事级别将其设置为 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

网格线的透明度。

`values`

（必需，请参见说明）

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

可用的背景颜色。请参见上面的使用示例。

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

使用 globals API

`options`

（必需，请参见说明）

类型

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

替换：values

可用的背景颜色。请参见上面的使用示例。

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

背景

配置

定义故事的背景

扩展配置

禁用背景

网格

API

全局

`grid`

`value`

参数

`default`

`disable`

`grid`

`grid.cellAmount`

`grid.cellSize`

`grid.disable`

`grid.offsetX`

`grid.offsetY`

`grid.opacity`

`values`

`options`