主題化

觀看影片教學

Storybook 可使用輕量的佈景主題 API 進行主題化。

全域主題化

可以全域主題化 Storybook。

Storybook 包含兩種開箱即用的好看主題：「light」和「dark」。除非您已將偏好的色彩配置設定為深色，否則 Storybook 將預設使用淺色主題。

請確保您已安裝 @storybook/manager-api 和 @storybook/theming 套件。

npm install --save-dev @storybook/manager-api @storybook/theming

例如，您可以修改 .storybook/manager.js，告知 Storybook 使用「dark」主題

.storybook/manager.js

import { addons } from '@storybook/manager-api';
import { themes } from '@storybook/theming';
 
addons.setConfig({
  theme: themes.dark,
});

設定主題時，請設定完整的主題物件。主題會被取代，而不是合併。

主題化文件

Storybook 文件使用與 Storybook UI 相同的主題系統，但其主題與主要 UI 獨立。

假設您在 .storybook/manager.js 中為主要 UI 定義了 Storybook 主題

.storybook/manager.js

import { addons } from '@storybook/manager-api';
import { themes } from '@storybook/theming';
 
addons.setConfig({
  theme: themes.dark,
});

以下說明如何在 .storybook/preview.js 中為文件指定相同的主題

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
import { themes } from '@storybook/theming';
 
const preview: Preview = {
  parameters: {
    docs: {
      theme: themes.dark,
    },
  },
};
 
export default preview;

如果您想學習如何建立自己的主題，請繼續閱讀。

建立主題快速入門

自訂 Storybook 最簡單的方法是使用 storybook/theming 中的 create() 函數產生新主題。此函數包含最常見主題變數的簡寫。以下說明如何使用它

在您的 .storybook 目錄中，建立一個名為 YourTheme.js 的新檔案，並新增以下內容

.storybook/YourTheme.js

import { create } from '@storybook/theming';
 
export default create({
  base: 'light',
  brandTitle: 'My custom Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://storybook.dev.org.tw/images/placeholders/350x150.png',
  brandTarget: '_self',
});

如果您使用 brandImage 新增自訂標誌，則可以使用任何最常見的圖片格式。

在上方，我們建立了一個新主題，它將

使用 Storybook 的 light 主題作為基準。
將側邊欄中的 Storybook 標誌替換為我們自己的標誌（在 brandImage 變數中定義）。
新增自訂品牌資訊。
設定品牌連結在同一個視窗中開啟（而不是新視窗），透過 target 屬性。

最後，我們需要將主題導入 Storybook。在您的 .storybook 目錄中建立一個名為 manager.js 的新檔案，並新增以下內容

.storybook/manager.js

import { addons } from '@storybook/manager-api';
import yourTheme from './YourTheme';
 
addons.setConfig({
  theme: yourTheme,
});

現在您的自訂主題將取代 Storybook 的預設主題，您將在 UI 中看到類似的一組變更。

Storybook starter theme

讓我們看看更複雜的範例。複製以下程式碼並貼到 .storybook/YourTheme.js 中。

.storybook/YourTheme.js

import { create } from '@storybook/theming/create';
 
export default create({
  base: 'light',
  // Typography
  fontBase: '"Open Sans", sans-serif',
  fontCode: 'monospace',
 
  brandTitle: 'My custom Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://storybook.dev.org.tw/images/placeholders/350x150.png',
  brandTarget: '_self',
 
  //
  colorPrimary: '#3A10E5',
  colorSecondary: '#585C6D',
 
  // UI
  appBg: '#ffffff',
  appContentBg: '#ffffff',
  appPreviewBg: '#ffffff',
  appBorderColor: '#585C6D',
  appBorderRadius: 4,
 
  // Text colors
  textColor: '#10162F',
  textInverseColor: '#ffffff',
 
  // Toolbar default and active colors
  barTextColor: '#9E9E9E',
  barSelectedColor: '#585C6D',
  barHoverColor: '#585C6D',
  barBg: '#ffffff',
 
  // Form colors
  inputBg: '#ffffff',
  inputBorder: '#10162F',
  inputTextColor: '#10162F',
  inputBorderRadius: 2,
});

在上方，我們正在使用以下變更更新主題

自訂調色盤（在 app 和 color 變數中定義）。
自訂字型（在 font 和 text 變數中定義）。

隨著新變更的引入，自訂主題應產生類似的結果。

Storybook custom theme loaded

許多主題變數是選用的，但 base 屬性不是。

@storybook/theming 套件是使用 TypeScript 建置的，這應有助於為 TypeScript 使用者建立有效的主題。這些類型是套件本身的一部分。

CSS 逸出途徑

Storybook 主題 API 在設計上範圍較窄。如果您想要精細控制 CSS，則所有 UI 和文件元件都標記了類別名稱，使其成為可能。請自行承擔風險使用，因為這是一項進階功能。

若要設定這些元素的樣式，請將樣式標籤插入

對於 Storybook 的 UI，請使用 .storybook/manager-head.html
對於 Storybook 文件，請使用 .storybook/preview-head.html

注意

如同您可以調整預覽的 head 標籤的方式一樣，Storybook 允許您透過 .storybook/manager-head.html 修改管理員端的程式碼。當新增以 Storybook HTML 為目標的主題樣式時，這可能會很有幫助，但這會帶來成本，因為 Storybook 的內部 HTML 可能隨時透過發布週期變更。

MDX 元件覆寫

如果您正在使用 MDX 建立文件，則還有另一層「主題化」。MDX 允許您使用 components 參數完全覆寫從 Markdown 渲染的元件。這是一種進階用法，我們在 Storybook 中未正式支援，但如果您需要，這是一個強大的結構。

以下說明如何在 .storybook/preview.js 中為頁面上的 code 區塊插入自訂程式碼渲染器

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
import { CodeBlock } from './CodeBlock';
 
const preview: Preview = {
  parameters: {
    docs: {
      components: {
        code: CodeBlock,
      },
    },
  },
};
 
export default preview;

您甚至可以覆寫 Storybook 區塊元件。

以下說明如何插入自訂 <Canvas /> 區塊

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
import { MyCanvas } from './MyCanvas';
 
const preview: Preview = {
  parameters: {
    docs: {
      components: {
        Canvas: MyCanvas,
      },
    },
  },
};
 
export default preview;

附加元件與主題建立

有些附加元件需要 Storybook 使用者必須新增的特定主題變數。如果您與社群分享您的主題，請務必支援官方 API 和其他熱門附加元件，以便您的使用者獲得一致的體驗。

例如，熱門的 Actions 附加元件使用 react-inspector，它有自己的主題。提供額外的主題變數來設定其樣式，如下所示

addonActionsTheme: {
  ...chromeLight,
  BASE_FONT_FAMILY: typography.fonts.mono,
  BASE_BACKGROUND_COLOR: 'transparent',
}

為附加元件作者使用主題

針對原生 Storybook 開發人員體驗重複使用上述主題變數。主題引擎依賴 emotion，這是一個 CSS-in-JS 程式庫。

YourTheme.js

import { styled } from '@storybook/theming';

以物件標記法使用主題變數

MyComponent.js|jsx

const Component = styled.div(({ theme }) => ({
  background: theme.background.app,
  width: 0,
}));

或使用樣板字串

MyComponent.js|jsx

const Component = styled.div`
  background: `${props => props.theme.background.app}`
  width: 0;
`;