Skip to content

组件库与设计系统:从零封装可复用组件 ​

本篇要点:能从零写出一套可发布、可按需引入、有测试和示例的 Vue 组件库,并说清一个 BaseButton 的 props 为什么不该有十四个布尔值。 前置:《TypeScript 与 Vue:类型安全与类型测试》的类型写法决定了 props 契约怎么表达,《请求层:HTTP 封装、缓存与错误处理》的错误对象会成为提示组件的输入;这一章把前两章的零件组装成团队共用的东西。

为什么需要它 ​

2026 年 2 月,一次品牌升级:主色从 #3B82F6 换成 #2563EB。设计只给了一个色值,前端改了 47 个文件、漏了 3 处,两个月后仍有运营截图出来问"这个按钮怎么还是旧蓝"。漏掉的三处不是粗心,是那三个组件把颜色写在了 <style scoped> 里,而全站扫描只按 #3B82F6 搜,其中一处被人写成 rgb(59,130,246)。

同期还有第二件事。支付页想要"圆角更大的确认按钮",开发在页面里写了 :deep(.btn) { border-radius: 12px }。这个页面确实变了,但同一个 Btn 在退款弹窗里也被带着变——因为两者用的是同一个组件,页面级样式顺着根节点漏了进去。上线当天退款弹窗的按钮变成胶囊形,截图进了周会。

这两个故障指向同一件事:没有一层专门存放"决定的形状"。颜色、圆角、间距这些决定散落在组件样式、页面样式、行内样式里,改一次就要全量扫描,还扫不干净。组件库要解决的正是这个——把可复用的界面切成三层,让"决定"只存在于一处。

核心概念 ​

三层结构:token、基础组件、复合组件 ​

设计系统(design system)的第一层是设计变量(design token),也就是颜色、间距、字号、圆角、阴影这些原始决定的命名集合,写法就是 CSS 自定义属性。第二层是不含业务语义的基础组件:BaseButton、BaseInput、BaseModal。第三层是复合了业务含义的组件:OrderStatusTag、SearchBar。依赖只能从上往下,基础组件不许 import 复合组件。如图 7-1 所示。

图 7-1 设计系统的三层依赖与两条消费路径

反例:OrderStatusTag 里直接写 color: #16a34a。这一行让 token 层形同虚设,也让"深色模式"变成一个需要逐文件排查的工程。判断标准很简单——组件里出现十六进制色值、像素圆角、绝对字号,都算越层。

组件 API 设计原则 ​

BaseButton 最常见的坏设计是布尔值堆叠:primary、danger、ghost、text、small、large、block、round、dashed、pill、square、iconOnly、loading、disabled,十四个 boolean 一叠加就是 2¹⁴ 种组合,其中绝大多数没被测过,互斥关系只能靠 if 的先后顺序保证。改成两个枚举就收敛了:variant: 'primary' | 'danger' | 'ghost' | 'text',size: 'sm' | 'md' | 'lg',类型系统直接挡住"既是 primary 又是 danger"。

三个扩展点的取舍可以记成一句话:能枚举的用 props,能是任意内容的用插槽,需要通知外部的用事件。

扩展点用来表达例子反面写法
props有限的、可枚举的形态variant、size、disabled、loadingisBigRedRound 这类一次性布尔值
插槽 slot内容形态不确定的位置icon、footer、defaulticonName: string 再去映射组件表
事件 emit发生了值得外部知道的事click、confirm、update:modelValue内部直接改 store 或父组件数据
暴露 expose命令式操作focus()、open()、scrollTo()把内部 ref 全暴露出去

还有两条容易被忽略的。其一是透传:包装组件的 class、style、aria-* 默认落在组件根元素上,做基础组件时要 inheritAttrs: false 再加 v-bind="$attrs" 到真正的 <button> 上,否则外部的 class 会跑到外层 div,样式对不上。其二是无障碍属于 API——图标按钮必须支持 aria-label,禁用态要用 aria-disabled 而不是只加 opacity: .5,否则读屏软件读不出"不可用"。

样式方案 ​

组件库内部用 CSS 变量存 token,理由是可运行时替换:Sass 变量在编译期就固化成字面量,换肤只能重新打包;CSS 变量挂在 :root 上,深色模式只需再声明一组 [data-theme='dark'] 的值。组件里只写 background: var(--mqx-color-primary),换主题时组件一行不改。

scoped 的能力边界要清楚。它给元素加上 data-v-xxxx 属性,并给选择器补属性选择器,所以父组件样式不会命中子组件内部——但子组件的根节点同时带有父组件的 scope id,父级写 .wrapper .btn 依然能改到它。这就是支付页那次事故的机制。真要做隔离,得靠命名约定(BEM)或者干脆不写跨组件的样式覆盖,把变体做成 props。

