側邊欄 & URL

觀看影片教學

Storybook 的側邊欄列出所有依元件分組的 stories。當您有很多元件時，您可能也希望將這些元件分組。若要執行此操作，您可以將 / 分隔符號新增至 CSF 檔案的 title，Storybook 會根據通用前綴將 stories 分組。

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

Stories 的永久連結

預設情況下，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，如果您想重新命名 stories 而不破壞永久連結，這會很有幫助。假設您想要將階層中的位置變更為 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',
};

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

CSF 3.0 自動標題

Storybook 6.4 導入了 CSF 3.0 作為實驗性功能，讓您可以更精簡地撰寫 stories。假設您已經使用此格式撰寫 stories。在這種情況下，您可以從預設匯出中省略 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.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<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)),
  },
});

除了改進 story 檔案名稱大小寫之外，還引入了一種新的啟發式方法，在檔案名稱與目錄名稱相同，或稱為 index.stories.js|ts 的情況下，移除冗餘名稱。例如，在以前，components/MyComponent/MyComponent.stories.js 在側邊欄中定義為 Components/MyComponent/MyComponent。現在它將定義為 Components/MyComponent。

如果您需要保留命名架構，您可以將 title 元素新增至預設匯出。例如：

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）載入您的 stories，Storybook 會自動為所有相符的 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: [
    {
      directory: '../src',
      titlePrefix: 'Custom', // 👈 Configure the title prefix
    },
  ],
};
 
export default config;

當 Storybook 產生所有相符 stories 的標題時，它們將保留 Custom 前綴。

Story Indexers

Story Indexers 是 Storybook 使用的一組啟發式方法，用於根據給定的 glob 模式爬梳您的檔案系統，搜尋相符的 stories，然後用於產生 index.json（以前為 stories.json）檔案，該檔案負責使用必要的資訊填入側邊欄。預設情況下，此啟發式方法將尋找包含以下架構的檔案：*.stories.@(js|jsx|mjs|ts|tsx)。

您可以提供自己的 indexer 以包含具有不同命名慣例的 stories、調整自動標題產生（超出前綴），以及許多其他使用案例。如需更多資訊，請參閱 Story Indexers API 參考資料。