如何開發一個基於 Vue 的 ui 組件庫（二）

遺留問題

書接上回，說道利用 sideEffects 字段，只需讀取源文件便可實現按需加載，還有個坑忘了說...

文檔中的樣式打包後會丟失...

由於咱們只注意到了做爲組件庫的源代碼，而忘了咱們的文檔是經過 vuepress 編譯，即底層也是基於 webpack 進行打包。因此 sideEffects 中也要加上文檔中的文件。

組件文檔該寫些什麼？

在編寫組件庫文檔時，有兩個必不可少的部分。

• 組件預覽，最好有相應的代碼
• 組件 api，即 props、events、slots 等接口和參數的說明

如何同時展現 demo 和 code？

• 最【一力降十會】的方法固然就是複製粘貼一把梭...

這樣實現簡單是簡單，不過維護時要同時改至少兩份代碼。好比 vant 的展現文檔 和 cube-ui 的展現文檔。

• 進階一點兒的方法就是嵌入 Codepen、JSFiddle 或 CodeSandbox 的 iframe。

可是組件庫中通常有大量的組件，不可能爲每一個組件都維護一份小代碼片斷，而且別忘了這但是三個平臺（硬點一個吼不吼啊~？）。

• 所以各類組件庫使用的最多的方法仍是本身編寫組件。（下一小節詳解）

• 固然也有例外好比 vux 只有 demo 沒有 code。

業界的文檔組件

• 最廣泛的方式仍是基於 markdown-it，將本身的 vue 組件插入文檔中。

  • muse-ui 的 demo-block 組件
  • muse-ui 的 markdown-it 配置
  • ant-design-vue 的 demoBox 組件
  • ant-design-vue 的 markdown-it 配置
  • element 的 demo-Block 組件
  • element 的 markdown-it 配置

• 比較有意思的是 mand-mobile 的文檔編寫方式。demo 的文檔放在組件目錄中，而後由 Doc 組件讀取各個組件的 demo。

  • mand-mobile 的展現文檔
  • mand-mobile 的 Doc 組件

• 那麼對於咱們使用 vuepress 編寫文檔的開發者來講咋辦咧？

在 vuepress 中展現 demo 和 code

首先讓咱們來分析一下：這兩份重複的代碼應該以誰爲主？即咱們應該只編寫 demo 的代碼仍是 code 的代碼？先有雞仍是先有蛋？物質決定意識仍是意識決定物質？

至少在編寫 demo 和 code 這個問題中，我認爲 demo 纔是「本源」，爲何？

• 這是最廣泛的方式，各大組件庫基本這麼幹
• 這是最天然的方式，由於 vuepress 會編譯 md 中的 vue 組件
• 如果反過來，文檔中以 code 爲主，再由 code 生成 demo 會有一些不便
  • 如何預處理代碼：babel、scss 等？
  • 如何插入生成的組件到文檔中？
  • 感興趣的話能夠看看這個插件 vuepress-plugin-demo-block

一開始我只在 .vuepress/components/ 中建了個組件自娛自樂，後來看到了 vuepress-plugin-demo-block，但以爲由 code 生成 demo 有點兒繞。

因而本身搞了個插件 vuepress-plugin-demo-code，有須要的讀者老爺能夠自取~

組件的 api 文檔

解決了 demo 和 code 的重複編寫問題，接下來是另外一個使人無發可脫的問題：如何自動生成並同步 .vue 組件的 api 文檔？

手動維護確定是不行的，還好有一個炒雞好用的庫 vuese。vuese 會基於 ast 分析你的 .vue 文件，提取其中的 props、events、slots 等接口和參數的說明。

爲了將其集成到 vuepress 中，我又整了個 markdown-it 插件 markdown-it-vuese。

只需使用如下的語法在導入已經存在的 *.vue 文件的同時，使用 Vuese 自動生成文檔。

<[vuese](@/filePath) 複製代碼

以上 to be continued...

參考資料

• muse-ui 的 demo-block 組件
• muse-ui 的 markdown-it 配置
• ant-design-vue 的 demoBox 組件
• ant-design-vue 的 markdown-it 配置
• element 的 demo-Block 組件
• element 的 markdown-it 配置
• vux 的展現文檔
• vant 的展現文檔
• cube-ui 的展現文檔
• mand-mobile 的展現文檔
• mand-mobile 的 Doc 組件
• vuepress-plugin-demo-code
• vuepress-plugin-demo-block
• vuese
• markdown-it-vuese