文件

在 Markdown 中記錄元件用法和屬性

在 Github 上檢視

每週下載次數

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 故事	+	+	+	+	+	+	+	+	+	+	+
原始碼	+	+	+	+	+	+	+	+	+	+	+
筆記 / 資訊	+	+	+	+	+	+	+	+	+	+	+
屬性表	+	+	+	+	+
屬性控制項	+	+	+
描述	+	+	+	+	+
內聯故事	+	+	+		+	+

注意： # = 正在開發中的支援

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

安裝

首先新增套件。確保您的 @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 選項非常有用。babelOptions 是在您使用 configureJSX 時進一步設定 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 中設定文件參數。這包括用於呈現頁面的 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 文件開箱即用。有關進階組態選項，請參閱屬性文件。

文件