Vue3 企業級優雅實戰 - 組件庫框架 - 7 組件庫文檔的開發和構建

Vue3 企業級優雅實戰 – 組件庫框架 – 7 組件庫文檔的開發和構建

2022 年 11 月 18 日
筆記
VUE, vue3, 前端, 架構, 組件庫

該系列已更新文章：
分享一個實用的 vite + vue3 組件庫腳手架工具，提升開發效率
 開箱即用 yyg-cli 腳手架：快速創建 vue3 組件庫和vue3 全家桶項目
 Vue3 企業級優雅實戰 – 組件庫框架 – 1 搭建 pnpm monorepo
Vue3 企業級優雅實戰 – 組件庫框架 – 2 初始化 workspace-root
Vue3 企業級優雅實戰 – 組件庫框架 – 3 搭建組件庫開發環境
 Vue3 企業級優雅實戰 – 組件庫框架 – 4 組件庫的 CSS 架構
 Vue3 企業級優雅實戰 – 組件庫框架 – 5 組件庫通用工具包

Vue3 企業級優雅實戰 – 組件庫框架 – 6 搭建example環境

前面完成了組件庫的開發環境搭建和 example，咱們可以在 example 中通過業務驅動組件的開發和完善。但組件庫開發的目的是給其他開發人員使用，這時候就需要通過文檔來展示組件庫的使用以及各個組件的 API、方法、插槽等。本文在前面文章的基礎上繼續實現組件庫文檔的開發和構建。組價庫的文檔咱們使用 vitepress 來實現，在之前的文章《vitepress搭建組件庫文檔》已經詳細介紹了 vitepress 1.0 的使用，該文章中談到的內容本文就快速略過。

1 搭建組件庫文檔環境

1.1 初始化工程

前面在工程根目錄創建 docs 目錄，在命令行中進入 docs 目錄，使用 pnpm 初始化：

pnpm init

安裝 vitepress 為開發依賴：

pnpm install vitepress -D

修改 package.json 文件的 name，並添加 scripts：

{
  "name": "@yyg-demo-ui/docs",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "serve": "vitepress serve"
  },
  "keywords": [],
  "author": "程式設計師優雅哥",
  "license": "ISC",
  "devDependencies": {
    "vitepress": "1.0.0-alpha.28"
  }
}

1.2 創建目錄及文件

在 docs 目錄下創建 .vitepress、public、components、demos、guide，分別存放 vitepress 配置文件、公共資源目錄、組件文檔描述、文檔中的 demo、組價庫的其他說明文檔。放一個 logo.png 圖片到 public 目錄下。

繼續在 docs 目錄下依次創建下列文件：

組件庫首頁 index.md：

---
layout: home

title: YYG-DEMO-UI
editLink: true
lastUpdated: true
hero:
  name: yyg-demo-ui
  text: YYG Vue3企業級中後台組件庫
  tagline: 組件庫描述 / SLOGAN
  image:
    src: /logo.png
    alt: yyg-admin-ui
  actions:
    - theme: brand
      text: 快速開始
      link: /guide/
    - theme: alt
      text: 組件
      link: /components/foo
features:
  - icon: 🔨
    title: 功能/特點 1
    details: 功能/特點 1 具體描述資訊。
  - icon: 🧩
    title: 功能/特點 2
    details: 功能/特點 2 具體描述資訊。
  - icon: ✈️
    title: 功能/特點 3。
    details: 功能/特點 3 具體描述資訊。
---

組件庫菜單 components.ts ：

export const components = [
  { text: 'Foo 組件示例', link: '/components/foo' }
] // end

在 guide 目錄下分別創建 index.md 和 quickstart.md：

guide/index.md：

# 組件庫介紹

yyg-demo-ui YYG Vue3企業級中後台組件庫

guide/quickstart.md：

# 快速開始

xxxxxx

## 用法

全局安裝組件庫

在 components 目錄下創建示例組件的說明文檔 foo.md：

# Foo 組件示例

1.3 添加插件並配置 vitepress

安裝 vitepress 中預覽組件的插件：

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

在 .vitepress 目錄下創建 config.ts：

