Vue3组件库设计实战：从零搭建企业级UI组件库

Vue3组件库设计是前端工程化的重要实践。业务中重复的表格、表单、弹窗、上传，抽成可复用的组件库后，迭代速度会明显提升。本文以Vue 3.4 + TypeScript + Vite搭建一套企业级组件库，覆盖工程结构、主题定制、单元测试与发布全流程。

Vue3组件库工程结构搭建

采用monorepo结构（pnpm workspace）组织packages目录，每个组件独立package，避免组件间耦合：

packages/
├── components/       # 组件集合入口
│   ├── button/
│   ├── table/
│   └── index.ts
├── theme/            # 设计令牌与主题变量
└── utils/            # 工具函数

组件入口统一从index.ts导出，构建时用defineOptions开启global属性，让组件支持全局注册。

组件API设计：Props、事件与插槽规范

组件API设计遵循三段式：props控制状态，emits声明事件，slots扩展视图。以封装的table增强版为例：

defineOptions({ name: 'YxTable' })
const props = withDefaults(defineProps<{
  data: TableData[]
  columns: TableColumn[]
  pagination?: boolean
}>(), { pagination: true })
const emit = defineEmits<{
  'row-click': [row: TableData]
  'selection-change': [rows: TableData[]]
}>()

组件命名统一前缀（如Yx），避免与第三方库冲突。默认值原则：尽量给合理默认值，减少使用方配置成本，同时保留v-model双向绑定。

样式方案与CSS变量主题定制

主题变量用CSS自定义属性定义在theme包中，组件内使用var(–yx-primary-color)。切换主题时只需覆盖变量：

:root {
  --yx-primary: #1668dc;
  --yx-radius: 4px;
  --yx-font-size: 14px;
}
[data-theme='dark'] {
  --yx-bg: #141414;
  --yx-text: #e0e0e0;
}

按钮颜色、边框、圆角全部走变量，暗黑模式无需改组件代码。

单元测试与组件库发布

用Vitest + @vue/test-utils写单元测试，覆盖组件props变化、事件触发、v-model同步三个基础行为，保证重构时行为不回归。

import { mount } from '@vue/test-utils'
import YxButton from '../button.vue'
it('click event', () => {
  const wrapper = mount(YxButton, { props: { type: 'primary' } })
  wrapper.trigger('click')
  expect(wrapper.emitted('click')).toBeTruthy()
})

发布流程走pnpm publish + changeset管理版本，tag按语义化版本规范发布，文档站点用vitepress搭建，示例代码可直接复制运行。

落地建议与维护边界

组件库先覆盖高频组件：表格、表单、对话框、消息提示，迭代两轮后再扩展日历、树选择等低频组件。维护边界要清晰：组件库只做通用逻辑，业务专属字段不塞进组件，避免组件库膨胀。版本发布后同步更新文档示例，保持文档与代码同步演进。