对比三个强大的组件文档展示工具

开发 开发工具
经多对比之后, 我们把一个 React 组件库 迁移到了 dumi, 并取得了不错的效果。有需要做 React 组件库的小伙伴可以留意下dumi.至于 Vue 组件文档库, 大家就根据自己的情况灵活选择吧。

背景

前段时间, 部门在热火朝天的搞各类组件库。

做组件库,不可避免的就需要做组件的展示和说明, 要用到一些文档工具。

我们项目里面也尝试了几种不同的文档工具,今天和大家分享一些经验, 希望对大家有所帮助。

正文

目前, 我们的组件库 一共使用了三种文档工具, 分别是:

  1. Story Book
  2. Docz
  3. Dumi

下面我会根据实际的使用情况,对这三种工具做一些对比 并给出一些结论。

1. Story Book

StoryBook 提供了一套UI组件的开发环境。

它允许你浏览组件库,查看每个组件的不同状态,以及交互式开发和测试组件, 目前支持 react、vue、angular 等前端类库和框架。

代码示例

  1. // Button.stories.tsx 
  2. import React from 'react'
  3. import { Story } from '@storybook/react'
  4.  
  5. // We create a “template” of how args map to rendering 
  6. const Template: Story<ButtonProps> = (args) => <Button {...args} />; 
  7.  
  8. export const Primary = Template.bind({}); 
  9.  
  10. Primary.args = { 
  11.   primarytrue
  12.   label: 'Primary'
  13. }; 

 storybook 提供可以交互的组件编写,通过 Template.bind({}) 进行组件的绑定,通过 args暴露可交互的属性。

且支持的组件库丰富,但是文档的编写除了需要提供示例外,还需要兼容可交互的模式。

渲染示例

比如我们的 SSC-UI-Vue-Pro 组件库:

  1. import STrackingHistory from './tracking-history.vue'
  2. import './style/index.less'
  3.  
  4. export default { 
  5.   title: 'Design System/展示/TrackingHistory'
  6.   component: STrackingHistory, 
  7.   parameters: { 
  8.     docs: { 
  9.       description: { 
  10.         component: '订单历史追踪,主要按时间和状态维度跟进'
  11.       }, 
  12.     }, 
  13.     design: { 
  14.       type: 'figma'
  15.       url: 
  16.         'https://www.figma.com/file/zi4Lcb2H2K5JikFKeEvPD7/WMS%E5%85%B8%E5%9E%8B%E6%A8%A1%E6%9D%BFV1.1?node-id=2974%3A595'
  17.     }, 
  18.   }, 
  19.   argTypes: { 
  20.     title: { 
  21.       control: 'text'
  22.       description: '标题内容,必填'
  23.       type: { required: true }, 
  24.     }, 
  25.     list: { 
  26.       control: 'object'
  27.       description: '历史记录列表'
  28.       type: { required: true, summary: 'array' }, 
  29.     }, 
  30.   }, 
  31. }; 
  32.  
  33. const Template = (args, { argTypes }) => ({ 
  34.   components: { STrackingHistory }, 
  35.   props: Object.keys(argTypes), 
  36.   template: '<STrackingHistory v-bind="$props" />'
  37. }); 
  38.  
  39. export const Default = Template.bind({}); 
  40. (Default as any).args = { 
  41.   title: 'Order Tracking History'
  42.   list: [ 
  43.     { 
  44.       time'18:00:22'
  45.       date'2021-11-23'
  46.       status: 'string; // 选填,缺省时不显示'
  47.       statusType: 'default'
  48.       contents: [ 
  49.         { 
  50.           label: 'Message'
  51.           value: 'LineContent[]; // 选填,按顺序展示每一行内容'
  52.         }, 
  53.         { 
  54.           label: 'Oprater'
  55.           value: 'LineContent[]; // 选填,按顺序展示每一行内容'
  56.         }, 
  57.       ], 
  58.       splitLineText: 'New Order'
  59.     }, 
  60.     { 
  61.       date'2021-1-2'
  62.       status: 'string; // 选填,缺省时不显示'
  63.       statusType: 'default'
  64.       contents: [ 
  65.         { 
  66.           label: 'Operator'
  67.           value: 'LineContent[]; // 选填,按顺序展示每一行内容'
  68.         }, 
  69.       ], 
  70.     }, 
  71.     { 
  72.       date'2021-11-23'
  73.       status: 'string; // 选填,缺省时不显示'
  74.       contents: [ 
  75.         { 
  76.           value: 'LineContent[]; // 选填,按顺序展示每一行内容'
  77.         }, 
  78.       ], 
  79.     }, 
  80.     { 
  81.       date'2021-11-23'
  82.       status: 'string; // 选填,缺省时不显示'
  83.       statusType: 'success'
  84.       contents: [], 
  85.     }, 
  86.     { 
  87.       date'2021-1-23'
  88.       contents: [{}], 
  89.     }, 
  90.     { 
  91.       date'2021-1-3'
  92.     }, 
  93.     { 
  94.       date'2021-11-23'
  95.       contents: [ 
  96.         { 
  97.           label: 'Message'
  98.         }, 
  99.       ], 
  100.     }, 
  101.   ], 
  102. }; 

