外观
历史决策:公共组件抽离
本文记录
@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 stylesArt* 是上游模板的历史命名,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:解耦后进入第一版组件
| 能力 | 阻塞项 | 必要改造 |
|---|---|---|
AppStatus | ArtSvgIcon、模板 tokens | 图标 slot、Kv* tokens、可访问文案 |
ArtSearchBar | vue-i18n、@/ 工具、自动指令 | messages、包内工具、显式导入 |
useTableColumns | $t 和模板类型 | 特殊列 labels 注入、类型内聚 |
ArtTable | Pinia、固定 DOM、页面滚动 | 受控 props、内部 refs、滚动回调 |
ArtTableHeader | Pinia、i18n、全屏 class | 受控 appearance、messages、根节点全屏 |
AppSearchTable | any、固定 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 原则
- 支持命名导入,也支持
app.use()全局安装; - 样式显式导入,且 package.json 标记 CSS side effects;
- 所有 props、emits、slots 和 exposed methods 有导出类型;
- 请求函数只接收标准分页契约,不理解具体后端响应;
- 组件不访问 LocalStorage,不决定用户偏好如何持久化;
- 组件不访问路由、业务 Store 或应用配置;
- 错误、空状态和批量选择必须有可见文本及 ARIA 状态;
- 图标按钮使用原生
button,具备 label、focus 和 disabled 语义; - 宽表格在移动端内部横向滚动,不能让页面整体溢出;
- 默认入口不能打包 Excel、编辑器、视频或 ECharts 等重依赖。
迁移顺序
阶段 1:建立包骨架
- 创建
packages/components、library build、类型声明和测试配置; - 配置
vue、element-pluspeer 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;在没有第二个使用场景前,不继续扩大默认导出范围。