经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置:技术经验 » JS/JS库/框架 » Vue.js » 查看文章
Vue3 企业级优雅实战 - 组件库框架 - 7 组件库文档的开发和构建
来源:cnblogs  作者:程序员优雅哥(\/同)  时间:2022/11/19 17:14:49  对本文有异议

该系列已更新文章:
分享一个实用的 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 初始化:

  1. pnpm init

安装 vitepress 为开发依赖:

  1. pnpm install vitepress -D

修改 package.json 文件的 name,并添加 scripts:

  1. {
  2. "name": "@yyg-demo-ui/docs",
  3. "version": "1.0.0",
  4. "description": "",
  5. "main": "index.js",
  6. "scripts": {
  7. "dev": "vitepress dev",
  8. "build": "vitepress build",
  9. "serve": "vitepress serve"
  10. },
  11. "keywords": [],
  12. "author": "程序员优雅哥",
  13. "license": "ISC",
  14. "devDependencies": {
  15. "vitepress": "1.0.0-alpha.28"
  16. }
  17. }

1.2 创建目录及文件

docs 目录下创建 .vitepresspubliccomponentsdemosguide,分别存放 vitepress 配置文件、公共资源目录、组件文档描述、文档中的 demo、组价库的其他说明文档。放一个 logo.png 图片到 public 目录下。

继续在 docs 目录下依次创建下列文件:

  1. 组件库首页 index.md
  1. ---
  2. layout: home
  3. title: YYG-DEMO-UI
  4. editLink: true
  5. lastUpdated: true
  6. hero:
  7. name: yyg-demo-ui
  8. text: YYG Vue3企业级中后台组件库
  9. tagline: 组件库描述 / SLOGAN
  10. image:
  11. src: /logo.png
  12. alt: yyg-admin-ui
  13. actions:
  14. - theme: brand
  15. text: 快速开始
  16. link: /guide/
  17. - theme: alt
  18. text: 组件
  19. link: /components/foo
  20. features:
  21. - icon: ??
  22. title: 功能/特点 1
  23. details: 功能/特点 1 具体描述信息。
  24. - icon: ??
  25. title: 功能/特点 2
  26. details: 功能/特点 2 具体描述信息。
  27. - icon: ??
  28. title: 功能/特点 3
  29. details: 功能/特点 3 具体描述信息。
  30. ---
  1. 组件库菜单 components.ts
  1. export const components = [
  2. { text: 'Foo 组件示例', link: '/components/foo' }
  3. ] // end

guide 目录下分别创建 index.mdquickstart.md

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

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

  1. # Foo 组件示例

