Skip to content

历史决策:公共组件抽离 ​

本文记录 @kevairy/components 建立时的审计、方案和迁移过程。迁移已经完成,当前公开 API 以组件文档为准。

结论 ​

建立单独的 packages/components 项目是合理的,但不能把 apps/template/src/components/core 整体复制过去。第一版 @kevairy/components 应只围绕搜索表格场景建立最小闭环,并同时包含组件、类型和 composables。

推荐第一版公开能力:

text
@kevairy/components
├── KvStatus
├── KvSearchBar
├── KvTable
├── KvTableToolbar
├── KvSearchTable
├── usePagedTable
├── useTableColumns
├── search/table types
└── component-owned styles

Art* 是上游模板的历史命名,App* 又无法表达包归属。新包统一使用 Kv* 作为组件前缀,composables 保持 use* 命名。

审计范围 ​

当前模板包含 76 个 Vue 组件和 9 个组件目录内的辅助文件。本次检查了:

  • 组件之间的引用关系;
  • 对应用 Store、路由、全局配置和 i18n 的依赖;
  • Element Plus、VueUse、Iconify、ECharts 等第三方依赖;
  • Tailwind 工具类和 --art-* 主题变量;
  • 自动导入、固定 DOM 节点和浏览器全局对象;
  • 现有使用频率与自动化测试覆盖。

组件数量不等于公共价值。当前页面真正形成完整使用链路的是布局系统、异常/结果页和搜索表格;其余大量组件仍是上游能力库存,不能因为“看起来通用”就直接成为公共 API。

搜索表格依赖链 ​

text
搜索表格示例页
├── AppSearchTable
│   ├── ArtSearchBar
│   │   ├── vue-i18n
│   │   ├── Element Plus
│   │   ├── responsive.ts
│   │   └── sanitize.ts
│   ├── ArtTableHeader
│   │   ├── Pinia tableStore
│   │   ├── vue-i18n
│   │   ├── vue-draggable-plus
│   │   └── 固定全屏 DOM class
│   ├── ArtTable
│   │   ├── Pinia tableStore
│   │   ├── useCommon
│   │   ├── useTableHeight
│   │   └── 固定页面滚动容器和 header id
│   └── AppStatus
│       └── ArtSvgIcon
├── usePagedTable
└── useTableColumns
    ├── 应用 i18n 函数
    └── 模板内 ColumnOption

这条链路的页面交互已经成熟,但包边界还不成熟。需要先把状态、文案、主题和 DOM 控制权交还给调用方,再进行物理搬迁。

主要耦合问题 ​

1. 应用状态渗透 ​

ArtTable 和 ArtTableHeader 直接读取 useTableStore。这会强迫所有使用者安装 Pinia、注册模板 Store,并接受模板自己的持久化策略。

组件包应改成受控状态:

ts
interface TableAppearance {
  size: 'small' | 'default' | 'large'
  stripe: boolean
  border: boolean
  headerBackground: boolean
}

通过 appearance 和 update:appearance 传递,是否持久化由业务应用决定。

2. 文案绑定应用 i18n ​

搜索、重置、空数据、错误、总数和列设置文案目前来自模板语言包或直接写死中文。公共包不应要求调用方采用相同的 vue-i18n 实例。

第一版采用包级默认 messages,并允许插件级与组件级覆盖:

ts
createKevairyComponents({ messages })

<KvSearchTable :messages="pageMessages" />

内部不直接调用模板 $t。业务项目如果使用 vue-i18n,只需把翻译结果传给 messages。

3. 样式依赖模板运行时 ​

现有组件混用了 Tailwind 工具类、Element Plus tokens 和 --art-* 变量。如果直接发布,未安装模板 Tailwind 配置的项目会得到残缺界面。

公共包必须:

  • 使用组件自带的 CSS,不要求消费方编译包内 Tailwind 类;
  • 定义 --kv-* 语义 tokens;
  • 默认 tokens 映射到 Element Plus tokens;
  • 支持浅色和暗色模式,不读取模板 Store;
  • 将样式作为显式的 @kevairy/components/style.css 导出。

4. 全局 DOM 与自动导入 ​

ArtTable 通过固定 art-table-header id 查找工具栏,并调用模板页面的滚动容器;工具栏全屏逻辑依赖外部 class 和 document.body。组件源码还依赖模板的 Vue API 与组件自动导入。

