背景

前段時(shí)間， 部門在熱火朝天的搞各類組件庫(kù)。

做組件庫(kù)，不可避免的就需要做組件的展示和說(shuō)明， 要用到一些文檔工具。

我們項(xiàng)目里面也嘗試了幾種不同的文檔工具，今天和大家分享一些經(jīng)驗(yàn)， 希望對(duì)大家有所幫助。

正文

目前， 我們的組件庫(kù) 一共使用了三種文檔工具， 分別是：

1. Story Book
2. Docz
3. Dumi

下面我會(huì)根據(jù)實(shí)際的使用情況，對(duì)這三種工具做一些對(duì)比 并給出一些結(jié)論。

1. Story Book

StoryBook 提供了一套UI組件的開(kāi)發(fā)環(huán)境。

它允許你瀏覽組件庫(kù)，查看每個(gè)組件的不同狀態(tài)，以及交互式開(kāi)發(fā)和測(cè)試組件， 目前支持 react、vue、angular 等前端類庫(kù)和框架。

代碼示例

// Button.stories.tsx 
import React from 'react'; 
import { Story } from '@storybook/react'; 
 
// We create a “template” of how args map to rendering 
const Template: Story<ButtonProps> = (args) => <Button {...args} />; 
 
export const Primary = Template.bind({}); 
 
Primary.args = { 
  primary: true, 
  label: 'Primary', 
}; 

 storybook 提供可以交互的組件編寫(xiě)，通過(guò) Template.bind({}) 進(jìn)行組件的綁定，通過(guò) args暴露可交互的屬性。

且支持的組件庫(kù)豐富，但是文檔的編寫(xiě)除了需要提供示例外，還需要兼容可交互的模式。

渲染示例

比如我們的 SSC-UI-Vue-Pro 組件庫(kù)：

import STrackingHistory from './tracking-history.vue'; 
import './style/index.less'; 
 
export default { 
  title: 'Design System/展示/TrackingHistory', 
  component: STrackingHistory, 
  parameters: { 
    docs: { 
      description: { 
        component: '訂單歷史追蹤，主要按時(shí)間和狀態(tài)維度跟進(jìn)', 
      }, 
    }, 
    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: '標(biāo)題內(nèi)容，必填', 
      type: { required: true }, 
    }, 
    list: { 
      control: 'object', 
      description: '歷史記錄列表', 
      type: { required: true, summary: 'array' }, 
    }, 
  }, 
}; 
 
const Template = (args, { argTypes }) => ({ 
  components: { STrackingHistory }, 
  props: Object.keys(argTypes), 
  template: '<STrackingHistory v-bind="$props" />', 
}); 
 
