从零搭建基于 Vue 3.x + ElementPlus 的组件库
前言
由于最近在我司开发中开启了Vue3的重构工作。于是乎，Vue组件库的抽离工作开启，此次算是基于 vue3.x + element-plus 的二次封装，封装常见通用组件。一年前做了 react+antd的组件库 的整合及示例，一年后再看该方案还有诸多缺陷，发现了很多新的东西可以用，在本次的Vue组件库技术选型中调研了更多的方式方法，最终选型不代表是最好的，但一定是现阶段我认为最合适该场景的技术选型，实际上写组件库并不复杂，技术调研和技术选型的整个流程下来，算是对各种方法方法及其优缺点有了一个稍微宽泛的认识，本文目的是记录下本次选型到最终成品的全过程。基础配置不在赘述，文章只大致记录大致的开发框架以及打包和单测，仅供参考。
不想看文章只想看代码的点这里 想先看下交互文档效果的点这里
目的
为什么要做组件库？这个问题也是老生常谈了，PC端后台xx管理系统这种场景下，通用的东西很容易抽象出来，这样就不需要每开一个新项目就在项目里写一套基础组件了，在可直接使用基础组件的基础上开发能省不少时间，本次只对集成度和通用度较高的几个组件进行抽离出几个 npm 包，先实现常见通用功能，后续扩展则可以在不改变原来架构的基础上进行添加功能。这些组件包括通用的布局组件、通用的表格组件、通用的表单组件、通用的文件图片上传组件等。
尤其是表格和表单组件，直接在页面中使用的话会出现很多重复代码，写起来代码冗余多，所以一般项目里就会封装这些基础组件来实现通用，想要实现的目的就是只需要通过不同的配置就能在页面中通用，一般这些其实都大同小异，这也是想要开发这样基础组件库的初衷，不必要在每个项目里都写一套，直接将组建库丢到 npm 管理已经后续升级，这样一来就能慢慢的沉淀出公司自己特有的基础和业务组件库，后续新项目开箱即用。
开始之前
开始之前，除了定好技术栈 Vue 3.x + ElementPlus 外，需要明确组件库的开发原则：简洁、高效、灵活、可扩展。
首先要有可读性好的文档库，有示例可交互；其次能自动化的重复工作绝不手动复制，文档库自动化部署；最后，最好还有组件测试来保证组件的正确性和完成性。
项目结构
├── docs /* 组件库文档 */
│ .vuepress /* vuepress 配置 */
│ ├── clientAppEnhance.ts /* 注册全局组件 */
│ ├── config.ts /* vuepress配置文件 */
│ index.md /* 文档 */
└── packages /* 包 */
│ ├── layout /* 布局组件 */
│ │ ├── src /* vue组件 */
│ │ ├── package.json /* 组件配置文件 */
│ │ ├── typings /* 组件声明文件 */
│ ├── form /* 表单组件 */
│ ├── table /* 表格组件 */
├── templates /* plop 配置clone的模板文件夹 */
├── typings /* 声明文件夹 */
├── .eslintrc.js /* eslint 配置 */
├── .gitignore /* gitignore 配置 */
├── .prettierrc /* prettier 配置 */
├── .stylelintrc /* stylelint 配置 */
├── babel.config.js /* babel 配置 */
├── jest.config.js /* jest 配置 */
├── LICENSE /* license */
├── package.json /* package.json */
├── plopfile.js /* plop 配置 */
├── tsconfig.json /* ts 配置 */
├── rollup.config.js /* rollup 打包配置 */
└── README.md /* 文档说明文件 */
包管理模式
由于是组件库，多个组件包会有共用的依赖，为减少重复代码，因此选用 lerna + yarn workspace 来进行包管理，这也是现如今大多数组件库的选择。
组件打包
组件打包选用 rollup，因为本次的组件是针对几个通用场景来封装组件，打算分开包来进行管理，rollup 打包能打包多种模式的包 esm, cjs, umd 等等，并且esm自带 tree-shaking，打出来的包语义明确，也比较易于调试。
rollup 打包配置文件放到了最外层，对组件的打包进行统一配置
下面的配置有几个关键点：
- 多入口，每个组件分开打包，并且分别打包出 umd 格式的 index.js 文件以及 esm 格式的 index.module.js 文件
- babel 配置的时候需要手动添加 .ts 和 .vue 的扩展名来正常的编译 ts 和 vue 文件
- 每个包下的 package.json 声明 main module 和 typings ，当支持 esm 方式加载的时候回默认加载 index.module.js，否则加载 index.js
- 配置的时候将 peerDependencies 添加到 external 配置项中，将peerDependencies的包不打包进去，减小包体积，提高打包效率
- esm 支持 tree-shaking，故css不分开打包，这样直接使用 esm 格式就会按需加载，无需借助插件
rollup.config.js
/* eslint-disable @typescript-eslint/no-var-requires */
import fs from 'fs'
import path from 'path'
import json from '@rollup/plugin-json'
import postcss from 'rollup-plugin-postcss'
import vue from '@vitejs/plugin-vue'
import { terser } from 'rollup-plugin-terser'
import { nodeResolve } from '@rollup/plugin-node-resolve'
import typescript from '@rollup/plugin-typescript'
import babel from '@rollup/plugin-babel'
import commonjs from '@rollup/plugin-commonjs'
import { DEFAULT_EXTENSIONS } from '@babel/core'
const isDev = process.env.NODE_ENV !== 'production'
// packages 文件夹路径
const root = path.resolve(__dirname, 'packages')
// 公共插件配置
const getPlugins = () => {
return [
vue(),
typescript({
tsconfig: './tsconfig.json'
}),
nodeResolve({
mainField: ['jsnext:main', 'browser', 'module', 'main'],
browser: true
}),
commonjs(),
json(),
postcss({
plugins: [require('autoprefixer')],
// 把 css 插入到 style 中
inject: true,
// 把 css 放到和js同一目录
// extract: true
// Minimize CSS, boolean or options for cssnano.
minimize: !isDev,
// Enable sourceMap.
sourceMap: isDev,
// This plugin will process files ending with these extensions and the extensions supported by custom loaders.
extensions: ['.sass', '.less', '.scss', '.css']
}),
babel({
exclude: 'node_modules/**',
babelHelpers: 'runtime',
// babel 默认不支持 ts 需要手动添加
extensions: [...DEFAULT_EXTENSIONS, '.ts', '.tsx', '.vue']
}),
// 如果不是开发环境，开启压缩
!isDev && terser({ toplevel: true })
]
}
module.exports = fs
.readdirSync(root)
// 过滤，只保留文件夹
.filter(item => fs.statSync(path.resolve(root, item)).isDirectory())
// 为每一个文件夹创建对应的配置
.map(item => {
const pkg = require(path.resolve(root, item, 'package.json'))
return {
input: path.resolve(root, item, 'src/main.ts'),
output: [
{
name: 'index',
file: path.resolve(root, item, pkg.main),
format: 'umd',
sourcemap: isDev,
globals: {
vue: 'vue',
'element-plus': 'element-plus'
}
},
{
name: 'index.module',
file: path.join(root, item, pkg.module),
format: 'es',
sourcemap: isDev,
globals: {
vue: 'vue',
'element-plus': 'element-plus'
}
}
],
onwarn: function (warning) {
if (warning.code === 'THIS_IS_UNDEFINED' || warning.code === 'CIRCULAR_DEPENDENCY') {
return
}
console.error(`(!) ${warning.message}`)
},
plugins: getPlugins(),
external: Object.keys(require(path.join(root, item, 'package.json'))?.peerDependencies || {})
}
})
组件库文档
sum-ui 组件库文档
本次对比之前的文档库考虑上有所不同，用的是 vuepress ，选它的原因之一是页面简洁灵活，利用插件不仅可以配置组件交互说明，还能配置其他说明引导文档，之前考虑了 vue-styleguidst ，但是其局限性比较强，只能配置组件交互文档并且页面样式没有vuepress 的简洁好看，还调研了 vitepress ，但因为 vitepress 还一直在 WIP 并且把 vuepress 里的 plugins 等多项配置去掉了，如果是纯说明文档用这个完全够，但我们需要有组件交互说明，因而最终还是选择了支持Vue3的 vuepress@next。
vuepress 打包
除了webpack，vuepress@next 还添加了 vite 开发打包的方式，可以在 .vuepress/config.ts 下进行配置
下面的配置有几个关键点：
- 读取packges文件夹下的文件夹名，给引用的包添加 alias 别名
- 由于组件里支持了jsx语法，所以添加了 @vitejs/plugin-vue-jsx 插件
- bundler 的配置(@vuepress/webpack / @vuepress/vite )，如果不设置则默认 webpack, 如果安装了 vuepress-vite 则默认vite打包
- 添加 vuepress 插件 vuepress-plugin-demoblock-plus ，该插件参照了 element-plus 的文档渲染实现做了交互组件渲染
- 由于使用了 GitHub Actions 自动化部署文档到 GitHub pages， 所以 base 选项的配置需要和github的项目名保持一致，因为加载的静态资源路径是该文件夹下的
.vuepress/config.js
const { readdirSync } = require('fs')
const { join } = require('path')
const chalk = require('chalk')
const headPkgList = []; // 非 @sum-ui/开头的组件
const pkgList = readdirSync(join(__dirname, '../../packages')).filter(
(pkg) => pkg.charAt(0) !== '.' && !headPkgList.includes(pkg),
);
const alias = pkgList.reduce((pre, pkg) => {
pre[`@sum-ui/${pkg}`] = join(__dirname, '../../packages', pkg, 'src/Index.vue');
return {
...pre,
};
}, {});
console.log(`🌼 alias list \n${chalk.blue(Object.keys(alias).join('\n'))}`);
module.exports = {
title: "sum-ui", // 顶部左侧标题
description: 'Vue3 + ElementPlus 组件库',
base: '/sum-ui/',
bundler: '@vuepress/vite',
bundlerConfig: {
viteOptions: {
plugins: [
vueJsx()
]
}
},
alias,
head: [
// 设置 描述 和 关键词
[
"meta",
{ name: "keywords", content: "Vue3 UI 组件库" },
]
],
themeConfig: {
sidebar: {
// 侧边栏
"/": [
{
text: "介绍",
children: [
{ text: "安装", link: "/guide/install" },
{ text: "快速上手", link: "/guide/start" },
],
},
{
text: "组件",
children: [
{ text: "Layout 布局", link: "/components/layout" },
{ text: "Table 表格", link: "/components/table" }
],
},
],
},
nav: [
// 顶部右侧导航栏
{ text: "介绍", link: "/", activeMatch: "^/$|^/guide/" },
{
text: "组件",
link: "/components/layout.html",
activeMatch: "^/$|^/components/"
}
],
// page meta
editLinkText: '在 GitHub 上编辑此页',
lastUpdatedText: '上次更新',
contributorsText: '贡献者',
},
plugins: ['demoblock-plus'] // vuepress-plugin-demoblock-plus 插件，作用是展示交互文档和代码展开
};
.vuepress/clientAppEnhance.ts
除 config.ts 的配置外，还需要全局注册组件才生效，需要加 clientAppEnhance.ts 来进行配置
import { defineClientAppEnhance } from '@vuepress/client'
import 'element-plus/theme-chalk/src/index.scss' // 全量引入样式文件 scss TODO: 这里如果用element-plus 文档里的方法 vite-plugin-element-plus 插件按需引入的话，dev 正常但是 vuepress build 打包 scss @import 就会报错
import SumTable from '@sum-ui/table'
import SumLayout from '@sum-ui/layout'
export default defineClientAppEnhance(({ app }) => {
app.component('SumTable', SumTable)
app.component('SumLayout', SumLayout)
})
组件开发预览
交互文档库配置完成之后，就能边开发组件库，边看组件最终效果了
yarn docs:dev // vuepress 文档库开发模式
yarn docs:build // vuepress 文档库打包成静态资源文件
打包生成的资源文件可以利用 Github Actions 自动部署到 GitHub Pages 上
sum-ui组件库文档地址
组件测试
组件测试放到每个组件目录下，组件写完可以写该组件的单元测试
vue 的单测用 @vue/test-utils 就可以，另外在组件测试中导入组件的时候，不可直接识别 ts、vue 文件，需要 ts-jest vue-jest babel-jest 来做转换
配置 jest.config.js
const alias = require('./alias')
module.exports = {
globals: {
// work around: https://github.com/kulshekhar/ts-jest/issues/748#issuecomment-423528659
'ts-jest': {
diagnostics: {
ignoreCodes: [151001]
}
}
},
testEnvironment: 'jsdom',
transform: {
'^.+\\.vue$': 'vue-jest',
'^.+\\.(t|j)sx?$': [
'babel-jest',
{
presets: [
[
'@babel/preset-env',
{
targets: {
node: true
}
}
],
[
'@babel/preset-typescript',
{
isTSX: true,
allExtensions: true
}
]
]
}
]
},
moduleNameMapper: alias, // 声明别名以便于在jest中导入文件加载的时候能够正确加载文件
moduleFileExtensions: ['ts', 'tsx', 'js', 'json'],
// u can change this option to a more specific folder for test single component or util when dev
// for example, ['<rootDir>/packages/input']
roots: ['<rootDir>']
}
vue 支持 tsx
babel 的 preset 配置 isTSX: true, allExtensions: true 两个选项，allExtensions 为 true 支持所有扩展名，主要是为了支持 .vue 文件的解析，isTSX 为 true 支持 jsx 语法的解析
babel.config.js
module.exports = {
// ATTENTION!!
// Preset ordering is reversed, so `@babel/typescript` will called first
// Do not put `@babel/typescript` before `@babel/env`, otherwise will cause a compile error
// See https://github.com/babel/babel/issues/12066
presets: [
'@vue/cli-plugin-babel/preset',
[
'@babel/typescript',
{
isTSX: true,
allExtensions: true
}
]
],
plugins: ['@babel/transform-runtime']
}
主题色相关
由于 element-plus 使用了 css 变量，可以通过改变 css 变量来覆盖主题色
main.js
import { themeVarsKey } from 'element-plus'
const themeVars = {
'--el-color-primary': '#29b6b0'
}
const app = createApp(App)
app.provide(themeVarsKey, themeVars)
其他可能会遇到的问题
Cannot read property 'isCE' of null 报错 https://github.com/vuejs/vue-next/issues/4344
在我本地打包组件后 yarn link 到全局，然后在其他项目里引用的时候遇到这个报错，是由于多个 Vue 包引用问题，发布到 npm 之后从 npm 安装引用正常
