文件區塊

Storybook 提供數個文件區塊，協助您記錄元件和專案的其他方面。

在 Storybook 中使用文件區塊有兩種常見方式：在 MDX 中以及作為文件頁面範本的一部分。

在 MDX 中

這些區塊最常在 Storybook 的 MDX 文件中使用

{/* ButtonDocs.mdx */}
 
import { Meta, Primary, Controls, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
# Button
 
A button is ...
 
<Primary />
 
## Props
 
<Controls />
 
## Stories
 
### Primary
 
A button can be of primary importance.
 
<Story of={ButtonStories.Primary} />
 
A button can be of secondary importance.
 
<Story of={ButtonStories.Secondary} />
 
{/* ... */}

自訂自動文件頁面

這些區塊也用於定義自動文件的頁面範本。例如，這是預設範本

import { Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks';
 
export const autoDocsTemplate = () => (
  <>
    <Title />
    <Subtitle />
    <Description />
    <Primary />
    <Controls />
    <Stories />
  </>
);

如果您覆寫預設頁面範本，您可以類似地使用文件區塊，為您的專案建立完美的文件頁面。

請注意，某些文件區塊會渲染其他區塊。例如，<Stories /> 區塊會展開為

## Stories
 
<Canvas>
  ### Story name
  <Description />
  <Story />
  <Source />
</Canvas>
 
{/* ... repeat <Canvas> for each story */}

因此，舉例來說，透過參數 (請參閱下一節) 自訂Source 區塊也會影響渲染為 Canvas 區塊一部分的 Source 區塊。

自訂文件區塊

在這兩種使用案例 (MDX 和自動文件) 中，許多文件區塊都可以透過參數進行自訂。

例如，您可以透過 Storybook 從所有 Controls 表格中篩選掉 style 屬性

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

在以下可用的區塊清單中，會標示可透過參數自訂的區塊。

在 MDX 中使用文件區塊時，也可以使用其 props 進行自訂

<Controls exclude={['style']}>

可用的區塊

每個區塊都有專用的 API 參考頁面，詳細說明使用方式、可用的選項和技術細節。

ArgTypes

ArgTypes 區塊可用於顯示指定元件的參數類型的靜態表格，以記錄其介面。

畫布 (Canvas)

畫布 (Canvas) 區塊是 故事 (Story) 的包裝器，具有一個工具列，可讓您與其內容互動，同時自動提供所需的 原始碼 (Source) 片段。

調色盤 (ColorPalette)

調色盤 (ColorPalette) 區塊可讓您記錄整個專案中使用的所有顏色相關項目（例如，色票）。

控制項 (Controls)

控制項 (Controls) 區塊可用於顯示指定故事的引數的動態表格，作為記錄其介面的方法，並允許您更改（單獨）呈現的故事的引數（透過 故事 (Story) 或 畫布 (Canvas) 區塊）。

描述 (Description)

描述 (Description) 區塊會顯示從元件、故事或其各自的 JSDoc 註解取得的中繼資料的描述。

圖示庫 (IconGallery)

圖示庫 (IconGallery) 區塊可讓您快速記錄與專案相關聯的所有圖示，並以整潔的網格顯示。

Markdown

Markdown 區塊可讓您在 MDX 檔案中匯入和包含純文字 markdown。

中繼資料 (Meta)

中繼資料 (Meta) 區塊用於附加自訂的 MDX 文件頁面，以及元件的故事列表。它不會呈現任何內容，但在 MDX 檔案中有兩個用途

• 將 MDX 檔案附加到元件及其故事，或
• 控制側邊欄中未附加的文件項目的位置。

主要 (Primary)

主要 (Primary) 區塊會在 故事 (Story) 區塊中顯示主要（在故事檔案中第一個定義的）故事。它通常會直接在文件條目的標題下呈現。

原始碼 (Source)

原始碼 (Source) 區塊用於直接呈現原始碼片段。

故事集 (Stories)

故事集 (Stories) 區塊會呈現故事檔案中的完整故事集合。

故事 (Story)

故事（元件測試）是 Storybook 的基本構建模組。

在 Storybook 文件中，您可以使用 故事 (Story) 區塊，在 MDX 檔案的內容中呈現 CSF 檔案中的任何故事，並套用所有註解（參數、引數、載入器、裝飾器、播放函式）。

副標題

Subtitle 區塊可以用作您文件條目的次要標題。

標題

Title 區塊作為您文件條目的主要標題。它通常用於提供元件或頁面的名稱。

排版

Typeset 區塊有助於記錄您專案中使用的字體。

無樣式

Unstyled 區塊是一個獨特的區塊，它會停用 Storybook 在 MDX 文件中添加的預設樣式。

預設情況下，文件中的大多數元素（如 h1、p 等）都會應用一些預設樣式，以確保文件看起來良好。但是，有時您可能希望某些內容不應用這些樣式。在這些情況下，請使用 Unstyled 區塊包裝內容以移除預設樣式。

建立您自己的文件區塊

Storybook 還提供了一個 useOf hook，使您更容易建立功能與內建區塊類似的自訂區塊。

疑難排解

為什麼我無法在我的 stories 中使用文件區塊？

Storybook 的文件區塊是高度可自訂且有用的建構區塊，可協助您建立自訂文件。儘管它們中的大多數都允許您使用參數或全域方式自訂它們以建立自訂的文件範本，但它們主要是為 MDX 檔案設計的。例如，如果您嘗試將 ColorPalette 區塊添加到您的 stories 中，如下所示，則當 story 在 Storybook 中載入時，您會收到錯誤訊息。

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { ColorItem, ColorPalette } from '@storybook/blocks';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
const theme = {
  colors: {
    primaryDark: {
      value: '#1C1C1C',
    },
    primaryRegular: {
      value: '#363636',
    },
    primaryLight1: {
      value: '#4D4D4D',
    },
    primaryLight2: {
      value: '#878787',
    },
    primaryLight3: {
      value: '#D1D1D1',
    },
    primaryLight4: {
      value: '#EDEDED',
    },
  },
};
 
// ❌ Don't use the Doc Blocks inside your stories. It will break Storybook with a cryptic error.
export const Colors: Story = {
  render: () => (
    <ColorPalette>
      {Object.entries(theme.colors).map(([key, { value }]) => (
        <ColorItem
          colors={{
            [key]: value,
          }}
          key={key}
          subtitle={`theme.colors.${key}`}
          title={key}
        />
      ))}
    </ColorPalette>
  ),
};

深入了解 Storybook 文件

• 自動文件 (Autodocs)，用於為您的 stories 建立文件
• MDX，用於自訂您的文件
• 用於撰寫您的文件的文件區塊
• 發佈文件，以自動化發佈文件的過程