背景

前段時間， 部門在熱火朝天的搞各類組件庫。

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

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

正文

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

1. Story Book
2. Docz
3. Dumi

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

1. Story Book

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

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

代碼示例

// 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 提供可以交互的組件編寫，通過 Template.bind({}) 進(jìn)行組件的綁定，通過 args暴露可交互的屬性。

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

渲染示例

比如我們的 SSC-UI-Vue-Pro 組件庫：

import STrackingHistory from './tracking-history.vue'; 
import './style/index.less'; 
 
export default { 
  title: 'Design System/展示/TrackingHistory', 
  component: STrackingHistory, 
  parameters: { 
    docs: { 
      description: { 
        component: '訂單歷史追蹤，主要按時間和狀態(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; // 選填，缺省時不顯示', 
      statusType: 'default', 
      contents: [ 
        { 
          label: 'Message', 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
        { 
          label: 'Oprater', 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
      ], 
      splitLineText: 'New Order', 
    }, 
    { 
      date: '2021-1-2', 
      status: 'string; // 選填，缺省時不顯示', 
      statusType: 'default', 
      contents: [ 
        { 
          label: 'Operator', 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
      ], 
    }, 
    { 
      date: '2021-11-23', 
      status: 'string; // 選填，缺省時不顯示', 
      contents: [ 
        { 
          value: 'LineContent[]; // 選填，按順序展示每一行內(nèi)容', 
        }, 
      ], 
    }, 
    { 
      date: '2021-11-23', 
      status: 'string; // 選填，缺省時不顯示', 
      statusType: 'success', 
      contents: [], 
    }, 
    { 
      date: '2021-1-23', 
      contents: [{}], 
    }, 
    { 
      date: '2021-1-3', 
    }, 
    { 
      date: '2021-11-23', 
      contents: [ 
        { 
          label: 'Message', 
        }, 
      ], 
    }, 
  ], 
}; 

2. docz

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

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

它同時支持添加插件，以便于通過 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)的一個示例，可以看出代碼的示例需要寫在 Playground 標(biāo)簽里面，由此帶來一個問題，無法在代碼示例中寫引入模塊，這其實(shí)對開發(fā)者不太友好。

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

3. dumi

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

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

基于 TypeScript 類型定義，自動生成組件 API、移動端組件庫編寫及多語言支持。

代碼示例

在類型定義中：

渲染示例

總體對比

以下為三個庫的特性對比：

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

踩坑總結(jié)

1. React 版本不兼容問題

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

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

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

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

在 package.json 中加入：

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

即可。

2.文檔引用問題

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

如 Button 組件為:

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

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

在 .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. 其他問題

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

暫不支持

2.dumi 是否支持搜索呢?

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

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

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

├── Button 
│   └── index.md 

結(jié)論

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

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

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

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