搭建 vue3 组件库

[chiyan-lin]

背景

组内在早些时候已经搭建了自己的一套组件库，但是存在很多问题

1. 组件没有文档，使用全靠当前项目的其他使用方式
2. 使用方式不是 npm 安装，只是一个独立的 git 项目，然后通过 webpack 引入
3. 组件没有版本管理，组件修改会影响其他页面的使用
4. 组件库内组件写法不规范，部分实现有很大的问题
5. 组件没有编译

契机

其实早就想动手改这个组件库，但是目前项目内很多使用，可能还有其他地方用到，所以有方案但是没有行动

组里新启动了一个项目，在项目上我们决定使用新的框架来实现，结合组内其他小伙伴的意见，决定使用

vite + vue3 为基本进行开发，拥抱 ts 作为项目语法规范，同时也决定自己来搭建这套组件库

组件使用组件仓库的模式统一为一个，其实还有另外一个模式，就是每一个组件单独发布。在我们的讨论下，觉得还是统一为一个组件库合理，第一是可以共享一些公共的东西，js以及sass的方法，其二是更好的管理，在引用组件的时候进行按需引入，项目在也不需要每个包都独立地安装，组件整体升级，对一些公共以来的升级也相对便捷。

组件的组织形式也进行了调整，加入了 ts 文件的要求，组件开发者需要在组件开发之前就在入口文件定义好必要的输入输出，样式也从原本的内嵌 style 的方式，改成了全局的方式，使用 namespace + bem 来做限制。

最终定下实现的目标包括 组件仓库 + 对应的文档（组件展示） + npm 版本管理 + vscode 智能提示

选型

项目基础上使用 pnpm 作为新的包管理工具，主要看中两个点，更快的包安装，更合理的包管理；使用 pnpm
来探索更多的多管理使用，通过新工具寻找更多提升代码管理的方式。
组件构建使用 rollup ，文件搬迁上使用 glup，组件文档使用 vitepress；

设计理念

项目一体化

整个组件库组件、开发、文档不做切割，整个项目的基本结构分为4大部分 devolop 开发 , docs 文档 , hammer 构建 , packages 组件库 四个子仓库。

组件规范

组件书写的格式，代码等做了 ts 代码规范；统一使用 sass 做组件样式工具语言。

更强的自动化

通过 props 声明自动生成基础 api md 文档，减少开发人员编写文档的时间。

组件库介绍

整体结构

扁平化的 packages 的设计，里面的每一个文件夹都是一个小仓，pnpm 的包管理带来的第一个好处。

组件

组件结构

import { useNamespace } from '@omd-design-plus/hooks' 组件内可以用这种方式引入其他小仓的资源

search-combination.ts 是整个组件的声明文件，定义组件的入参，props, event, slot 三个参数，在这份文件也是生成 api.md 的重要入口

组件构建

组件的构建上使用 rollup，整体的流程涉及到工作流，使用 gulp 来组织整体的构建工作

整个组件库的构建核心的5步

1. buildModules 分批构建，讲组件库的组件挨个构建
2. buildFullBundle 合并打包为一个大的组件dist文件
3. buildCss 构建 css，把 sass 文件转换为 css
4. buildTypesDefinitions 根据文件生成 type 定义，进行ide ts 提示
5. buildHelper 生成组件UI提示
6. copyFiles 把必要的 package 和 readme 文件复制到到打包完成的文件夹

buildHelper

之前要求组件开发者定义的组件声明文件在这里就有了作用了

即时的文档生成，生成了api文档，组件文档直接引入即可，search-combination/basic 是 example vue 组件

components-helper 可以根据 md 文件生成 web-types attributes tags 三个json文件，valor会根据 web-types 进行组件提示

在 md 文件中引用 md和vue 文件

整个组件库文档的难点就在于此，找到了一个md插件 MarkdownIt 来实现

通过给文档定义特殊的标志符api ，将当前块标记为特殊块

:::api search-combination/api :::

在执行md文件的编译过程，截取这些块，替换成对应的文件 search-combination/api.md

小结

全文展示了整个组件库的结构，组件的结构和构建。在实现过程中还是有很多小细节，后续会抽一个小的出来，做成一个开源的仓库，可以更好地展示细节。组件库的价值还是很大的，很多团队在日常的工作中会产生很多可以可复用的组件，这些组件可以用 story-book 的方式组织，也可以用组件库的方式组织。接下来也会探索用 story-book 来组织文档和组件。