Storybook 文档

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

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

DocsPage. 开箱即用，您的所有 stories 都会获得一个 DocsPage。 DocsPage 是对您的组件 stories、文本描述、文档生成注释、属性表和代码示例进行的零配置聚合，生成简洁易读的页面。

MDX. 如果您需要更多控制权，MDX 允许您在同一个文件中编写详细的 markdown 文档和 stories。您还可以使用它来编写纯文档页面，并将其嵌入到您的 Storybook 中，与您的 stories 并列。

与 Storybook 一样，Docs 支持所有主要视图层，包括 React, Vue, Angular, HTML, Web 组件, Svelte 等等。

继续阅读以了解更多信息

Storybook 文档

DocsPage

当您安装 Docs时，每个 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

Docs 的 peer dependencies 依赖于 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 时，它会告诉 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 一起使用。有关高级配置选项，请参阅 Props 文档。