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

背景

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

成都创新互联公司坚持“要么做到，要么别承诺”的工作理念，服务领域包括：网站建设、成都网站设计、企业官网、英文网站、手机端网站、网站推广等服务，满足客户于互联网时代的博望网站设计、移动媒体设计的需求，帮助企业找到有效的互联网解决方案。努力成为您成熟可靠的网络建设合作伙伴！

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

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

正文

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

  1. Story Book
  2. Docz
  3. Dumi

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

1. Story Book

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

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

代码示例

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

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

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

渲染示例

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

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

2. docz

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

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

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

代码示例

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

渲染示例

这是官网的一个示例，可以看出代码的示例需要写在 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. 
  
  
  
  
  2.   "@types/react": "^16.9.23" 
    3. 
  
  
  
  
  3. } 
    4.

即可。

2.文档引用问题

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

如 Button 组件为:

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

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

在 .umirc.ts 中添加：

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

3. 其他问题

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

暂不支持

2.dumi 是否支持搜索呢?

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

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

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

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

结论

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

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

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

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

分享题目：对比三个强大的组件文档展示工具
URL分享：http://www.csdahua.cn/qtweb/news36/235686.html

网站建设、网络推广公司-快上网，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 快上网

成都快上网为您推荐相关内容

网站设计公司知识

各行业网站

成都微信开发　　 　高端网站策划　　 　seo关键词优化　　 　成都关键词SEO优化　　 　网站SEO优化　　 　网站空间　　 　攀枝花网站建设　　 　成都网页制作　　 　等级保护测评　　 　双流做网站　　 　雅安服务器托管　　 　网站seo优化　　 　绵阳发电机　　 　深圳纱窗安装　　 　重庆托管服务器　　 　成都主机托管　　 　网络推广公司　　 　成都微信小程序开发　　 　成都品牌官网设计公司　　 　眉山发电机维修