想给组件加上文档？ 试试 Storybook

大家平时都在写组件，当你写组件库里的组件，或者项目里的一些公共组件的时候，是需要提供文档的。

这时候我们一般都会用 Storybook。

Storybook 是非常流行的用来构建组件文档的工具。

现在有 80k 的 star 了：

那 Storybook 都提供了啥功能呢？

我们试一下就知道了：

npx create-react-app --template typescript sb-test

用 cra 创建个 react 项目。

然后进入项目，执行 storybook 的初始化：

npx storybook@latest init

打印的日志告诉你 storybook init 是在你的项目里添加 storybook 的最简单方式。

执行 npm run storybook，就可以看到这样文档：

这就是 storybook 生成的组件文档。

这三个组件不是我们自己写的，是 storybook 初始化的时候自带了三个 demo 组件。

我们可以用它来了解下 storybook 的功能。

storybook init 在项目里加了 2 个目录： .storybook 和 src/stories

.storybook 下的是配置文件， src/stories 下的是组件。

比如 Button.tsx 是这样的：

传入几个参数，渲染出一个 button。

然后 Button.stories.tsx 是这样的：

导出的这几个 Story 类型的对象是啥呢？

是这个：

也就是 Button 组件传入不同参数的时候渲染的结果。

我们加一个 Story 试试：

页面多了一个 Button 的类型：

也就是说，Storybook 把同一个组件传入不同 props 的情况，叫做一个 Story。

别的地方可能叫做用例或变体，而在 Storybook 里叫做 story。

一个组件包含多个 Story，一个文档里又包含多个组件，和一本书的目录差不多。

所以把这个工具叫做 Storybook。

除了 story 外，上面还有生成的组件文档：

可以看到，列出了每个 props 和描述。

是从注释里拿到的：

我们改了一下注释，刷新下，可以看到文档变了：

这样就可以方便的生成组件文档了。

而且，这些参数都是可以调的：

可以直接修改 props 看组件渲染结果，就很方便。

而且你还可以直接复制它的 jsx 代码：

之前我们是 args 传入参数渲染，你还可以用 render 函数的方式自己渲染：

render 函数的参数就是 args，你可以自己返回 jsx（这时要把文件后缀名改为 tsx）。

这样，渲染内容就是自己控制的：

而且有的组件不只是传入 props 就可以了，还需要一些点击、输入等事件。

storybook 支持写这类脚本：

比如我写了找到内容为光光光的 button，点击，然后把它的内容改为东。

组件渲染完就会自动执行 play 函数：

当然，这个案例不大好，用表单来测试 play 功能会更好点：

此外，你还可以在渲染组件之前请求数据，然后把数据传入 render 函数再渲染：

渲染出来是这样的：

感受到 Storybook 的强大了么？

不只是自动生成组件文档这么简单，你可以定义不同的 Story，这些 Story 可以传入不同 props、可以请求数据、可以自定义渲染内容、还可以定义自动执行的脚本。

有同学会觉得，这个自动执行的 play 函数其实和测试脚本差不多。

确实，play 函数是可以当作测试脚本来用的。

安装用到的包：

npm install @storybook/jest

使用 expect 来断言：

这样一打开组件会自动跑 play 函数，也就会自动执行断言：

改下 expect，断言失败就是这样：

这样，组件有没有通过测试用例，打开一看就知道了。

就很方便。

但是，组件多了的话，这样一个个点开看也挺麻烦的，这时候就可以用 cli 跑了：

安装用到的包：

npm install @storybook/testing-library

然后：

npx test-storybook

xx.stories.tsx 文件里除了 Story 外，还会导出 meta 信息：

这些都很简单，改一下就知道了：

title 是这个：

paremeters 的 layout 是这个：

这里还可以配置背景色：

然后 argTypes 是这个：

这些都是与 Story 无关的一些东西，所以放在 Meta 里。

此外，你还可以用 Storybook 写 MDX 文档。

mdx 是 markdown + jsx 的混合语法，用来写文档很不错。

在这个目录下的文档：

都会被放到这里：

我们加一个试试：

这样，当你想在组件文档里加一些别的说明文档，就可以这样加。

而且，组件文档的格式也是可以自定义的。

可以在 .storybook 下的 preview.tsx 里配置这个：

总结

写组件文档，我们一般都是用 Storybook。

它把不同 props 的渲染结果叫做一个 story，一个组件有多个 story。

story 可以指定传入组件的参数、请求的数据、通过render自定义渲染内容、自动执行的play脚本等。

而且还可以渲染完组件直接跑测试用例，就很方便。

storybook 还会自动生成组件文档，而且也可以把项目里的 mdx 文件加到文档里。

总之，用 storybook 可以轻松的创建组件文档，可以写多个 story，直观的看到组件不同场景下的渲染结果，还可以用来做测试。

如果想给你的组件加上文档，storybook 基本是最好的选择。