對于前端團隊來說，公共組件庫是必須的，緊接著就是完善組件庫的文檔

社區里關于快速生成文檔的工具有很多，如 StoryBook、Docz、Gatsby

在調研了幾種文檔工具之后，最終我選擇了 umi 家族的另一個成員：dumi

因為它集成了 docz，以及打包工具father-build，同時支持創建自己的Markdown 組件

當然最重要的是，我的項目是基于 umi 構建的

一、啟動

首先創建一個項目目錄

mkdir myapp && cd myapp

然后初始化組件庫，這里有兩種選擇：

1. 文檔模式：

yarn create @umijs/dumi-lib

2. 站點模式

yarn create @umijs/dumi-lib --site

創建項目后，首先執行yarn 安裝依賴，然后執行yarn start 即可查看文檔項目

// 接下來將介紹文檔模式，主要針對 dumi 官網中沒有詳細描述的地方進行補充

二、組件庫打包

組件庫的依賴項dependencies應該只包含自身用到的模塊，如classnames

其他的依賴應該盡量用peerDependencies 和devDependencies 來管理

組件庫的入口是文件是 index.ts，需要打包的組件都應該從這里導出

dumi 使用 father-build 來打包，其配置文件是.fatherrc.ts，詳細配置可以參考 father 的文檔

假如 src 目錄下有一個 Button 組件：

// src/Button/index.tsx

import React from 'react';
import './index.less';

const Button: React.FC<any> = () => {
  // ...
}

export default Button;

只需要在 src/index.ts 中導出該組件：

// src/index.ts

export { default as Button } from './Button';

然后簡單的配置下.fatherrc.ts

// .fatherrc.ts

export default {
  esm: 'rollup',
};

就能使用yarn build 打包組件庫了

打包后的文件在 dist 目錄下，另外在 package.json 中已經默認配置好了路徑

接下來只需要 npm publish 發布到自己配置的 npm 倉庫就行

如果在打包的過程中遇到問題，可以到father 的 GitHub 倉庫中找找issues

三、文檔站點

組件打包已經搞定，接下來就是完善組件的文檔

dumi 會基于 src 目錄下的 index.md 文件（或者 README.md）生成頁面及默認路由

比如剛才的 Button 組件，目錄下有一個 index.md（src/Button/index.md）

在瀏覽器中就能通過http://localhost:8000/button 訪問到該頁面

1. 組件 Demo

dumi 可以直接在Markdown 文件中寫 jsx，然后會在頁面中渲染成組件

```jsx
import React from 'react';

export default () => <h1>Hello dumi!</h1>;
```

如果不希望代碼塊被渲染，可以使用pure 修飾符

```jsx | pure
import React from 'react';

export default () => <h1>Hello dumi!</h1>;
```

更多的用法可以參考官網《寫組件 demo》

2. 自定義導航與分組

dumi 導航是基于文件目錄來的，首頁渲染的是docs/index.md

其他的導航路徑默認是根據 src 下的文件結構生成的

比如這樣的文件結構：

會生成這樣的導航：

如果希望自定義導航（分組、排序、改標題），可以在 Markdown 文件頂部編寫 FrontMatter

---
title: 自定義頁面名稱
nav:
  path: /自定義導航路由
  title: 自定義導航名稱
  order: 控制導航順序，數字越小越靠前，默認以路徑長度和字典序排序
group:
  path: /自定義分組路由，注意，分組路由 = 導航路由 + 自己
  title: 自定義分組名稱
  order: 控制分組順序，數字越小越靠前，默認以路徑長度和字典序排序
---

<!-- 其他 Markdown 內容 -->

比如這樣的結構

其中 Button 和 Select 組件可以歸類為“表單組件”，Container 可以歸類為“布局組件”

那就可以在 Container 組件的 index.md 文件頂部添加“布局組件”的分組信息：

---
order: 1
group:
  path: /layout
  title: 布局組件
  order: 1
---

然后在 Button、Select 組件的 index.md 文件頂部添加“表單組件”的分組信息：

---
order: 2
group:
  path: /form
  title: 表單組件
  order: 2
---

順便給首頁文件 docs/index.md 添加一個 order

---
order: 0
---

這樣就能實現自定義導航了

3. 引入外部組件

由于文檔站點的頁面是 MarkDown 文件，雖然在 dumi 讓我們可以在 MarkDown 中寫 jsx 組件，

但如果某個組件的 Demo 比較復雜，甚至包含很多外部文件，

這時候可以在其他地方寫好 demo，然后在 MarkDown 文件中，通過 <code> 標簽引入

<code src="/path/to/complex-demo.tsx"></code>

--------------------------------------

最后需要注意一下，對于文檔站點的打包需要使用yarn docs:build 命令

四、Demo 理念

開發文檔站點的時候，需要牢記一條宗旨：開發者應該像用戶一樣寫 Demo

這是 dumi 官方文檔中提到的，我深以為然

建議每一個寫組件文檔的小伙伴都了解一下，傳送門：

https://d.umijs.org/zh-CN/guide/demo-principle

總結

以上是生活随笔為你收集整理的使用 dumi 打包 React 组件库并生成文档站点的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。