VTable 基础封装与分页国际化接入

概述

技术选型确定后，第一版基础表格组件的目标不是支持所有高级能力，而是先抽出"表格主体 + 分页"的最小复用单元。本章基于 el-table 封装 VTable，把 columns、表格本体 props、分页 props 分开设计，用 withDefaults 建立开箱即用的基线，并通过 ConfigProvider.locale 接入 Element Plus 内置分页国际化。进阶部分则处理分页插槽与事件透传，重点解决分页与表格同名事件（如 current-change）的冲突。

在组件库里，VTable 的边界要画在“通用展示与分页”上，搜索表单、批量操作栏、工具栏这些业务区留给页面层。基础组件越克制，越容易被不同列表页复用；过早把业务能力收进组件，反而会让每个页面都不得不绕开组件的“好心”。

学习目标

理解第一版 VTable 只抽"表格主体 + 分页"，搜索表单不进基础组件
掌握 columns 与 tableProps 的分层设计
用本地类型别名收口 Element Plus 依赖，让 prop 保持可选兼容操作列
用 withDefaults 建立默认基线，对象型 props 用函数返回默认值
通过 ElConfigProvider.locale 接入分页国际化，而非业务 $t()
解决分页事件与表格同名事件冲突，用 page- 前缀 + 可复用透传工具
认识 VTable 边界应止于通用展示与分页，业务区留给页面
理解 defaultSlot 与分页插槽要分别处理而非混用
掌握用 prefix 参数让同一套透传工具服务表格与分页

一、第一版目标：表格主体 + 分页最小复用单元

正式做表格组件时，没有一上来处理复杂操作列、插槽列、树形或虚拟滚动，而是先抽最常见的后台列表页结构：中间是表格内容、底部是分页，页面顶部的搜索表单不放入基础表格组件。因为搜索条件通常属于具体业务页面，表格和分页更偏通用展示能力。只要"表格 + 分页"跑通，绝大多数列表页就能落地。

二、基础 VTable 优先基于 el-table 封装

延续选型结论，第一版仍选经典的 el-table：功能完整、后台常见能力成熟、封装成本低，更适合先做第一版通用组件。组件首版优先稳定和可用，不要一开始就背上虚拟化复杂度；若业务真遇性能瓶颈，后面再评估 V2 或第三方方案也不迟。

三、分页先抽象 layout 和 align 展示层规则

加 el-pagination 后，最先要想的是分页区域显示哪些部分、在底部如何排布，对应 layout 与 align。其中 align（left / center / right）并不是 Element Plus 原生能力，而是 VTable 这一层附加的展示配置，让页面层不用反复自己拼布局类名。第一版先把分页展示规则抽清楚，比接口联动更重要。

四、columns 和 tableProps 分开设计

"列长什么样"和"表格怎么表现"不是同一类配置：columns 决定列结构（prop、label、width、fixed 等），tableProps 决定表格行为（border、fit、show-header、highlight-current-row 等）。二者不拆开，API 一定会越来越乱；后续支持自定义单元格渲染时，columns 的独立性会更有价值。

export interface VTableProps extends Partial<TableProps<any>> {
  columns: VTableColumnType[]
  data: Record<string, unknown>[]
  pagination?: VTablePaginationProps
}

五、本地类型别名收口 Element Plus 依赖

把 TableColumnCtx<any> 这类原始类型包成本地导出类型（如 TableColumnType），页面层导入更直观，后续统一收口第三方依赖，若表格方案替换受影响范围更可控。类型别名的意义在于项目内部 API 收口，而不只是少写几个字。

六、withDefaults 建立开箱即用基线

若把表格和分页 props 全改成可选，某些默认表现会丢失（如 show-header、fit、pagination.total）。基础组件只靠 Partial<> 不够，还要通过 withDefaults 给出一套默认可用的基线。对象型 props（如 pagination）建议使用函数返回默认值；默认值要服务大多数列表页，而不是只服务某个演示页。

七、分页国际化靠 ConfigProvider.locale

分页文案没有跟随业务 i18n 切换，根因是 el-pagination 属于 Element Plus 内置组件，它自己的文案不读取页面里的 $t()，而要通过 ElConfigProvider 注入 locale。只要是分页、日期、空状态这类组件库自带文案，都要靠 ConfigProvider。国际化映射键值时要注意项目里 locale 的命名格式是否一致。

Vue SFC

<ElConfigProvider :locale="messages[localeKey]">
  <RouterView />
</ElConfigProvider>

八、类型设计服务真实场景，不逼用户填空 prop

操作列只有按钮没有真实字段，若类型把 prop 强制必填，会逼开发者写空字符串，这不是好 API 设计。更合理的做法是在本地列类型上让 prop 保持可选，使操作列、插槽列、展示列都能自然兼容。同时，为了消掉 scope 的 any 报错，不要急着全局关闭 noImplicitAny，优先给 scope、column、渲染函数参数补局部类型，避免拉低整个项目的类型质量。

九、进阶：分页插槽与事件透传，解决同名事件冲突

只透传分页 props 会让组件停在半封装状态，分页的默认插槽和事件迟早要接。分页插槽应从 props.pagination.defaultSlot 单独取出，而非和表格列插槽混用。真正的难点是 el-table 和 el-pagination 都有 current-change，直接原名透传会造成语义冲突，因此给分页事件统一加 page- 前缀（page-current-change、page-size-change、page-prev-click、page-next-click）。把分页事件类型 PaginationEventsType 与表格事件 TableEventsType 交叉合并成 VTableEventsType，并让 forwardEventsUtils 支持可选 prefix 参数，使 Table 和 Pagination 共用同一套透传逻辑。

export function forwardEventsUtils(
  emit: (...args: any[]) => void,
  arr: readonly string[],
  prefix = ""
) {
  const forwardedEvents: Record<string, (...args: any[]) => void> = {}
  arr.forEach((eventName) => {
    forwardedEvents[eventName] = (...args: any[]) => emit(`${prefix}${eventName}`, ...args)
  })
  return forwardedEvents
}

十、defaultSlot 与分页插槽要分别落地

分页的默认插槽（pagination.defaultSlot）表达“分页区域右侧的额外内容”，比如共 N 条、跳转页码框，和表格列的 defaultSlot 是完全不同的概念。二者如果混在 VTable 的同一个 slot 机制里，页面层很难分清“这是某一列的渲染”还是“这是分页区的补充”。更清晰的做法是列插槽走 columns 上的 defaultSlot 字段，分页插槽单独从 props.pagination.defaultSlot 取出再透传给 el-pagination，两条线互不干扰。