export const Default = Template.bind({}); 
(Default as any).args = { 
  title: 'Order Tracking History', 
  list: [ 
    { 
      time: '18:00:22', 
      date: '2021-11-23', 
      status: 'string; // 選填，缺省時(shí)不顯示', 
      statusType: 'default', 
      contents: [ 
        { 
          label: 'Message', 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
        { 
          label: 'Oprater', 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
      ], 
      splitLineText: 'New Order', 
    }, 
    { 
      date: '2021-1-2', 
      status: 'string; // 選填，缺省時(shí)不顯示', 
      statusType: 'default', 
      contents: [ 
        { 
          label: 'Operator', 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
      ], 
    }, 
    { 
      date: '2021-11-23', 
      status: 'string; // 選填，缺省時(shí)不顯示', 
      contents: [ 
        { 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
      ], 
    }, 
    { 
      date: '2021-11-23', 
      status: 'string; // 選填，缺省時(shí)不顯示', 
      statusType: 'success', 
      contents: [], 
    }, 
    { 
      date: '2021-1-23', 
      contents: [{}], 
    }, 
    { 
      date: '2021-1-3', 
    }, 
    { 
      date: '2021-11-23', 
      contents: [ 
        { 
          label: 'Message', 
        }, 
      ], 
    }, 
  ], 
}; 

2. docz

Docz 是一個(gè)高效、零配置的事件記錄工具。

Docz 基于 MDX ，有許多內(nèi)置的組件可以幫助你記錄你的事情。

它同時(shí)支持添加插件，以便于通過(guò) Docz 流程和數(shù)據(jù)管控很多事情。

代碼示例

// Button.mdx 
import { Playground } from 'docz' 
import { Button } from './Button' 
 
# Button 
 
## Basic usage 
 
<Playground> 
  <Button>Click me</Button> 
  <Button kind="secondary">Click me</Button> 
</Playground> 

渲染示例

這是官網(wǎng)的一個(gè)示例，可以看出代碼的示例需要寫(xiě)在 Playground 標(biāo)簽里面，由此帶來(lái)一個(gè)問(wèn)題，無(wú)法在代碼示例中寫(xiě)引入模塊，這其實(shí)對(duì)開(kāi)發(fā)者不太友好。

我們的 SSC-UI-React 組件庫(kù)使用了docz, 實(shí)際效果：

3. dumi

dumi 是一款為組件開(kāi)發(fā)場(chǎng)景而生的文檔工具。

其具有開(kāi)箱即用，將注意力集中在組件開(kāi)發(fā)和文檔編寫(xiě)上。

基于 TypeScript 類型定義，自動(dòng)生成組件 API、移動(dòng)端組件庫(kù)編寫(xiě)及多語(yǔ)言支持。

代碼示例

在類型定義中：

渲染示例

總體對(duì)比

以下為三個(gè)庫(kù)的特性對(duì)比：

綜上所述，愉快地決定將 React Pro Components 組件庫(kù)文檔遷移到 dumi 中。

踩坑總結(jié)

1. React 版本不兼容問(wèn)題

一通遷移操作后，我們 yarn 了一下，發(fā)現(xiàn)報(bào)錯(cuò)了:

這是 ts 報(bào)出的關(guān)于 react 類型檢查的錯(cuò)誤，一開(kāi)始認(rèn)為是 ts 檢查多了，那么在tsconfig.json 配置 excluded：['node-modules']，將這個(gè)檢查去掉，但是配完了仍然不好使。

經(jīng)過(guò)一通細(xì)致的檢查，在 yarn.lock 中發(fā)現(xiàn)組件庫(kù)依賴的 react 版本是 16，而 dumi 依賴的 react 版本是*，*的版本下載了 17 版本的 react，由于兩個(gè)版本的 react 的 ts 類型不同，導(dǎo)致了類型檢查不通過(guò)。

既然如此，我們只要顯示指定 react 的版本為 16 就行了，16 在 * 的范圍，也不會(huì)導(dǎo)致 dumi 有錯(cuò)誤。

在 package.json 中加入：

"resolutions": { 
  "@types/react": "^16.9.23" 
} 

即可。

2.文檔引用問(wèn)題

由于 dumi 的文檔是面向用戶的，因此寫(xiě)文檔時(shí)引入組件的方法，舉例:

如 Button 組件為:

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

由于這里引入的是 node_module 的包，這使得組件庫(kù)的更改無(wú)法映射到文檔中，需要添加別名映射。

在 .umirc.ts 中添加：

const path = require('path'); 
const chainWebpack = require('webpack-chain'); 
export default { 
 // 其他配置 
  chainWebpack(memo) { 
    // 設(shè)置 alias 
    memo.resolve 
      .alias 
      .set('react-pro-components', path.resolve(__dirname, 'src', 'components')) 
  }, 
}; 

3. 其他問(wèn)題

1.dumi 是否支持 api 文檔的部分屬性隱藏呢?

暫不支持

2.dumi 是否支持搜索呢?

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

3.dumi 是否 md 文檔單獨(dú)放在組件目錄下的一個(gè)文件夾下呢?

暫不支持，需要直接放在組件目錄下，如 Button 組件：

├── Button 
│   └── index.md 

結(jié)論

經(jīng)多對(duì)比之后， 我們把一個(gè) React 組件庫(kù) 遷移到了 dumi, 并取得了不錯(cuò)的效果。

有需要做 React 組件庫(kù)的小伙伴可以留意下dumi.

至于 Vue 組件文檔庫(kù)， 大家就根據(jù)自己的情況靈活選擇吧。

希望這篇文章能對(duì)大家有所幫助， 謝謝。