Storybook 文件

遷移指南：此頁面記錄了最近在 5.3.0 中引入的 storybook 配置方法，如果您想遷移到這種配置 storybook 的格式，請參考遷移指南。

Storybook 文件將您的 Storybook 故事轉換為世界級的元件文件。

DocsPage。 開箱即用，您的所有故事都會獲得一個 DocsPage。DocsPage 將您的元件故事、文字描述、docgen 註解、屬性表格和程式碼範例零配置地整合到清晰、可讀的頁面中。

MDX。 如果您想要更多控制權，MDX 允許您在一個檔案中撰寫長篇 markdown 文件和故事。您也可以使用它來撰寫純文件頁面，並將它們嵌入到您的 Storybook 中，與您的故事並排。

就像 Storybook 一樣，文件支援每個主要視圖層，包括 React、Vue、Angular、HTML、Web 元件、Svelte 以及更多。

繼續閱讀以了解更多資訊

Storybook 文件

DocsPage

當您安裝文件時，每個故事都會獲得一個 DocsPage。DocsPage 從您的故事、元件、原始碼和故事元數據中提取資訊，以建構一個明智的、零配置的預設值。

點擊 Docs 標籤即可查看

如需更多關於其運作方式的資訊，請參閱DocsPage 參考。

MDX

MDX 是一種用於在同一個檔案中並排撰寫長篇文件和故事的語法。與提供開箱即用的智慧文件的 DocsPage 不同，MDX 讓您可以完全控制元件文件。

這是一個範例檔案

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Checkbox } from './Checkbox';

<Meta title="MDX/Checkbox" component={Checkbox} />

# Checkbox

With `MDX` we can define a story for `Checkbox` right in the middle of our
markdown documentation.

<Canvas>
  <Story name="all checkboxes">
    <form>
      <Checkbox id="Unchecked" label="Unchecked" />
      <Checkbox id="Checked" label="Checked" checked />
      <Checkbox appearance="secondary" id="second" label="Secondary" checked />
    </form>
  </Story>
</Canvas>

這是在 Storybook 中呈現的方式

如需更多關於 MDX 的資訊，請參閱MDX 參考。

框架支援

Storybook 文件支援 Storybook 支援的所有視圖層，除了 React Native（目前）。還有一些特定於框架的功能，例如屬性表格和內嵌故事呈現。此圖表捕獲了目前的支援狀態

	React	Vue	Angular	Ember	Web 元件	HTML	Svelte	Preact	Riot	Mithril	Marko
MDX 故事	+	+	+	+	+	+	+	+	+	+	+
CSF 故事	+	+	+	+	+	+	+	+	+	+	+
StoriesOf 故事	+	+	+	+	+	+	+	+	+	+	+
原始碼	+	+	+	+	+	+	+	+	+	+	+
註解/資訊	+	+	+	+	+	+	+	+	+	+	+
屬性表格	+	+	+	+	+
屬性控制項	+	+	+
描述	+	+	+	+	+
內嵌故事	+	+	+		+	+

注意： # = WIP 支援

想要為您最喜歡的框架新增增強功能嗎？請查看此開發指南

安裝

首先新增套件。確保您的 @storybook/* 套件的版本相符

yarn add -D @storybook/addon-docs

文件對 react 和 babel-loader 有對等依賴。如果您想在 MDX 中撰寫故事，您可能還需要新增這些依賴項

yarn add -D react babel-loader

然後將以下內容新增至您的 .storybook/main.js

module.exports = {
  stories: ['../src/**/*.stories.@(js|mdx)'],
  addons: ['@storybook/addon-docs'],
};

如果與storyshots 擴充功能一起使用，您需要配置 Jest 將 MDX 故事轉換為 Storyshots 可以理解的內容

將以下內容新增至您的 Jest 配置

{
  "transform": {
    "^.+\\.[tj]sx?$": "babel-jest",
    "^.+\\.mdx$": "@storybook/addon-docs/jest-transform-mdx"
  }
}

請務必檢查特定框架的安裝需求

預設選項

addon-docs 預設值有一些配置選項，可用於配置其 babel/webpack 載入行為。以下是使用帶有選項的預設值的範例

module.exports = {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        configureJSX: true,
        babelOptions: {},
        sourceLoaderOptions: null,
        transcludeMarkdown: true,
      },
    },
  ],
};

當您在 MDX 中撰寫文件且您的專案的 babel 配置尚未設定為處理 JSX 檔案時，configureJSX 選項非常有用。當您使用 configureJSX 時，babelOptions 是一種進一步配置 babel 處理器的方式。

sourceLoaderOptions 是一個用於配置 @storybook/source-loader 的物件。當設定為 null 時，它會告訴文件完全不執行 source-loader，這可以用作最佳化，或者如果您已經在 main.js 中使用 source-loader。

transcludeMarkdown 選項允許 mdx 檔案匯入 .md 檔案並將其呈現為元件。

import { Meta } from '@storybook/addon-docs/blocks';
import Changelog from '../CHANGELOG.md';

<Meta title="Changelog" />

<Changelog />

手動配置

我們建議使用預設值，它應該可以開箱即用。如果您不想使用預設值，並且更喜歡「長路漫漫」的配置，請將以下配置新增至 .storybook/main.js（請參閱內聯註解以取得說明）

const createCompiler = require('@storybook/addon-docs/mdx-compiler-plugin');

module.exports = {
  // 1. register the docs panel (as opposed to '@storybook/addon-docs' which
  //    will configure everything with a preset)
  addons: ['@storybook/addon-docs/register'],
  // 2. manually configure webpack, since you're not using the preset
  webpackFinal: async (config) => {
    config.module.rules.push({
      // 2a. Load `.stories.mdx` / `.story.mdx` files as CSF and generate
      //     the docs page from the markdown
      test: /\.(stories|story)\.mdx$/,
      use: [
        {
          loader: 'babel-loader',
          // may or may not need this line depending on your app's setup
          options: {
            plugins: ['@babel/plugin-transform-react-jsx'],
          },
        },
        {
          loader: '@mdx-js/loader',
          options: {
            compilers: [createCompiler({})],
          },
        },
      ],
    });
    // 2b. Run `source-loader` on story files to show their source code
    //     automatically in `DocsPage` or the `Source` doc block.
    config.module.rules.push({
      test: /\.(stories|story)\.[tj]sx?$/,
      loader: require.resolve('@storybook/source-loader'),
      exclude: [/node_modules/],
      enforce: 'pre',
    });
    return config;
  },
};

您還需要在 .storybook/preview.js 中設定 docs 參數。這包括用於呈現頁面的 DocsPage、容器，以及各種配置選項，例如用於手動提取元件描述的 extractComponentDescription

import { addParameters } from '@storybook/react';
import { DocsPage, DocsContainer } from '@storybook/addon-docs/blocks';

addParameters({
  docs: {
    container: DocsContainer,
    page: DocsPage,
  },
});

TypeScript 配置

從 SB6 開始，TypeScript 是零配置的，應該可以與 SB 文件開箱即用。如需進階配置選項，請參閱屬性文件。