背景
背景工具栏插件允许你设置故事在 UI 中渲染的背景颜色:
¥The backgrounds toolbar addon allows you to set the background color on which the story renders in the UI:
globals
API
此插件已更新,在启用 backgroundsStoryGlobals
功能标志 时使用 globals
API。使用 globals
,当你为故事指定背景值时,它不能从工具栏中覆盖,这确保了在故事之间导航时获得一致的体验。这将是 Storybook 9 中的默认行为和 API。
¥This addon has been updated to use the globals
API when the backgroundsStoryGlobals
feature flag is enabled. With globals
, when you specify a background value for a story, it cannot be overridden from the toolbar, which ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9.
配置
¥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;
使用 globals
API
¥With the globals
API
使用 globals
API 时,必须使用 options
属性 定义可用的背景颜色。可以使用 initialGlobals
属性设置初始背景颜色,该属性接受与此插件的 globals
相同的对象属性。
¥When using the globals
API, you must define the available background colors using the options
property. The initial background color can be set using the initialGlobals
property, which accepts the same object properties as the globals
for this addon.
// 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.
使用 globals
API
¥With the globals
API
当你使用 globals
为故事(或组件的故事)指定背景颜色时,将应用背景颜色,并且无法使用工具栏进行更改。当你想要确保故事始终在特定背景颜色上渲染时,这很有用。
¥When you specify a background color for a story (or a component's stories) using globals
, the background color is applied and cannot be changed using the toolbar. This is useful when you want to ensure that a story is always rendered on a specific background color.
// 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;
使用 globals
API
¥With the globals
API
可用的背景颜色是使用 options
属性 定义的。在此示例中,我们将调整所有 Button 组件的故事的颜色:
¥The available background colors are defined using the options
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: {
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:
使用 globals
API
¥With the globals
API
请注意,该属性已重命名为 disabled
。
¥Note that the property has been renamed to 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 },
},
};
网格
¥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
使用 globals
API
¥With the globals
API
全局
¥Globals
此插件在 backgrounds
命名空间下为 Storybook 贡献了以下全局变量:
¥This addon 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
此插件将以下 参数 贡献给 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
使用 globals
API
¥With the globals
API
请注意,该属性已重命名为 disabled
。
¥Note that the property has been renamed to disabled
.
类型: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.
使用 globals
API
¥With the globals
API
options
(必需,请参阅说明)
¥(Required, see description)
类型:
¥Type:
{
[key: string]: {
name: string;
value: string;
};
}
替换:values
¥Replaces: values
可用的背景颜色。有关 使用示例,请参阅上文。
¥Available background colors. See above for a usage example.
在项目级别(在 .storybook/preview.js|ts
中)定义 backgrounds
参数时,必须定义 options
属性。
¥When defining the backgrounds
parameter at the project level (in .storybook/preview.js|ts
), you must define the options
property.