Storybook 文档

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

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

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

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

就像 Storybook 一样，Docs 支持所有主要的视图层，包括 React、Vue、Angular、HTML、Web Components、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 Components	HTML	Svelte	Preact	Riot	Mithril	Marko
MDX 故事	+	+	+	+	+	+	+	+	+	+	+
CSF 故事	+	+	+	+	+	+	+	+	+	+	+
StoriesOf 故事	+	+	+	+	+	+	+	+	+	+	+
来源	+	+	+	+	+	+	+	+	+	+	+
注释/信息	+	+	+	+	+	+	+	+	+	+	+
属性表	+	+	+	+	+
属性控件	+	+	+
描述	+	+	+	+	+
内联故事	+	+	+		+	+

注意：# = 正在开发中的支持

想要为您最喜欢的框架添加增强功能？请查看此开发指南

安装

首先添加包。确保您的 @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 开箱即用。有关高级配置选项，请参阅属性文档。