Vitepress搭建組件庫文檔（下）—— 組件 Demo

2022 年 10 月 27 日
筆記
vite, VUE, vue3, 前端, 組件庫

上文《Vitepress搭建組件庫文檔（上）—— 基本配置》已經討論了 vitepress 搭建組件庫文檔的基本配置，包括站點 Logo、名稱、首頁 home 布局、頂部導航、左側導航等。本文進入最重要的部分 —— 如何像 Element Plus 那樣一遍程式碼就可以展示組件的效果和源程式碼。

1 組件 Demo 的實現效果

vitepress 對 MarkDown 支援比較好，同時對 vue3 也支援較好。常見的在 MD 文檔中展示 Demo 有兩種方式：

在一個區塊內展示，添加插件用來解析 demo 區塊，如：

組件基本使用：

:::demo 描述資訊
<template>
	<el-button type="primary">測試按鈕</el-button>
</template>
:::

封裝一個組件，將 Demo 程式碼的語言、路徑傳遞給該組件，然後在 MD 文檔中使用該組件，如：

組件基本使用：

<code-preview path="../demos/xx/xxx.vue"
							language="vue">

如果某個組件文檔中 demo 較少，可以使用第一種方式，直接在 MD 文檔中編寫組件 demo；但如果 demo 較多或 demo 實現較複雜，可以使用第二種方式。所以最好兩種方式都支援。

在 vitepress 1.0 之前（如 0.22.0），vitepress-theme-demoblock 是個非常好的選擇，支援區塊內的方式展示 Demo 和示例程式碼，但從 npmjs 上面可以看到該插件有一年多沒更新了，在 vitepress 1.0 中會報錯。不停搜索，總算找到一個可以很好支援 vitepress 1.0 的插件 —— vitepress-demo-preview，這裡非常感謝 vitepress-demo-preview 的作者 flingyp 大神！

2 集成 @vitepress-demo-preview

2.1 安裝依賴

pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin

2.2 config.ts

修改 docs/.vitepress/config.ts，添加 markdown 配置：

import { componentPreview, containerPreview } from '@vitepress-demo-preview/plugin'

...

export default defineConfig({
  ...
  markdown: {
    theme: {
      light: 'vitesse-light',
      dark: 'vitesse-dark'
    },
    lineNumbers: true,
    config(md) {
      md.use(componentPreview)
      md.use(containerPreview)
    }
  }
})

2.3 組件引入

在 .vitepress 下新建目錄 theme，並在 theme 目錄中創建 index.ts

import theme from 'vitepress/dist/client/theme-default/index'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'

export default {
  ...theme,
  enhanceApp({app}) {
    app.component('demo-preview', AntDesignContainer)
  }
}

這樣便完成了 @vitepress-demo-preview 的配置，接下來就可以在組件文檔中編寫demo了。

3 編寫組件 demo

這裡由於是演示，就不編寫測試組件了，簡單的使用 Element-Plus 來模擬組件庫，在文檔使用 Button 編寫 Demo。

3.1 引入組件庫

安裝組件庫依賴：

pnpm install element-plus

在 .vitepress/theme/index.ts 中安裝組件庫：

import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import theme from 'vitepress/dist/client/theme-default/index'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'

export default {
  ...theme,
  enhanceApp({app}) {
    app.use(ElementPlus)
    app.component('demo-preview', AntDesignContainer)
  }
}

3.2 編寫組件 Demo

在 docs 目錄下創建 demo 目錄，該目錄存放文檔中編寫的demo，如定義一個 button-demo-1.vue 文件：

<template>
  <el-button type="primary">測試按鈕</el-button>
</template>

在 docs/compnents/basic-component1.md 中使用該 Demo：

# Basic Component 1

<preview path="../demos/button-demo-1.vue" title="基本使用" description="xxxxx"></preview>

預覽該頁面：

使用這個插件，只能在文檔外部定義組件 Demo，不支援在 MD 文檔中編寫 Demo。

4 打包組件庫

組件庫打包完成後，需要打包發布。

打包：

pnpm run build

預覽組件庫：

pnpm run serve

vitepress 編寫組件庫文檔就先介紹到這裡。後面將分享 pnpm + monorepo + vite + vue3 + tsx + vitepress 搭建企業級組件庫，內容大綱如下：

pnpm 搭建 monorepo 風格架構；
組件庫開發環境搭建和構建發布；
組件庫演示 example 開發環境搭建和構建發布；
組件庫文檔開發環境搭建和構建發布；
命令行工具開發。

感謝你閱讀本文，如果本文給了你一點點幫助或者啟發，還請三連支援一下，點贊、關注、收藏，作者會持續與大家分享更多乾貨

Tags: vite VUE vue3 前端組件庫