组件库文档和示例的书写方案

2020.6.21
开发一套UI组件很重要的配套就是示例和文档，有多种方案。

• 手工维护方案：首先想到了就是建工程手动引用组件，书写示例和说明，并遵循一定的规则和样式以保证风格的统一；

• elementUI方案：第一种方法纯人工维护，不利于扩展，elementUI中示例和说明按照一定规则写在md文件中，调用md-loader将md文件转成相应的页面，组件库维护者，只需要书写md文件即可自动地生成对应的文档页面。

  md示例 页面效果图

• stroybook方案：最近，看到有一种叫做storybook的解决方案。效果图可参看storybook-hero-video-optimized，vue guide可参考guide-vue，开发实践见StoryBook实战。storybook对于组件的开发、测试、文档化非常方便。
  这块暂时没有使用，初步感觉：
  elementUI方案更为方便且灵活（书写md文件不比写代码方式更easy吗）
  storyBook更为通用和更易上手（不用像elementUI方案那样需要搭建一套工程）
  storyBook方式因其通用和简洁，开发人员可以很方便地书写示例和文档，并嵌入到组件（库）中
storyBook方式就像写测试用例一样生成示例和文档，更利于测试人员进行测试

下面引述网上的观点。

Storybook是UI组件的开发环境。它允许您浏览组件库，查看每个组件的不同状态，以及交互式开发和测试组件。

storybook优点：

支持的主流前端框架
为组件提供独立的开发环境
多种测试场景，全面测试组件
使用MarkDown编写备注
众多的Addon，方便扩展
这些对于前端开发的工作，提供了不少改进：

避免混乱的重复代码，提高代码复用性
测试人员可以直接测试组件
丰富的Story，所见即所得
组件开发，督促开发者提高自身技能
Markdown的文档，方便展示组件

storybook问题：

Addon太多，管理有些混乱
支持UI框架多，但是有的Andon却不是所有UI框架都支持，比如info，具体可参见文档3
大版本之间变化大，从网上找到的示例代码比较老，不能用
不知道是否支持国际化

限于经验，如有不足，不吝指教。