側邊欄 & URL

觀看影片教學

Storybook 的側邊欄會列出所有您的 Story，並依元件分組。當您有很多元件時，您可能也希望將這些元件分組。若要這樣做，您可以將 / 分隔符號新增至 CSF 檔案的 title，而 Storybook 將會根據常見的前置詞將 Story 分組

Storybook sidebar anatomy

我們建議使用一個與元件的檔案系統路徑鏡射的巢狀架構。例如，如果您有一個檔案 components/modals/Alert.js，請將 CSF 檔案命名為 components/modals/Alert.stories.js 並將其標題設為 Components/Modals/Alert。

根目錄

預設情況下，Storybook 會將您的最上層節點視為「根目錄」。根目錄會在 UI 中顯示為階層的「區段」。較低層級的群組會顯示為資料夾

Storybook sidebar story roots

如果您偏好將最上層節點顯示為資料夾而不是根目錄，您可以在 ./storybook/manager.js 中將 sidebar.showRoots 選項設為 false

./storybook/manager.js

import { addons } from '@storybook/manager-api';
 
addons.setConfig({
  sidebar: {
    showRoots: false,
  },
});

Story 的永久連結

預設情況下，Storybook 會根據元件標題和 Story 名稱，為每個 Story 產生一個 id。這個 id 特別用於每個 Story 的 URL 中，而該 URL 可以作為永久連結（主要是在您發布您的 Storybook 時）。

請考慮以下 Story

FooBar.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Foo } from './Foo';
 
const meta: Meta<typeof Foo> = {
  /* 👇 The title prop is optional.
   * See https://storybook.dev.org.tw/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Foo/Bar',
  component: Foo,
};
 
export default meta;
type Story = StoryObj<typeof Foo>;
 
export const Baz: Story = {};

Storybook 的 ID 產生邏輯會給這個 id foo-bar--baz，因此連結會是 ?path=/story/foo-bar--baz。

可以手動設定 Story 的 ID，如果您想要重新命名 Story 而不會破壞永久連結，這會很有用。假設您想要將階層中的位置變更為 OtherFoo/Bar，並將 Story 名稱變更為 Moo。以下是如何執行此操作

FooBar.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Foo } from './Foo';
 
const meta: Meta<typeof Foo> = {
  /* 👇 The title prop is optional.
   * See https://storybook.dev.org.tw/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'OtherFoo/Bar',
  component: Foo,
  id: 'Foo/Bar', // Or 'foo-bar' if you prefer
};
 
export default meta;
type Story = StoryObj<typeof Foo>;
 
export const Baz: Story = {
  name: 'Insert name here',
};

如果提供，Storybook 會優先使用 id 來產生 ID，而不是標題，並優先使用 story.name 來顯示，而不是匯出金鑰。

CSF 3.0 自動標題

Storybook 6.4 引入了 CSF 3.0 作為實驗性功能，讓您可以更精簡地撰寫 Story。假設您已經在使用此格式來撰寫您的 Story。在這種情況下，您可以省略預設匯出中的 title 元素，並允許 Storybook 根據檔案的實際位置自動推斷它。例如，假設有以下設定和 Story

.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: ['../src'],
};
 
export default config;

當 Storybook 載入時，該 Story 可以 components/My Component 的形式顯示在側邊欄中。

自動標題與元件的 title 和 Story 的 name 等明確的標題選項搭配使用

src/components/Button/Button.stories.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<Button> = {
  // Sets the name for the stories container
  title: 'components/Button',
  // The component name will be used if `title` is not set
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
// The story variable name will be used if `name` is not set
const Primary: Story = {
  // Sets the name for that particular story
  name: 'Primary',
  args: {
    label: 'Button',
  },
};

自動標題檔案名稱大小寫

從 Storybook 6.5 開始，自動產生的 Story 標題不再依賴 Lodash 的 startCase。相反地，檔案名稱大小寫會保留，允許對 Story 標題進行額外控制。例如，components/My Component 會定義為 components/MyComponent。

如果需要，您可以透過新增以下設定來還原先前的模式

.storybook/manager.js

import { addons } from '@storybook/manager-api';
 
import startCase from 'lodash/startCase.js';
 
addons.setConfig({
  sidebar: {
    renderLabel: ({ name, type }) => (type === 'story' ? name : startCase(name)),
  },
});

除了改進故事檔案名稱的大小寫處理外，還引入了一種新的啟發式方法，用於移除多餘的名稱。當檔案名稱與目錄名稱相同，或是名為 index.stories.js|ts 時，就會移除多餘的名稱。例如，之前 components/MyComponent/MyComponent.stories.js 在側邊欄中會被定義為 Components/MyComponent/MyComponent。現在它會被定義為 Components/MyComponent。

如果您需要保留原有的命名方式，您可以將 title 元素新增到預設的 export 中。例如：

components/MyComponent/MyComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  /* 👇 The title prop is optional.
   * See https://storybook.dev.org.tw/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  component: MyComponent,
  title: 'components/MyComponent/MyComponent',
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
export const Default: Story = {
  args: {
    something: 'Something else',
  },
};

自動標題前綴

此外，如果您自訂 Storybook 以根據設定物件來載入您的故事，包括 titlePrefix，Storybook 會自動將前綴加到所有符合的故事標題。例如，假設您有以下設定：

.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: [
    {
      directory: '../src',
      titlePrefix: 'Custom', // 👈 Configure the title prefix
    },
  ],
};
 
export default config;

當 Storybook 為所有符合的故事產生標題時，它們會保留 Custom 前綴。

故事索引器

故事索引器是一組 Storybook 用於爬梳檔案系統的啟發式方法，它會根據給定的 glob 模式搜尋符合的故事，然後用來產生一個 index.json（以前是 stories.json）檔案，負責使用必要資訊來填充側邊欄。預設情況下，這個啟發式方法會尋找包含以下模式的檔案 *.stories.@(js|jsx|mjs|ts|tsx)。

您可以提供自己的索引器，以包含具有不同命名約定的故事、調整自動標題生成，使其不只是加前綴，以及許多其他用例。如需更多資訊，請參閱故事索引器 API 參考。