🤩 對比三個強大的組件文檔展現工具

背景

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

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

咱們項目裏面也嘗試了幾種不一樣的文檔工具，今天和你們分享一些經驗， 但願對你們有所幫助。

正文

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

1. Story Book
2. Docz
3. Dumi

下面我會根據實際的使用狀況，對這三種工具作一些對比 並給出一些結論。

1. Story Book

StoryBook 提供了一套UI組件的開發環境。

它容許你瀏覽組件庫，查看每一個組件的不一樣狀態，以及交互式開發和測試組件， 目前支持 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({}) 進行組件的綁定，經過 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: '訂單歷史追蹤，主要按時間和狀態維度跟進',
      },
    },
    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: '標題內容，必填',
      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[]; // 選填，按順序展現每一行內容',
        },
        {
          label: 'Oprater',
          value: 'LineContent[]; // 選填，按順序展現每一行內容',
        },
      ],
      splitLineText: 'New Order',
    },
    {
      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',
      contents: [
        {
          label: 'Message',
        },
      ],
    },
  ],
};

2. docz

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

Docz 基於 MDX ，有許多內置的組件能夠幫助你記錄你的事情。

它同時支持添加插件，以便於經過 Docz 流程和數據管控不少事情。

代碼示例

// 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>

渲染示例

這是官網的一個示例，能夠看出代碼的示例須要寫在 Playground 標籤裏面，由此帶來一個問題，沒法在代碼示例中寫引入模塊，這其實對開發者不太友好。

咱們的 SSC-UI-React 組件庫使用了docz, 實際效果：

3. dumi

dumi 是一款爲組件開發場景而生的文檔工具。

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

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

代碼示例

在類型定義中：

渲染示例

整體對比

如下爲三個庫的特性對比：

	docz	story book	dumi
支持編寫的組件庫類型	all ✅	all ✅	React Only
輕量級 / 開發者友好	❌	❌	✅
文檔內嵌在組件目錄中	❌	✅	✅
將引入模塊寫在代碼示例中	❌	❌	✅
自動生成組件庫 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 中加入：

"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) {
    // 設置 alias
    memo.resolve
      .alias
      .set('react-pro-components', path.resolve(__dirname, 'src', 'components'))
  },
};

3. 其餘問題

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

暫不支持

1. dumi 是否支持搜索呢?

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

1. dumi 是否 md 文檔單獨放在組件目錄下的一個文件夾下呢？

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

├── Button
│   └── index.md

結論

經多對比以後， 咱們把一個 React 組件庫 遷移到了 dumi, 並取得了不錯的效果。

有須要作 React 組件庫的小夥伴能夠留意下dumi.

至於 Vue 組件文檔庫， 你們就根據本身的狀況靈活選擇吧。

但願這篇文章能對你們有所幫助， 謝謝。

最後

若是以爲內容有幫助， 能夠關注下個人公衆號，掌握最新動態，一塊兒學習！

相關連接

1. https://zhuanlan.zhihu.com/p/...
2. https://storybook.js.org/docs...
3. https://d.umijs.org/zh-CN