Storybook 文件

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

Storybook 文件將您的 Storybook Stories 轉換為世界一流的元件文件。

DocsPage。 所有您的 Stories 都會直接獲得一個 DocsPage。 DocsPage 是一個零配置的聚合，將您的元件 Stories、文字描述、docgen 註解、屬性表格和程式碼範例整合到簡潔、易讀的頁面中。

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

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

繼續閱讀以了解更多

Storybook 文件

DocsPage

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

點擊 Docs 標籤以查看

有關其工作原理的更多資訊，請參閱 DocsPage 參考。

MDX

MDX 是一種語法，用於在同一個檔案中並排撰寫長篇幅的文件和 Stories。與提供現成智慧文件的 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（目前）。還有一些特定於框架的功能，例如屬性表格和內嵌 Story 渲染。此圖表捕捉了目前支援的狀態

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

注意： # = 開發中支援

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

安裝

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

yarn add -D @storybook/addon-docs

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

yarn add -D react babel-loader

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

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

如果與storyshots 擴充套件一起使用，您需要設定 Jest 以將 MDX Stories 轉換為 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 文件一起使用。有關進階設定選項，請參閱屬性文件。