背景
背景功能允许您设置 Story 在 UI 中渲染时的背景颜色
配置
默认情况下,背景功能包含浅色和深色背景。
但您不限于这些背景。您可以在您的 .storybook/preview.js|ts
中使用 backgrounds
参数 配置您自己的颜色集。
您可以使用 options
属性定义可用的背景颜色,并使用 initialGlobals
属性设置初始背景颜色
// 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 默认为特定的背景颜色
// 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 的颜色
// 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
参数
// 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 },
},
};
网格
背景功能还包含一个网格选择器,允许您快速查看组件是否对齐。
您无需额外配置即可开始使用。但其属性是完全可自定义的;如果您不为其任何属性提供任何值,它们将默认为以下值
// 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;
};
}
可用的背景颜色。有关使用示例,请参见上文。