文档

在 Markdown 中记录组件用法和属性

每周下载量

Storybook 文档

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

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	+	+	+		+	+

注意： # = WIP 支持 (正在进行中)

想为您喜爱的框架添加增强功能吗？请查阅这篇开发指南

安装

首先添加软件包。确保您的 @storybook/* 软件包版本匹配

yarn add -D @storybook/addon-docs

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 选项非常有用。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 配合使用。对于高级配置选项，请参阅属性文档。

文档