設定 Storybook

Storybook 是透過一個名為 .storybook 的資料夾進行設定，其中包含各種設定檔。

請注意，您可以透過將 -c 標記設定為 storybook dev 和 storybook build CLI 命令來變更 Storybook 使用的資料夾。

設定您的 Storybook 專案

Storybook 的主要設定 (即 main.js|ts) 定義了您的 Storybook 專案的行為，包括您的故事的位置、您使用的附加元件、功能標記和其他專案特定的設定。此檔案應位於您專案根目錄的 .storybook 資料夾中。您可以使用 JavaScript 或 TypeScript 撰寫此檔案。以下列出可用的選項以及如何使用它們的範例。

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-essentials'],
  docs: {
    autodocs: 'tag',
  },
  staticDirs: ['../public'],
};
 
export default config;

此設定檔是一個預設，因此具有強大的介面，可以進一步自訂。請閱讀我們關於編寫預設的文件以了解更多資訊。

設定元素	描述
`stories`	表示您的故事檔案位置的 glob 陣列，相對於 `main.js`
`staticDirs`	設定要由 Storybook 載入的靜態檔案目錄清單 `staticDirs: ['../public']`
`addons`	設定 Storybook 載入的附加元件清單 `addons: ['@storybook/addon-essentials']`
`typescript`	設定 Storybook 如何處理 TypeScript 檔案 `typescript: { check: false, checkOptions: {} }`
`framework`	根據一組框架特定設定來設定 Storybook `framework: { name: '@storybook/svelte-vite', options:{} }`
`core`	設定 Storybook 的內部功能 `core: { disableTelemetry: true, }`
`docs`	設定 Storybook 的自動產生文件 `docs: { autodocs: 'tag' }`
`features`	啟用 Storybook 的其他功能請參閱下表，以取得可用功能的清單
`refs`	設定 Storybook 組合 `refs: { example: { title: 'ExampleStorybook', url:'https://your-url.com' } }`
`logLevel`	設定瀏覽器終端機中的 Storybook 記錄。對於除錯很有用 `logLevel: 'debug'`
`webpackFinal`	自訂 Storybook 的 Webpack 設定 `webpackFinal: async (config:any) => { return config; }`
`viteFinal`	使用 vite 建置器時自訂 Storybook 的 Vite 設定 `viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }`
`env`	定義自訂的 Storybook 環境變數。 `env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),`
`build`	透過從套件中排除特定功能，來最佳化 Storybook 生產建置效能。當減少建置時間是首要考量時，此功能很有用。 `build: { test: {} }`

設定故事載入

根據預設，Storybook 會根據 .storybook/main.js|ts 中的 glob (模式比對字串) 從您的專案載入故事，該 glob 符合您專案中副檔名為 .stories.* 的所有檔案。這樣做的目的是讓您將故事檔案與其記錄的組件並列放置。

•
└── components
    ├── Button.js
    └── Button.stories.js

如果您想要使用不同的命名慣例，可以使用 picomatch 支援的語法來變更 glob。

例如，如果您想要從 my-project/src/components 目錄中提取 .md 和 .js 檔案，則可以寫入

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../my-project/src/components/*.@(js|md)'],
};
 
export default config;

使用設定物件

此外，您可以自訂 Storybook 的設定，以根據設定物件載入您的 stories。例如，如果您想從 packages/components 目錄載入您的 stories，您可以將您的 stories 設定欄位調整為以下內容

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../packages/components',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
      // 👇 Used when generating automatic titles for your stories
      titlePrefix: 'MyComponents',
    },
  ],
};
 
export default config;

當 Storybook 啟動時，它會尋找 packages/components 目錄內任何包含 stories 副檔名的檔案，並產生您的 stories 的標題。

使用目錄

您也可以簡化您的 Storybook 設定，並使用目錄載入 stories。例如，如果您想載入 packages/MyStories 內的所有 stories，您可以將設定調整如下

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  // 👇 Storybook will load all existing stories within the MyStories folder
  stories: ['../packages/MyStories'],
};
 
export default config;

使用自訂實作

您也可以調整您的 Storybook 設定，並實作自訂邏輯來載入您的 stories。例如，假設您正在處理一個包含特定模式的專案，而傳統的載入 stories 方式無法解決該問題。在這種情況下，您可以將您的設定調整如下

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
import type { StoriesEntry } from '@storybook/types';
 
async function findStories(): Promise<StoriesEntry[]> {
  // your custom logic returns a list of files
}
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: async (list: StoriesEntry[]) => [
    ...list,
    // 👇 Add your found stories to the existing list of story files
    ...(await findStories()),
  ],
};
 
export default config;

已知限制

由於 Storybook 目前索引 stories 的方式，按需載入 stories 目前有一些小的限制

支援從版本 1 到版本 3 的 CSF 格式。
允許基於受限 API 的自訂 storySort 函式。

設定 story 呈現方式

要控制 stories 的呈現方式，並加入全域裝飾器和參數，請建立一個 .storybook/preview.js 檔案。這會在 Canvas UI 中載入，也就是在隔離狀態下呈現元件的「預覽」 iframe。請使用 preview.js 來處理全域程式碼（例如 CSS 導入或 JavaScript 模擬），這些程式碼會套用到所有 stories。

preview.js 檔案可以是 ES 模組，並匯出以下鍵

decorators - 全域裝飾器的陣列
parameters - 全域參數的物件
globalTypes - globalTypes 的定義

如果您想變更 stories 的排序方式，請閱讀關於排序 stories 的說明。

設定 Storybook 的 UI

要控制 Storybook UI（「管理員」）的行為，您可以建立一個 .storybook/manager.js 檔案。

這個檔案沒有特定的 API，但是設定 UI 選項和設定 Storybook 的主題的地方。