正文

猿创征文vue3企业级优雅实战-组件库框架-7组件库文档的开发和构建(代码片段)

程序员优雅哥  程序员优雅哥  2023-04-02  319

关键词：

本系列已更新文章：
分享一个实用的 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 和组件库

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 的开发。

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

猿创征文｜2022年快过完了，是时候总结一下那些优秀的react组件库(代码片段)

⭐️本文首发自前端修罗场(点击加入)，是一个由资深开发者独立运行的专业技术社区，我专注Web技术、Web3、区块链、答疑解惑、面试辅导以及职业发展。2022年只剩下2个月，在这快一年的开发过程中，我觉得是... 查看详情

猿创征文｜2022年快过完了，是时候总结一下那些优秀的react组件库(代码片段)

猿创征文｜tidb架构分析&读写性能测试

TiDB是由PingCAP公司开发的一个开源的分布式HTAP(HybridTransactionalandAnalyticalProcessing)数据库，基于GoogleSpanner和Percolator的设计思想，采用存储与计算分离架构，将整个系统划分为TiDB、PD、TiKV、TiFlash四个组件，各组件之... 查看详情

猿创征文｜tidb架构分析&读写性能测试

组件库实战|用vue3+ts实现全局header和列表数据渲染columnlist(代码片段)

用vue3+ts实现全局Header和列表数据渲染ColumnList🖼️序言📻一、ColumnList数据渲染1、设计稿抢先知2、数据构思3、视图数据绑定4、数据传递5、挠头情况☎️二、GlobalHeader全局Header1、设计稿抢先看2、数据构思3、视图数据... 查看详情

primevue-全面升级！免费开源优雅好用的vue3ui组件库，可选主题超多

新版本发布了，主题超好看，还有很多独有的组件，强烈推荐给大家。关于新版本PrimeVuePrimeVue是一个用于Vue.js3.x开发的webUI组件库。早在2021年10月我就推荐过这个组件库，至今一年多的时间，开发迭代非常快&#... 查看详情

猿创征文|国产数据库实战之使用docker部署tidb集群(代码片段)

猿创征文|国产数据库实战之使用Docker部署TiDB集群一、TiDB介绍1.TiDB简介2.TiDB特性3.TiDB集群整体架构4.TiDB集群各部分介绍5.本次TiDB集群组件二、检查本地环境1.检查docker状态2.检查docker版本3.检查docker-compose版本三、下载tidb-docker-comp... 查看详情

猿创征文|国产数据库实战之使用docker部署tidb集群(代码片段)

猿创征文|国产数据库实战之使用docker部署oceanbase数据库(代码片段)

猿创征文|国产数据库实战之使用Docker部署OceanBase数据库一、OceanBase介绍1.OceanBase介绍2.OceanBase特点3.OceanBase数据库基础概念4.OceanBase相关概念①OBServer②区域（zone）③资源池④租户⑤数据分区⑥副本5.本次实践介绍二、检查... 查看详情

猿创征文｜机器学习实战——降维(代码片段)

目录1主成分2低维度投影3方差解释率4选择正确数量的维度5PCA压缩6增量PCA7核主成分分析8选择核函数和调整超参数9局部线性嵌入10其他降维技巧数据降维会丢失一些信息（好比压缩图像带来的效果一样），所以，... 查看详情

猿创征文|unity开发实战——2d项目1-ruby‘sadventure游戏地图绘制（2-1）(代码片段)

文章目录1）使用指南2）具体步骤详细剖析2.1）《4-2.创建瓦片地图》操作更新2.2）《4-3.创建新瓦片》操作更新2.3）《5-2.如何才能解决排序问题？》操作注意2.3）《5-7.什么是预制件？》操作积累3... 查看详情

猿创征文|国产数据实战之docker部署mywebsql数据库管理工具(代码片段)

猿创征文|国产数据实战之docker部署MyWebSQL数据库管理工具一、MyWebSQL介绍1.MyWebSQL简介2.MyWebSQL特点二、检查本地环境1.检查docker状态2.检查docker-compose版本三、下载MyWebSQL镜像四、部署MyWebSQL工具1.编辑docker-compose.yaml2.创建MyWebSQL容器... 查看详情

猿创征文|国产数据库实战之tidb数据库快速入门(代码片段)

猿创征文|国产数据库实战之TiDB数据库快速入门一、系统检查1.检查系统版本2.查看本地IP地址3.TiDB集群介绍二、快速部署本地测试集群1.安装TiUP工具2.声明全局环境变量3.快速部署TiDB集群三、连接TiDB数据库1.新开一个session以访问T... 查看详情

猿创征文|kafka框架从入门到精通（全）(代码片段)

目录前言1.入门kafka1.1安装配置1.2命令操作1.2.1topic1.2.2生产者消费者2.生产者2.1异步&同步发送2.2分区2.3调优参数2.3.1吞吐量2.3.2可靠性2.3.3幂等性事务性2.3.4顺序性3.Broker3.1工作原理3.2节点增删3.3副本3.4故障处理3.5leaderpartition负载... 查看详情

猿创征文｜机器学习实战——集成学习(代码片段)

目录1投票分类器2baggingandpasting3包外评估4疑问解答如果我们聚合一组预测器的预测，得到的预测结果会比最好的单个预测器要好，这样的一组预测器，我们称为集成，这种技术也被称为集成学习。例如，我们... 查看详情

vite-admin后台管理系统|vite4+vue3+pinia前端后台框架实例(代码片段)

...系统解决方案ViteAdmin。前段时间分享了一篇vue3自研pc端UI组件库VEPlus。这次带来最新开发的基于vite4+vue3+pinia技术栈搭配ve-plus组件库构建的中后台权限管理系统框架。支持vue-i18n国际化多语言、动态路由鉴权、4种布局模板及tab页... 查看详情

猿创征文|国产数据库实战使用docker部署polardb-x云原生分布式开源数据库(代码片段)

猿创征文|【国产数据库实战】使用docker部署PolarDB-X云原生分布式开源数据库一、PolarDB-X介绍1.PolarDB-X简介2.PolarDB-X特点二、检查docker版本三、检查docker配置信息四、下载PolarDB-X镜像五、部署PolarDB-X1.创建PolarDB-X容器2.检查PolarDB-X容... 查看详情