Backgrounds
背景工具栏插件允许您设置 Story 在 UI 中渲染时所用的背景颜色
globals API
此插件已更新为在使用 backgroundsStoryGlobals 功能标志时使用 globals API。使用 globals，当您为 Story 指定背景值时，它无法从工具栏中覆盖，这确保了在 Story 之间导航时体验的一致性。这将是 Storybook 9 中的默认行为和 API。
配置
默认情况下，背景工具栏包含浅色和深色背景。
但您不限于这些背景。您可以使用 backgrounds parameter 在 .storybook/preview.js 中配置您自己的一组颜色。
您可以使用 values 属性定义可用的背景颜色，并使用 default 属性设置初始背景颜色
// 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 相同的对象属性。
// 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;为 Story 定义背景
背景插件使您能够通过从工具栏中预定义的背景颜色列表中选择来更改应用于 Story 的背景颜色。如果需要，您可以使用 parameters.backgrounds.default 参数将 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,
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',
},
},
};顾名思义，此方法仅设置 Story 的默认背景颜色。在查看 Story 时，您仍然可以使用工具栏更改背景颜色。
使用 globals API
当您使用 globals 为 Story（或组件的 Stories）指定背景颜色时，将应用该背景颜色，并且无法使用工具栏进行更改。当您想要确保 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' },
},
};扩展配置
您还可以通过 参数继承在每个组件或每个 Story 的基础上配置背景。
要设置可用的背景颜色，请使用 values 属性。在此示例中，我们将调整所有 Button 组件的 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;使用 globals API
可用的背景颜色使用 options 属性定义。在此示例中，我们将调整所有 Button 组件的 Stories 的颜色
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;禁用背景
如果您想在 Story 中关闭背景，可以通过如下配置 backgrounds 参数来完成
使用 globals API
请注意，该属性已重命名为 disabled。
// 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 },
},
};网格
背景工具栏还包括一个网格选择器，可让您快速查看组件是否对齐。
您无需额外配置即可开始使用。但其属性是完全可自定义的；如果您不为其任何属性提供任何值，它们将默认为以下值
// 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
参数
此插件在 backgrounds 命名空间下，向 Storybook 贡献以下参数
default
类型： string
必需：请参阅描述
默认背景颜色。必须与在 values （或 options）属性中定义的可用颜色之一的 name 属性匹配。
disable
使用 globals API
请注意，该属性已重命名为 disabled。
类型: boolean
关闭此插件的行为。如果您希望为整个 Storybook 关闭此插件，则应在注册 addon-essentials 时执行此操作。有关更多信息，请参阅essential addon's docs。
此参数最有用，允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 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 属性。