公共包中需要改为:

  • 使用组件内部 refs 和 ResizeObserver;
  • 通过可选回调决定翻页后的外层滚动行为;
  • 全屏目标使用组件根节点,不查询全局 class;
  • 所有 Vue、Element Plus 和内部组件都显式导入;
  • 源码中禁止出现 @/、@views 等应用别名。

5. API 泛型不足 ​

AppSearchTable 的 data、columns 和选择事件仍使用 any,并把 row-key 固定为 id。公共 API 应将行类型和查询类型贯穿组件、事件、slots 和 composable。

建议核心类型:

ts
type RowKey<T> = keyof T | ((row: T) => string | number)

interface PagedTableRequest<Q> {
  query: Q
  current: number
  size: number
  sort?: PagedTableSort
  signal: AbortSignal
}

interface PagedTableResponse<T> {
  records: T[]
  total: number
}

rowKey 必须由调用方提供或显式使用默认值,不能假设所有后端模型都有 id。

候选能力分级 ​

A:可以作为第一批内核 ​

能力当前情况处理方式
usePagedTable已有并发取消、分页、排序、错误与选择状态测试移入包并补充 clone/error 可配置项
sanitizeSearchParams基本是纯函数,已有测试与搜索类型一起移动
响应式 span 计算纯函数,无应用依赖作为 SearchBar 内部工具
useTableHeight只依赖 Vue refs改成包内私有 composable

B:解耦后进入第一版组件 ​

能力阻塞项必要改造
AppStatusArtSvgIcon、模板 tokens图标 slot、Kv* tokens、可访问文案
ArtSearchBarvue-i18n、@/ 工具、自动指令messages、包内工具、显式导入
useTableColumns$t 和模板类型特殊列 labels 注入、类型内聚
ArtTablePinia、固定 DOM、页面滚动受控 props、内部 refs、滚动回调
ArtTableHeaderPinia、i18n、全屏 class受控 appearance、messages、根节点全屏
AppSearchTableany、固定 row key、硬编码文案端到端泛型、rowKey、messages、slots

C:后续按需抽离 ​

组件族结论
ArtSvgIcon、ArtCountTo、结果页较通用,但应在真实项目产生第二个使用场景后再稳定 API
ArtForm可复用,但与 SearchBar 的 schema 能力重叠,需要先统一表单 schema
右键菜单、水印、图片裁剪、视频可做可选入口;需要先补键盘、焦点、SSR 和按需依赖测试
Excel 导入导出、富文本编辑器第三方依赖较重,应使用独立 subpath,不能进入默认 bundle
图表和图表卡片依赖 ECharts 插件、主题 Store 与模板 tokens,适合第二阶段单独设计

D:保留在模板应用 ​

  • Header、Sidebar、工作标签页、面包屑和页面内容容器;
  • 设置面板、全局搜索、通知、聊天和快速入口;
  • 登录视图、异常页中的路由行为和品牌 Logo;
  • 节日文字、烟花效果及其他模板运行时能力。

这些组件表达的是 Kevairy Admin Template 的应用架构,不是跨项目的基础组件 API。

不应发布的遗留能力 ​

useTable.ts 原有约 736 行,没有实际调用点,并与已有测试覆盖的 usePagedTable 职责重叠。它同时包含缓存、响应适配、防抖、分页和错误处理,公共 API 面过大。

最终可达性检查确认 useTable 及其专用的 tableCache/tableUtils/tableConfig 没有调用者,现已从模板删除。组件包只保留 usePagedTable 这条简单且可组合的路径。其他未使用的上游展示组件也应先做可达性清理,不应借组件库迁移继续保留。

包结构设计 ​

text
packages/components/
├── package.json
├── src/
│   ├── components/
│   │   ├── feedback/KvStatus.vue
│   │   ├── search/KvSearchBar.vue
│   │   ├── table/KvTable.vue
│   │   ├── table/KvTableToolbar.vue
│   │   └── patterns/KvSearchTable.vue
│   ├── composables/
│   │   ├── usePagedTable.ts
│   │   └── useTableColumns.ts
│   ├── styles/
│   │   ├── tokens.css
│   │   └── index.css
│   ├── types/
│   │   ├── search.ts
│   │   └── table.ts
│   ├── defaults/messages.ts
│   ├── index.ts
│   └── install.ts
└── tests/

