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

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

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

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

现在有 80k 的 star 了:

那 Storybook 都提供了啥功能呢?

我们试一下就知道了:

lua 复制代码
npx create-react-app --template typescript sb-test

用 cra 创建个 react 项目。

然后进入项目,执行 storybook 的初始化:

kotlin 复制代码
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 函数是可以当作测试脚本来用的。

安装用到的包:

bash 复制代码
npm install @storybook/jest

使用 expect 来断言:

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

改下 expect,断言失败就是这样:

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

就很方便。

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

安装用到的包:

dart 复制代码
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 可以指定请求的数据、自定义渲染内容、自动执行的脚本等。

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

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

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

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

相关推荐
开心工作室_kaic7 分钟前
ssm068海鲜自助餐厅系统+vue(论文+源码)_kaic
前端·javascript·vue.js
有梦想的刺儿26 分钟前
webWorker基本用法
前端·javascript·vue.js
cy玩具1 小时前
点击评论详情,跳到评论页面,携带对象参数写法:
前端
清灵xmf1 小时前
TypeScript 类型进阶指南
javascript·typescript·泛型·t·infer
小白学大数据1 小时前
JavaScript重定向对网络爬虫的影响及处理
开发语言·javascript·数据库·爬虫
qq_390161771 小时前
防抖函数--应用场景及示例
前端·javascript
334554322 小时前
element动态表头合并表格
开发语言·javascript·ecmascript
John.liu_Test2 小时前
js下载excel示例demo
前端·javascript·excel
Yaml42 小时前
智能化健身房管理:Spring Boot与Vue的创新解决方案
前端·spring boot·后端·mysql·vue·健身房管理
PleaSure乐事2 小时前
【React.js】AntDesignPro左侧菜单栏栏目名称不显示的解决方案
前端·javascript·react.js·前端框架·webstorm·antdesignpro