Storybook 文档

迁移指南：此页面记录了最近在 5.3.0 版本中引入的配置 Storybook 的方法，如果您想迁移到这种 Storybook 配置格式，请参考迁移指南。

Storybook 文档将您的 Storybook 故事转换为世界一流的组件文档。

DocsPage。默认情况下，所有故事都获得一个 DocsPage。DocsPage 是一个零配置的聚合，它将组件故事、文本描述、docgen 注释、属性表和代码示例整合到干净易读的页面中。

MDX。如果您想要更多控制权，MDX 允许您在一个文件中编写长篇 Markdown 文档和故事。您还可以使用它来编写纯文档页面，并将它们嵌入到 Storybook 中，与您的故事并排。

与 Storybook 一样，Docs 支持所有主要的视图层，包括 React、Vue、Angular、HTML、Web 组件、Svelte，以及更多。

继续阅读以了解更多信息

Storybook 文档

DocsPage

当您安装 Docs时，每个故事都会获得一个 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 Docs 支持 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

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 时，它告诉 docs 不要完全运行 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 Docs 开箱即用。有关高级配置选项，请参考属性文档。