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 组件的说明文档:
![image-20221114210703244](https://tva1.sinaimg.cn/large/008vxvgGly1h865xwdr3tj30y60u0dhg.jpg)
3.2 打包构建
- 打包组件库文档:
pnpm run build
打包后的文档位于:docs/.vitepress/dist 中。
- 预览打包后的结果:
pnpm run serve
预览的效果与本地启动服务的效果一致。
到此咱们已经完成了组件库文档的开发环境搭建和打包构建,下一篇文章将分享加速器 —— 创建新组建的脚手架 cli 的开发。
感谢你阅读本文,如果本文给了你一点点帮助或者启发,还请三连支持一下,点赞、关注、收藏,程序员优雅哥会持续与大家分享更多干货