vue 开发组件库（Vue3 企业级优雅实战 – 组件库框架 – 7 组件库文档的开发和构建）

该系列已更新文章：

分享一个实用的 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: https://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 和组件库

在 docs 目录下安装依赖： 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

访问 http://localhost:3100/components/foo.html    
    
    
，可以看到 foo 组件的说明文档：

3.2 打包构建

打包组件库文档： pnpm run build

打包后的文档位于：docs/.vitepress/dist 中















。

预览打包后的结果： pnpm run serve

预览的效果与本地启动服务的效果一致               。

到此咱们已经完成了组件库文档的开发环境搭建和打包构建 


     


     


     ，下一篇文章将分享加速器 —— 创建新组建的脚手架 cli 的开发     



     



     



 。

感谢你阅读本文

 




 




 



，如果本文给了你一点点帮助或者启发   

   

   

，还请三连支持一下  

     

     

    ，点赞                、关注




    




    




    
、收藏


  




  




  


，程序员优雅哥会持续与大家分享更多干货