Backgrounds

背景工具列附加元件可讓您設定 story 在 UI 中渲染時的背景顏色

globals API

此附加元件已更新為在使用 backgroundsStoryGlobals 功能標誌時使用 globals API。使用 globals，當您為 story 指定背景值時，無法從工具列覆寫，這可確保在 story 之間導覽時獲得一致的體驗。這將是 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;

定義 story 的背景

Backgrounds 附加元件可讓您透過從工具列中預定義的背景顏色清單中選擇來變更應用於 story 的背景顏色。如果需要，您可以使用 parameters.backgrounds.default 參數將 story 設定為預設為特定的背景顏色

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

顧名思義，此方法僅設定 story 的預設背景顏色。當您檢視 story 時，仍然可以使用工具列變更背景顏色。

使用 globals API

當您使用 globals 為 story (或元件的 stories) 指定背景顏色時，背景顏色會被套用且無法使用工具列變更。當您想要確保 story 始終在特定的背景顏色上渲染時，這非常有用。

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

擴展設定

您也可以透過參數繼承在每個元件或每個 story 的基礎上設定背景。

若要設定可用的背景顏色，請使用 values 屬性。在此範例中，我們將調整所有 Button 元件 story 的顏色

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 元件 story 的顏色

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;

停用背景

如果您想要在 story 中關閉背景，您可以透過設定 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 },
  },
};

網格

Backgrounds 工具列也包含網格選擇器，可讓您快速查看元件是否對齊。

您不需要額外的設定即可開始使用。但其屬性是完全可自訂的；如果您未提供任何屬性的值，它們將預設為以下值

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，則可以透過在 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 版面配置為 'fullscreen' 則為 0；如果 story 版面配置為 'padded' 則為 16

網格的水平偏移量。

`grid.offsetY`

類型：number

預設值：如果 story 版面配置為 'fullscreen' 則為 0；如果 story 版面配置為 '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 屬性。

Backgrounds

設定

定義 story 的背景

擴展設定

停用背景

網格

API

全域變數

`grid`

`value`

參數

`default`

`disable`

`grid`

`grid.cellAmount`

`grid.cellSize`

`grid.disable`

`grid.offsetX`

`grid.offsetY`

`grid.opacity`

`values`

`options`