最近在做的新项目是使用 React 构建一个新的网站,实现新的需求的同时慢慢将旧网站迁移过来。其中的一部分工作是建立一个可重用的前端组件库。
实现一个前端组件库需要非常多的工作量,这里有一份详细的 Checklist 可供参考。除此之外,我们还需要为这些可重用组件建立一份文档,这样大家就可以照着文档去使用这些组件了。在对比了一些文档工具后,我选择了 Storybook 这款非常小清新的可视化组件文档生成器。它支持各种主流框架。
集成 Storybook 到项目的过程遇到了不少坑,不过这篇博客我们暂时不讨论这些,有空的话我再另开一篇文章吧。本文我想聊聊写文档的时候遇到的一些需求。
背景
在项目中我们使用了一款自制的图标字体(Icon Font),以字体的形式将网站常用的图标打包成 Web Font,然后再在页面中使用。
从设计师同事那获得的素材文件如下:
~/Downloads/racing20_march
├── fonts
│ ├── racing20.eot
│ ├── racing20.svg
│ ├── racing20.ttf
│ └── racing20.woff
├── icons-reference.html
└── styles.css
其中 icons-reference.html
是说明文档,内里介绍了如何使用这个字体,以及一个图标名称及对应字符的映射关系。
所谓映射(Mapping),可以从 styles.css
中看到一些例子:
.icon-article:before {
content: "\61";
}
.icon-calendar:before {
content: "\64";
}
...
即 article
图标对应的字符是 \61
即字母 a
。
不过使用的时候我们并不需要关心这个映射。只要知道想用这个图标的话,引用对应的英文名即可:
<i class="icon icon-article"></i>
需求
我们要做的正是将这个说明文档中的映射关系集成到我们的 Storybook 组件文档中去。以便在文档中显示所有图标,还可以直接点击图标复制组件代码,方便引用。
一个简单的方法就是手动创建这个列表,把映射关系整理到一个数组中。但是考虑到后期的维护,如新增图标或者映射有变化,就需要重新校对这个列表,是一件很麻烦的事。
既然如此,何不一开始就将其自动化?我们只需要写一个脚本将这个 styles.css
中的映射关系提取出来,就可以为我所用。另外这个 styles.css
作为唯一数据源,更新起来也很方便,直接将设计师提供的新文件覆盖旧文件即可。符合 Single Source of Truth
原则。