2. docz

Docz 是一个高效、零配置的事件记录工具。

Docz 基于 MDX ,有许多内置的组件可以帮助你记录你的事情。

它同时支持添加插件,以便于通过 Docz 流程和数据管控很多事情。

代码示例

  1. // Button.mdx 
  2. import { Playground } from 'docz' 
  3. import { Button } from './Button' 
  4.  
  5. # Button 
  6.  
  7. ## Basic usage 
  8.  
  9. <Playground> 
  10.   <Button>Click me</Button> 
  11.   <Button kind="secondary">Click me</Button> 
  12. </Playground> 

渲染示例

这是官网的一个示例,可以看出代码的示例需要写在 Playground 标签里面,由此带来一个问题,无法在代码示例中写引入模块,这其实对开发者不太友好。

我们的 SSC-UI-React 组件库使用了docz, 实际效果:

图片

3. dumi

dumi 是一款为组件开发场景而生的文档工具。

其具有开箱即用,将注意力集中在组件开发和文档编写上。

基于 TypeScript 类型定义,自动生成组件 API、移动端组件库编写及多语言支持。

代码示例

在类型定义中:

图片

渲染示例

图片
图片

总体对比

以下为三个库的特性对比:

综上所述,愉快地决定将 React Pro Components 组件库文档迁移到 dumi 中。

踩坑总结

1. React 版本不兼容问题

一通迁移操作后,我们 yarn 了一下,发现报错了:

图片

这是 ts 报出的关于 react 类型检查的错误,一开始认为是 ts 检查多了,那么在tsconfig.json 配置 excluded:['node-modules'],将这个检查去掉,但是配完了仍然不好使。

经过一通细致的检查,在 yarn.lock 中发现组件库依赖的 react 版本是 16,而 dumi 依赖的 react 版本是*,*的版本下载了 17 版本的 react,由于两个版本的 react 的 ts 类型不同,导致了类型检查不通过。

图片
图片
图片

既然如此,我们只要显示指定 react 的版本为 16 就行了,16 在 * 的范围,也不会导致 dumi 有错误。

在 package.json 中加入:

  1. "resolutions": { 
  2.   "@types/react""^16.9.23" 

即可。

2.文档引用问题

由于 dumi 的文档是面向用户的,因此写文档时引入组件的方法,举例:

如 Button 组件为:

  1. import { EditArea } from 'react-pro-components' 

由于这里引入的是 node_module 的包,这使得组件库的更改无法映射到文档中,需要添加别名映射。

在 .umirc.ts 中添加:

  1. const path = require('path'); 
  2. const chainWebpack = require('webpack-chain'); 
  3. export default { 
  4.  // 其他配置 
  5.   chainWebpack(memo) { 
  6.     // 设置 alias 
  7.     memo.resolve 
  8.       .alias 
  9.       .set('react-pro-components', path.resolve(__dirname, 'src''components')) 
  10.   }, 
  11. }; 

3. 其他问题

1.dumi 是否支持 api 文档的部分属性隐藏呢?

暂不支持

2.dumi 是否支持搜索呢?

site 模式支持,doc 模式暂不支持。

3.dumi 是否 md 文档单独放在组件目录下的一个文件夹下呢?

暂不支持,需要直接放在组件目录下,如 Button 组件:

  1. ├── Button 
  2. │   └── index.md 

结论

经多对比之后, 我们把一个 React 组件库 迁移到了 dumi, 并取得了不错的效果。

有需要做 React 组件库的小伙伴可以留意下dumi.

至于 Vue 组件文档库, 大家就根据自己的情况灵活选择吧。

希望这篇文章能对大家有所帮助, 谢谢。

 

责任编辑:姜华 来源: 前端皮小蛋
相关推荐

2023-12-28 07:39:58

C#项目框架

2011-09-13 15:05:57

2018-08-29 05:33:52

2015-03-30 12:20:07

DemoStoryboard

2017-08-01 08:41:29

Oracle开源容器

2010-05-24 14:43:39

Linux性能监测工具

2010-03-24 10:32:05

Python多线程

2018-05-02 08:06:12

2018-10-18 08:15:27

开源分布式追踪工具

2023-07-28 09:00:00

NLP开源工具

2023-10-17 07:23:00

Vue组件代码

2010-08-24 09:10:14

Linux命令行工具

2023-04-26 11:14:11

IT领导者远程工作

2020-06-11 09:00:27

SDN网络架构网络

2020-02-02 14:45:55

联系人开源工具

2022-04-28 16:54:13

事件响应网络安全安全工具

2023-10-10 15:17:54

数据集降维技术

2021-04-28 15:07:06

鸿蒙HarmonyOS应用

2018-03-08 07:45:21

2018-02-25 07:23:23

点赞
收藏

51CTO技术栈公众号