import { DefaultTheme, defineConfig } from 'vitepress'
import { componentPreview, containerPreview } from '@vitepress-demo-preview/plugin'
import { components } from '../components'

const nav: DefaultTheme.NavItem[] = [
  { text: '指南', link: '/guide/' },
  { text: '組件', link: '/components/foo' }
]

const sidebar: DefaultTheme.Sidebar = {
  '/guide': [
    {
      text: '指南',
      items: [
        { text: '組件庫介紹', link: '/guide/' },
        { text: '快速開始', link: '/guide/quickstart' },
      ]
    }
  ],
  '/components': [{
    items: [
      ...components
    ]
  }]
}

export default defineConfig({
  title: 'yyg-admin-ui',
  description: 'YYG Vue3企業級中後台組件庫',
  lang: 'cn-ZH',
  base: '/',
  lastUpdated: true,
  themeConfig: {
    logo: '/logo.png',
    siteTitle: 'yyg-admin-ui',
    outline: 3,
    socialLinks: [
      { icon: 'github', link: '//github.com/vuejs/vitepress' }
    ],
    nav,
    sidebar
  },
  markdown: {
    theme: {
      light: 'vitesse-light',
      dark: 'vitesse-dark'
    },
    lineNumbers: true,
    config(md) {
      md.use(componentPreview)
      md.use(containerPreview)
    }
  }
})

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

import DefaultTheme from 'vitepress/theme'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'
import { EnhanceAppContext } from 'vitepress'

export default {
  ...DefaultTheme,
  enhanceApp(ctx: EnhanceAppContext) {
    ctx.app.component('demo-preview', AntDesignContainer)
  }
}

此時組件庫的文檔結構就搭建好了，可以在 docs 目錄下執行 pnpm run dev，測試服務是否能正常啟動，頁面是否正常顯示。

2 編寫組件的文檔

上一步已經引入了用於展示組件 demo 的插件，這一步就簡單了。

2.1 安裝 element plus 和組件庫

pnpm install element-plus
pnpm install @yyg-demo-ui/yyg-demo-ui

在 .vitepress/theme/index.ts 中引入組件庫：

...
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import YygDemoUi from '@yyg-demo-ui/yyg-demo-ui'
...
export default {
  ...DefaultTheme,
  enhanceApp(ctx: EnhanceAppContext) {
    ctx.app.use(ElementPlus)
    ctx.app.use(YygDemoUi)
    ctx.app.component('demo-preview', AntDesignContainer)
  }
}

2.2 編寫demo

在 docs/demos 目錄下創建子目錄 foo，在 foo 目錄下創建兩個組件：

foo-1.vue：

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

foo-2.vue：

<template>
  <yyg-foo :msg="msg"></yyg-foo>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const msg = ref('hello custom component')
</script>

2.3 vite 配置文件

在 docs 目錄下創建 vite 的配置文件 vite.config.ts，該文件主要配置開發埠和 jsx 插件：

import { defineConfig } from 'vite'
import VueJsx from '@vitejs/plugin-vue-jsx'

export default defineConfig({
  plugins: [
    VueJsx()
  ],
  server: {
    port: 3100
  }
})

2.4 在組件庫文檔中展示 demo

在 docs/components/foo.md 文件中展示上面兩個 demo：

# Foo 組件示例

第一個示例：

<preview path="../demos/foo/foo-1.vue" title="基本使用" description="測試使用 Element Plus 組件"></preview>

第二個示例：

<preview path="../demos/foo/foo-2.vue" title="基本使用" description="測試使用自定義組件庫組件"></preview>

## 組件介紹

3 運行組件庫文檔

3.1 本地開發

pnpm run dev

訪問 //localhost:3100/components/foo.html，可以看到 foo 組件的說明文檔：

3.2 打包構建

打包組件庫文檔：

pnpm run build

打包後的文檔位於：docs/.vitepress/dist 中。

預覽打包後的結果：

pnpm run serve

預覽的效果與本地啟動服務的效果一致。

到此咱們已經完成了組件庫文檔的開發環境搭建和打包構建，下一篇文章將分享加速器 —— 創建新組建的腳手架 cli 的開發。

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

Tags: VUE vue3 前端架構組件庫