原子化方案(UnoCSS、Tailwind)适合页面层,写布局和间距很快;组件库内部仍建议 CSS 变量加少量手写规则,因为组件库要能被不装原子化框架的项目使用。两套并存时给工具类加前缀,避免和应用层的类名撞车。至于 CSS-in-JS,它的运行时注入在服务端渲染时要额外抽样式,组件库这种"被很多项目引用"的场景通常不值得付这个成本。

按需加载与 Tree Shaking ​

按需引入要两件事同时成立:产物是 ESM 且具名导出,以及打包器知道哪些模块没有副作用。

第一件事落在入口写法上:export { BaseButton } from './button' 这种具名导出可以被静态分析,export default { install } 加 app.use() 全量注册则不行——后者的 install 会引用所有组件,打包器无法证明没用到的部分可以删。

第二件事落在 package.json 的 sideEffects 字段。组件库的样式副作用是真实存在的,写成 "sideEffects": false,打包器会把 import './style.css' 整行删掉,产物能跑但没有样式,这类问题在本地开发环境常常看不出来(开发时样式通过插件注入)。正确写法是只标记样式文件:"sideEffects": ["**/*.css", "**/*.scss"]。

验证不能靠感觉。装 rollup-plugin-visualizer,或者在业务项目里只 import { BaseButton },构建后看产物里有没有混进 BaseModal 的代码。另外建议给每个组件提供子路径导出(exports 里的 "./button": "./dist/button/index.js"),配合 unplugin-vue-components 的 resolver,业务侧连 import 都不用写。

文档与单元测试 ​

文档与示例同源是唯一能长期维持的做法:Storybook(或更轻的 Histoire)里每个组件四个 story——默认态、全部变体、边界态(超长文本、空内容、禁用、加载中)、交互态。写 story 的过程本身就是一次 API 审查,如果 story 里要传八个布尔值才能拼出目标外观,说明 API 该改了。

测试用 Vitest 加 @vue/test-utils,原则是断言行为和可访问性,不断言实现细节。查元素用 role 而不是 class 名,因为 class 名重构一次测试就红一片,红了之后大家的处理方式是删测试。快照测试要克制,整棵组件树的快照 diff 通常没人看。

动手实践 ​

第一步,建库工程。 pnpm create vite mqx-ui --template vue-ts,删掉 src/App.vue 里的示例,装 pnpm add -D vitest @vue/test-utils jsdom @vitejs/plugin-vue。预期输出:pnpm test 能跑起来,此时报 No test files found,正常。

第二步,写基础组件。 src/button/BaseButton.vue:

vue
<script setup lang="ts">
const props = withDefaults(defineProps<{
  variant?: 'primary' | 'danger' | 'ghost' | 'text'
  size?: 'sm' | 'md' | 'lg'
  disabled?: boolean
  loading?: boolean
  type?: 'button' | 'submit'
}>(), { variant: 'primary', size: 'md', type: 'button' })

const emit = defineEmits<{ click: [e: MouseEvent] }>()
defineOptions({ inheritAttrs: false })

function onClick(e: MouseEvent) {
  if (props.loading || props.disabled) return
  emit('click', e)
}
</script>

<template>
  <button
    v-bind="$attrs"
    :type="type"
    :class="['mqx-btn', `mqx-btn--${variant}`, `mqx-btn--${size}`]"
    :aria-disabled="disabled || loading"
    :aria-busy="loading"
    @click="onClick"
  >
    <span v-if="loading" class="mqx-btn__spinner" aria-hidden="true" />
    <slot />
  </button>
</template>

<style>
.mqx-btn {
  --mqx-btn-bg: var(--mqx-color-primary);
  --mqx-btn-fg: #fff;
  --mqx-btn-radius: var(--mqx-radius-md, 6px);
  display: inline-flex;
  align-items: center;
  gap: 6px;
  border: 0;
  border-radius: var(--mqx-btn-radius);
  background: var(--mqx-btn-bg);
  color: var(--mqx-btn-fg);
  cursor: pointer;
}
.mqx-btn--danger { --mqx-btn-bg: var(--mqx-color-danger); }
.mqx-btn--ghost { --mqx-btn-bg: transparent; --mqx-btn-fg: var(--mqx-color-primary); }
.mqx-btn--sm { height: 28px; padding: 0 10px; font-size: 12px; }
.mqx-btn--md { height: 32px; padding: 0 14px; font-size: 14px; }
.mqx-btn[aria-disabled='true'] { opacity: .55; cursor: not-allowed; }
</style>

预期输出:在页面里写 <BaseButton variant="ghost" class="mb-2">取消</BaseButton>,渲染出的 DOM 为