1.3 添加插件并配置 vitepress

  1. 安装 vitepress 中预览组件的插件:
  1. pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin
  1. .vitepress 目录下创建 config.ts
  1. import { DefaultTheme, defineConfig } from 'vitepress'
  2. import { componentPreview, containerPreview } from '@vitepress-demo-preview/plugin'
  3. import { components } from '../components'
  4. const nav: DefaultTheme.NavItem[] = [
  5. { text: '指南', link: '/guide/' },
  6. { text: '组件', link: '/components/foo' }
  7. ]
  8. const sidebar: DefaultTheme.Sidebar = {
  9. '/guide': [
  10. {
  11. text: '指南',
  12. items: [
  13. { text: '组件库介绍', link: '/guide/' },
  14. { text: '快速开始', link: '/guide/quickstart' },
  15. ]
  16. }
  17. ],
  18. '/components': [{
  19. items: [
  20. ...components
  21. ]
  22. }]
  23. }
  24. export default defineConfig({
  25. title: 'yyg-admin-ui',
  26. description: 'YYG Vue3企业级中后台组件库',
  27. lang: 'cn-ZH',
  28. base: '/',
  29. lastUpdated: true,
  30. themeConfig: {
  31. logo: '/logo.png',
  32. siteTitle: 'yyg-admin-ui',
  33. outline: 3,
  34. socialLinks: [
  35. { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
  36. ],
  37. nav,
  38. sidebar
  39. },
  40. markdown: {
  41. theme: {
  42. light: 'vitesse-light',
  43. dark: 'vitesse-dark'
  44. },
  45. lineNumbers: true,
  46. config(md) {
  47. md.use(componentPreview)
  48. md.use(containerPreview)
  49. }
  50. }
  51. })
  1. .vitepress 目录下创建 theme 目录,并在 theme 中创建 index.ts
  1. import DefaultTheme from 'vitepress/theme'
  2. import { AntDesignContainer } from '@vitepress-demo-preview/component'
  3. import '@vitepress-demo-preview/component/dist/style.css'
  4. import { EnhanceAppContext } from 'vitepress'
  5. export default {
  6. ...DefaultTheme,
  7. enhanceApp(ctx: EnhanceAppContext) {
  8. ctx.app.component('demo-preview', AntDesignContainer)
  9. }
  10. }

此时组件库的文档结构就搭建好了,可以在 docs 目录下执行 pnpm run dev,测试服务是否能正常启动,页面是否正常显示。

2 编写组件的文档

上一步已经引入了用于展示组件 demo 的插件,这一步就简单了。

2.1 安装 element plus 和组件库

  1. docs 目录下安装依赖:
  1. pnpm install element-plus
  2. pnpm install @yyg-demo-ui/yyg-demo-ui
  1. .vitepress/theme/index.ts 中引入组件库:
  1. ...
  2. import ElementPlus from 'element-plus'
  3. import 'element-plus/dist/index.css'
  4. import YygDemoUi from '@yyg-demo-ui/yyg-demo-ui'
  5. ...
  6. export default {
  7. ...DefaultTheme,
  8. enhanceApp(ctx: EnhanceAppContext) {
  9. ctx.app.use(ElementPlus)
  10. ctx.app.use(YygDemoUi)
  11. ctx.app.component('demo-preview', AntDesignContainer)
  12. }
  13. }

2.2 编写demo

docs/demos 目录下创建子目录 foo,在 foo 目录下创建两个组件:

foo-1.vue

  1. <template>
  2. <el-button type="primary">测试按钮</el-button>
  3. </template>

foo-2.vue

  1. <template>
  2. <yyg-foo :msg="msg"></yyg-foo>
  3. </template>
  4. <script lang="ts" setup>
  5. import { ref } from 'vue'
  6. const msg = ref('hello custom component')
  7. </script>

2.3 vite 配置文件

docs 目录下创建 vite 的配置文件 vite.config.ts,该文件主要配置开发端口和 jsx 插件:

  1. import { defineConfig } from 'vite'
  2. import VueJsx from '@vitejs/plugin-vue-jsx'
  3. export default defineConfig({
  4. plugins: [
  5. VueJsx()
  6. ],
  7. server: {
  8. port: 3100
  9. }
  10. })

2.4 在组件库文档中展示 demo

docs/components/foo.md 文件中展示上面两个 demo:

  1. # Foo 组件示例
  2. 第一个示例:
  3. <preview path="../demos/foo/foo-1.vue" title="基本使用" description="测试使用 Element Plus 组件"></preview>
  4. 第二个示例:
  5. <preview path="../demos/foo/foo-2.vue" title="基本使用" description="测试使用自定义组件库组件"></preview>
  6. ## 组件介绍

3 运行组件库文档

3.1 本地开发

  1. pnpm run dev

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

image-20221114210703244

3.2 打包构建

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

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

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

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

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

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

原文链接:https://www.cnblogs.com/youyacoder/p/16903476.html

 友情链接:直通硅谷  点职佳  北美留学生论坛

本站QQ群:前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

W3xue 的所有内容仅供测试,对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接(目前9元/月)请联系QQ:27243702 沸活量
皖ICP备17017327号-2 皖公网安备34020702000426号