背景前段时间，部门如火如荼地搞各种组件库。做一个组件库，免不了要对组件进行展示和解释，还要用到一些文档工具。我们在项目中也尝试过几种不同的文档工具，今天将一些经验分享给大家，希望对大家有所帮助。Text目前我们的组件库一共使用了三个文档工具，分别是：StoryBookDoczDumi下面我将对这三个工具进行比较，并根据实际使用情况给出一些结论。1.StoryBookStoryBook为UI组件提供了一个开发环境。它允许您浏览组件库，查看每个组件的不同状态，并交互式地开发和测试组件。目前支持react、vue、angular等前端库和框架。代码示例//Button.stories.tsximportReactfrom'react';import{Story}from'@storybook/react';}/>;exportconstPrimary=Template.bind({});Primary.args={primary:true,label:'Primary',};storybook通过Template.bind({})为通过args公开交互属性的组件绑定提供交互式组件编写。并且支持的组件库丰富，但是除了提供示例，文档的编写还需要兼容交互模式。渲染示例比如我们的SSC-UI-Vue-Pro组件库：importSTrackingHistoryfrom'./tracking-history.vue';import'./style/index.less';exportdefault{title:'DesignSystem/display/TrackingHistory',component:STrackingHistory,parameters:{docs:{description:{component:'订单历史跟踪，主要跟进时间和状态维度',},},design:{type:'figma',url:'https://www.figma.com/file/zi4Lcb2H2K5JikFKeEvPD7/WMS%E5%85%B8%E5%9E%8B%E6%A8%A1%E6%9D%BFV1.1?node-id=2974%3A595',},},argTypes:{title:{control:'text',description:'titlecontent,required',type:{required:true},},list:{control:'object',description:'历史列表',type:{required:true,summary:'array'},},},};constTemplate=(args,{argTypes})=>({components:{STrackingHistory},props:Object.keys(argTypes),template:'',});exportconstDefault=Template.bind({});(Defaultasany).args={title:'OrderTrackingHistory',list:[{time:'18:00:22',date:'2021-11-23',status:'string;//可选，def不显示ault',statusType:'default',contents:[{label:'Message',value:'LineContent[];//可选，依次显示一行内容',},{label:'Oprater',value:'LineContent[];//可选，按顺序显示每行内容',},],splitLineText:'NewOrder',},{date:'2021-1-2',status:'string;//可选，默认不显示',statusType:'default',contents:[{label:'Operator',value:'LineContent[];//可选,按顺序显示每行内容',},],},{date:'2021-11-23',status:'string;//可选，默认不显示',contents:[{value:'LineContent[];//可选，按顺序显示每行内容',},],},{date:'2021-11-23',status:'string;//可选，默认不显示',statusType:'success',contents:[],},{date:'2021-1-23',contents:[{}],},{date:'2021-1-3',},{date:'2021-11-23',内容:[{label:'消息',},],},],};2.doczDocz是一个高效、零配置的事件记录工具Docz基于MDX，内置了很多组件可以帮你记录你的东西。它还支持添加插件以通过Docz流程和数据管理许多事情。代码示例//Button.mdximport{Playground}from'docz'import{Button}from'./Button'#Button##BasicusageClickme渲染示例这是官网的示例。可以看出代码示例需要写在Playground标签中，这就带来了一个问题。无法在代码示例中编写导入模块，这对开发人员来说其实并不好。太友好了。我们的SSC-UI-React组件库使用的是docz，实际效果：3.dumidumi是组件开发场景的文档工具。它开箱即用，专注于组件开发和文档。基于TypeScript类型定义，自动生成组件API，编写移动组件库，提供多语言支持。类型定义中的代码示例：渲染示例总体对比下面是三个库的特性对比：综上所述，愉快地决定将ReactProComponents组件库文档迁移到dumi。踩坑总结1.React版本不兼容问题迁移运行后，我们yarn，发现报错：这是ts报的关于react类型检查的错误。一开始我们以为是ts里面检查太多了，所以在tsconfig.jsonconfigurationexcluded:['node-modules']去掉了这个检查，但是配置之后还是不行。仔细查看，发现yarn.lock中组件库依赖的react版本是16，而dumi依赖的react版本是*，*版本下载的是17版本的react，因为ts两个版本的react的类型不同，导致类型检查失败。这种情况下，我们只需要指定react的版本为16，16在*的范围内，就不会导致dumi报错。添加："resolutions":{"@types/react":"^16.9.23"}到package.json。2.文档引用问题由于dumi的文档是面向用户的，所以在写文档时引入组件的方法，例如：比如Button组件是：import{EditArea}from'react-pro-components'因为node_module包是这里介绍一下，它可以防止组件库的变化被映射到文档中，需要添加一个别名映射。在.umirc.ts中添加：constpath=require('path');constchainWebpack=require('webpack-chain');exportdefault{//其他配置chainWebpack(memo){//setaliasmemo.resolve.alias.set('react-pro-components',path.resolve(__dirname,'src','components'))},};三、其他问题1、dumi是否支持隐藏api文档的部分属性？2、dumi目前不支持搜索吗？site模式支持，doc模式目前不支持。3、dumi的md文件是单独放在component目录下的一个文件夹里的吗？暂时不支持，需要直接放在组件目录下，比如Button组件：├──Button│└──index.md对比了很多次得出结论之后，我们迁移了一个React组件库到dumi，取得了不错的效果。需要搭建React组件库的朋友可以关注dumi。至于vue组件文档库，大家可以根据自己的情况灵活选择。希望这篇文章能对大家有所帮助，谢谢。