html
<button type="button" class="mqx-btn mqx-btn--ghost mqx-btn--md mb-2" aria-disabled="false" aria-busy="false">取消</button>

运行结果:class="mb-2" 落在 button 上而不是外层容器上,说明 inheritAttrs: false 加 v-bind="$attrs" 起效了;aria-disabled 与 aria-busy 也一并渲染出来,读屏软件能读出禁用态。样式块故意不写 scoped:组件库的类名靠 mqx- 前缀区分,不依赖 scope id,使用方在外层做布局时就不必和 :deep() 打架。

第三步,把行为钉成测试。 src/button/__tests__/BaseButton.spec.ts:

ts
import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import BaseButton from '../BaseButton.vue'

describe('BaseButton', () => {
  it('按 role 渲染按钮并透传 class', () => {
    const w = mount(BaseButton, { slots: { default: '保存' }, attrs: { class: 'mb-2' } })
    expect(w.get('button').text()).toBe('保存')
    expect(w.get('button').classes()).toContain('mb-2')
  })

  it('danger 变体切换颜色变量', () => {
    const w = mount(BaseButton, { props: { variant: 'danger' } })
    expect(w.get('button').classes()).toContain('mqx-btn--danger')
  })

  it('disabled 时不派发 click', async () => {
    const w = mount(BaseButton, { props: { disabled: true } })
    await w.get('button').trigger('click')
    expect(w.emitted('click')).toBeUndefined()
    expect(w.get('button').attributes('aria-disabled')).toBe('true')
  })
})

// pnpm vitest run 的输出:
// ✓ src/button/__tests__/BaseButton.spec.ts (3 tests) 26ms
//   ✓ BaseButton > 按 role 渲染按钮并透传 class
//   ✓ BaseButton > danger 变体切换颜色变量
//   ✓ BaseButton > disabled 时不派发 click
// Test Files  1 passed (1)      Tests  3 passed (3)

预期输出:三条 ✓ 全绿,末行 Tests 3 passed (3)。把 aria-disabled 那条断言删掉,第三条用例仍然会过——它靠 emitted('click') 守行为;但把 onClick 里的 props.disabled 判断删掉,这条就会红,说明测的是行为而不是 class 名。

第四步,配入口并验证按需引入。 src/index.ts 用具名导出:export { default as BaseButton } from './button/BaseButton.vue'。vite.config.ts 里用 build.lib 加 preserveModules: true,package.json 写 "sideEffects": ["**/*.css"] 并补上 exports 的子路径。预期输出:在业务项目里只引入 BaseButton 后执行 pnpm build,产物里 BaseButton 所在的 chunk 约 2–4 KB,BaseModal 的代码不在其中;把 sideEffects 改成 false 再构建,页面样式全部丢失——这条对照实验做过一次就不会再写错。

常见误解 ​

"抽象得越早,复用越多。" 只写了一两处的相似界面,通常还没暴露出真正的差异。经验做法是手写三遍、看清变化点之后再抽,抽出来的 props 才是必要的那几个。过早抽出去的基础组件,最后往往长成十四个布尔值的样子,因为每个需求都在往里塞开关。

"scoped 就是完全隔离。" 它只是给选择器加了属性选择器,子组件根节点会同时带上父组件的 scope id,父级样式依然能命中。:deep() 则是主动拆掉隔离。真正的隔离靠命名约定、组件边界和不写跨组件覆盖,而不是指望 scoped 兜住一切。

"发布成 ESM 就有 Tree Shaking。" ESM 只提供了静态分析的可能。入口若是 export default { install } 加全量注册,或者 sideEffects 配置写错,删掉的和没删掉的都不由你决定。判断 Tree Shaking 有没有生效,只在构建产物的体积上,不在配置文件里。

小结 ​

  • 三层结构:token 管决定、基础组件管形态、复合组件管业务;组件里不该出现十六进制色值和绝对圆角。
  • API 优先用枚举与插槽,避免布尔值堆叠;inheritAttrs: false 加 v-bind="$attrs" 保证透传落在真正的元素上。
  • 样式靠 CSS 变量实现运行时换肤;scoped 不等于隔离,:deep() 用一次就少一层边界。
  • 按需引入需要具名导出、子路径 exports、以及精确的 sideEffects 声明,验证只看产物体积。
  • 文档与测试都对着行为写:story 覆盖默认、变体、边界、交互,测试查 role 与 aria-* 而不是 class。

相关主题 ​

组件库把界面的形状固定下来了,但形状正确不等于跑得动:一个 5000 行的订单表格照样能把页面卡到 8 帧。《性能优化:渲染性能、长列表与加载策略》讲 性能优化:渲染性能、长列表与加载策略,用虚拟滚动、组件复用和代码分割把渲染成本压回去,并用 Performance 面板量出优化前后的差别。