包名使用 @kevairy/components。第一版 peer dependencies 仅包含 vue 和 element-plus;拖拽列设置等确定会进入运行时的能力作为普通 dependency。Pinia、vue-router、axios、模板配置和模板 i18n 不得成为依赖。

公共 API 原则 ​

  1. 支持命名导入,也支持 app.use() 全局安装;
  2. 样式显式导入,且 package.json 标记 CSS side effects;
  3. 所有 props、emits、slots 和 exposed methods 有导出类型;
  4. 请求函数只接收标准分页契约,不理解具体后端响应;
  5. 组件不访问 LocalStorage,不决定用户偏好如何持久化;
  6. 组件不访问路由、业务 Store 或应用配置;
  7. 错误、空状态和批量选择必须有可见文本及 ARIA 状态;
  8. 图标按钮使用原生 button,具备 label、focus 和 disabled 语义;
  9. 宽表格在移动端内部横向滚动,不能让页面整体溢出;
  10. 默认入口不能打包 Excel、编辑器、视频或 ECharts 等重依赖。

迁移顺序 ​

阶段 1:建立包骨架 ​

  • 创建 packages/components、library build、类型声明和测试配置;
  • 配置 vue、element-plus peer dependencies;
  • 建立 tokens、messages 和禁止应用别名的 lint 规则。

阶段 2:迁移无 UI 内核 ​

  • 移动 usePagedTable、参数清洗、响应式 span 计算和公共类型;
  • 将现有单测迁到包内;
  • 模板先通过 workspace:* 使用这些 exports。

阶段 3:在原地解除 UI 耦合 ​

  • 将表格外观改为受控状态;
  • 移除 vue-i18n、Pinia、固定 DOM 和页面滚动依赖;
  • 去除 Tailwind 与 --art-* 依赖;
  • 补齐组件行为、slots、键盘和移动端测试。

阶段 4:移动 UI 并切换模板 ​

  • 迁移 KvStatus、KvSearchBar、KvTableToolbar、KvTable 和 KvSearchTable;
  • 示例页只从 @kevairy/components 导入;
  • 删除模板中的旧实现,保证不存在双份源码。

阶段 5:稳定发布边界 ​

  • 在 VitePress 增加组件 API、交互示例和迁移说明;
  • 使用组件冒烟项目验证安装、类型、样式和 tree-shaking;
  • 完成模板 E2E 后再确定 0.1.0 公共 API。

第一版验收条件 ​

  • @kevairy/components 能独立 build 并生成 .d.ts;
  • 包源码不包含应用别名、Pinia、router、AppConfig 和 LocalStorage;
  • 模板搜索表格完全从 workspace 包消费,不保留本地副本;
  • 查询、重置、分页、排序、取消请求、空状态、错误恢复和多选测试通过;
  • props、emits、slots 和 row 类型不使用公开 any;
  • 键盘可以操作搜索、刷新、密度、列设置、分页和恢复按钮;
  • 375px 下页面无横向溢出,宽表格只在自身容器滚动;
  • 浅色、暗色和 reduced-motion 模式均可用;
  • 默认入口不包含未使用的重型第三方库。

下一步 ​

“包骨架 + 无 UI 内核迁移”已经完成:usePagedTable、搜索参数清洗、响应式 span 计算和公共类型已由 @kevairy/components 单独构建、测试,并通过 workspace:* 提供给模板。

阶段 3 也已完成:搜索表格 UI 已改用受控 appearance/messages/fullscreen/showSearchBar,显式要求 rowKey,并移除了 Pinia、vue-i18n、固定 DOM 查询、页面滚动、Tailwind 和 --art-* 依赖。列设置提供拖拽及键盘上移/下移两种操作,375px 下页面无横向溢出,宽表格在自身区域滚动。

阶段 4 已完成:KvStatus、KvSearchBar、KvTableToolbar、KvTable 和 KvSearchTable 已物理移动到 @kevairy/components,模板删除了本地 UI 源码并只从 workspace 包消费。

阶段 5 已完成:VitePress 已提供组件 API、可交互示例和迁移说明;组件冒烟项目会验证插件安装、类型、完整样式和 @kevairy/components/core 轻量入口,模板 E2E 也已纳入验收命令。

下一步是根据真实业务接入反馈稳定 0.1.0 API;在没有第二个使用场景前,不继续扩大默认导出范围。