编写组件文档?用它轻松拿捏!
The following article is from 神光的编程秘籍 Author 神说要有光zxg
大家平时都在写组件,当你写组件库里的组件,或者项目里的一些公共组件的时候,是需要提供文档的。
这时候我们一般都会用 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 支持写这类脚本:
比如写g找到内容为光光光的 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 基本是最好的选择。
往期推荐