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

  • Vue3 企业级优雅实战 – 组件库框架 – 7 组件库文档的开发和构建已关闭评论
  • 162 次浏览
  • A+
所属分类：Web前端
摘要

该系列已更新文章：
分享一个实用的 vite + vue3 组件库脚手架工具，提升开发效率
开箱即用 yyg-cli 脚手架：快速创建 vue3 组件库和vue3 全家桶项目
Vue3 企业级优雅实战 – 组件库框架 – 1 搭建 pnpm monorepo
Vue3 企业级优雅实战 – 组件库框架 – 2 初始化 workspace-root
Vue3 企业级优雅实战 – 组件库框架 – 3 搭建组件库开发环境
Vue3 企业级优雅实战 – 组件库框架 – 4 组件库的 CSS 架构
Vue3 企业级优雅实战 – 组件库框架 – 5 组件库通用工具包
便宜好用的国外VPS推荐

该系列已更新文章：
分享一个实用的 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 目录下依次创建下列文件：

  1. 组件库首页 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 具体描述信息。 ---
  1. 组件库菜单 components.ts ：
export const components = [   { text: 'Foo 组件示例', link: '/components/foo' } ] // end

在 guide 目录下分别创建 index.md 和 quickstart.md：

  1. guide/index.md：
# 组件库介绍  yyg-demo-ui YYG Vue3企业级中后台组件库
  1. guide/quickstart.md：
# 快速开始  xxxxxx  ## 用法  全局安装组件库

在 components 目录下创建示例组件的说明文档 foo.md：

# Foo 组件示例

1.3 添加插件并配置 vitepress

  1. 安装 vitepress 中预览组件的插件：
pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin
  1. 在 .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)     }   } })
  1. 在 .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 和组件库

  1. 在 docs 目录下安装依赖：
pnpm install element-plus pnpm install @yyg-demo-ui/yyg-demo-ui
  1. 在 .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 组件的说明文档：

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

3.2 打包构建

  1. 打包组件库文档：
pnpm run build

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

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

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

到此咱们已经完成了组件库文档的开发环境搭建和打包构建，下一篇文章将分享加速器 —— 创建新组建的脚手架 cli 的开发。

感谢你阅读本文，如果本文给了你一点点帮助或者启发，还请三连支持一下，点赞、关注、收藏，程序员优雅哥会持续与大家分享更多干货

便宜好用的国外VPS推荐