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

佯真愚發表於2019-04-01
VueUI元件

遺留問題

書接上回，說道利用 sideEffects 欄位，只需讀取原始檔即可實現按需載入，還有個坑忘了說...

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

因為我們只注意到了作為元件庫的原始碼，而忘了我們的文件是通過 vuepress 編譯，即底層也是基於 webpack 進行打包。所以 sideEffects 中也要加上文件中的檔案。

元件文件該寫些什麼？

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

  • 元件預覽，最好有相應的程式碼
  • 元件 api，即 props、events、slots 等介面和引數的說明

如何同時展示 demo 和 code？

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

這樣實現簡單是簡單，不過維護時要同時改至少兩份程式碼。比如 vant 的展示文件 和 cube-ui 的展示文件。

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

但是元件庫中一般有大量的元件，不可能為每個元件都維護一份小程式碼片段，並且別忘了這可是三個平臺（硬點一個吼不吼啊~？）。

  • 因此各種元件庫使用的最多的方法還是自己編寫元件。（下一小節詳解）

  • 當然也有例外比如 vux 只有 demo 沒有 code。

業界的文件元件

在 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...

參考資料

相關文章