背景
背景工具列擴充功能可讓您設定 UI 中渲染 Story 的背景顏色
globals API
此擴充功能已更新為在使用 backgroundsStoryGlobals 功能旗標時使用 globals API。使用 globals，當您為 Story 指定背景值時，無法從工具列覆寫該值，這可確保在 Story 之間導覽時有一致的體驗。這將會是 Storybook 9 中的預設行為和 API。
組態
預設情況下，背景工具列包含淺色和深色背景。
但您不限於這些背景。您可以使用 參數在 .storybook/preview.js 中設定您自己的一組顏色 backgrounds。
您可以使用 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
參數
此附加元件會在 Storybook 中，於 backgrounds 命名空間下貢獻以下參數
default
類型：string
必要：請參閱說明
預設背景顏色。必須與values（或options）屬性中定義的可用顏色的其中一個name 屬性匹配。
disable
使用 globals API
請注意，屬性已重新命名為 disabled。
類型：boolean
關閉此附加元件的行為。如果您希望關閉整個 Storybook 的此附加元件，您應該在註冊addon-essentials 時執行。請參閱基本附加元件的文件以取得更多資訊。
此參數對於允許在更具體的層級覆寫最有用。例如，如果此參數在專案層級設定為 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
預設值：如果story layout 為'fullscreen'，則為 0；如果 story layout 為 'padded'，則為 16
格線的水平偏移。
grid.offsetY
類型：number
預設值：如果story layout 為'fullscreen'，則為 0；如果 story layout 為 '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 屬性。