Table 表格

CfTable 是组件库里功能最完整的”主力”组件之一。设计取舍：

• 客户端模式默认派生 —— 全局搜索、列过滤、排序、分页全部在组件内完成；改成服务端模式只需要给 pagination.total 一个数字。
• 列状态非受控为主 —— 隐藏 / 顺序 / 宽度走内置 state，必要时可通过 update:columnsState 全受控。
• 0 第三方依赖 —— HTML5 DnD 处理列拖拽，PointerEvent 处理调宽，原生 position: sticky 处理固定列与表头。

基础用法

columns + rows + 可选 rowKey。column.format 做展示格式化，column.render 接收渲染函数返回 VNode / 字符串。

选择行

单选 selectable="single" / 多选 selectable="multiple"。v-model 接受 string 或 string[]，由 rowKey 决定。

多列排序

打开 multi-sort 后，按住 Shift / ⌘ 点列头追加次级排序。同列再次点击循环 asc → desc → 取消。表头显示当前列在排序队列中的序号。

排序优先级 = sort 数组顺序。完全受控时把 :sort 绑到自己的 ref 上即可。

拖拽调宽 + 拖拽换序

打开 resizable 后每列右边出现 6px 的 col-resize 区。拖拽实时更新内部 state，@update:columns-state 把新宽度送出来用于持久化。reorderable 让表头可拖拽换序。

单列可以用 resizable: false / reorderable: false 屏蔽。

固定列 + 粘性表头

column.fixed: 'left' | 'right' 把列钉在两侧，超长内容横向滚动时仍可见。配合 sticky-header + :height 表头同时粘顶。

行展开 + 树形数据

expandable 给每行加展开按钮：

• 传 expand-render —— 渲染自定义展开内容（订单详情、嵌套图表等）。
• 行数据自带 children —— 自动当作树形数据递归渲染，每层 tree-indent 像素的缩进。

v-model:expanded-row-keys 把展开状态外置到父组件，方便保存到 URL 或 localStorage。

工具栏 + 总计行 + 分页 + 过滤

把 toolbar="auto" 打开就出现全局搜索与列可见性菜单。column.filterable 给每列加漏斗按钮，filterType 切到 select / number-range / 默认文本。column.summary 接 'sum' | 'avg' | 'count' 或函数；表底自动出一行总计，跟着过滤结果实时变。

:default-pagination="{ page: 1, pageSize: 8 }" 是非受控分页。完全受控用 pagination 绑当前对象，并监听 @update:pagination。

虚拟滚动

打开 virtual 后表体只渲染当前可见的行 + 上下 overscan 缓冲，DOM 节点数恒定在几十个。要求所有行使用固定 row-height（缺省 36px）。建议配合 :height + sticky-header。

50000 行的数据集只渲染 ~30 个 <tr>。继续兼容排序、过滤、固定列、全局搜索。注意：虚拟模式下 expandable 的展开行高也被固定，复杂的展开内容请用 Modal 替代或关闭虚拟。

行拖拽换序

row-reorderable 在最左侧加一列 ⋮⋮ 拖把柄。拖动整行换序，@update:rows 把新数组送出来；想监听 from/to 索引就用 @row-reorder。

仅作用在顶层（level 0）行；树形子行自身不能拖。

内联编辑

给列加 editable: true + 可选 editType: 'text' | 'number' | 'select'，双击单元格进入编辑：

• editValidate 拦截非法值，校验失败时保留编辑态。
• 提交时机：Enter / blur；取消：Esc。
• @cell-edit 抛出 { row, column, oldValue, newValue, index }，由你写回数据源。

组件不直接 mutate 你的 rows：所有提交都通过 cell-edit 事件，业务方决定要不要写回、是否调接口、是否合并。

CSV 导出

exportable 让工具栏出现 Export 按钮，点击导出当前过滤后的结果。导出文件含 UTF-8 BOM，Excel 直接打开不乱码。

• 跳过某列：column.exportable: false
• 自定义单元格序列化：column.exportRender(value, row, i) => string
• 文件名：export-file-name，缺省 'table'
• 完全自定义：@export 事件接到 CSV 字符串，自己 download 或上传到服务端。
• 命令式调用：组件 exportCsv() 已通过 defineExpose 暴露。

列状态持久化

persistKey="<key>" 让组件把当前 columnsState（隐藏 / 顺序 / 宽度）写到 localStorage['cf-table:<key>']，下次访问自动恢复。

完全受控时（外部传 :columns-state）会跳过自动读写，这时由你决定怎么持久化。

自动 rowSpan 合并

给某列加 mergeRows: true，连续相同值的单元格会自动合并 rowSpan。需要更细粒度的合并条件可以传函数：mergeRows: (cur, prev) => cur.groupId === prev.groupId。

合并不会跨树形层级（不同 parentKey 的子行不会被合并到一起）。

单元格选区 + 一键复制

cell-selectable 让表格行为接近 Excel：

• 单击单元格 → 选中
• Shift 单击 / 鼠标拖动 → 矩形选区
• Ctrl/⌘ + C → 复制为 TSV 到剪贴板，可以直接粘到 Excel / Numbers / Google Sheets

column.format 会被尊重 —— 复制出去的就是显示的字符串。

列虚拟化（双向虚拟化）

100+ 列且每列内容简单（如二维数据矩阵）时，启用 col-virtual + 默认 col-width 让横向滚动也只渲染可见列；和 virtual 一起开就是双向虚拟化。

200 行 × 121 列 = 24200 单元格，DOM 实际不到 800 个节点。注意：列虚拟化下 column.fixed 仍然钉住，但要求被钉的列总宽不要超过视口的 1/3，否则可视区会很拥挤。

树形拖拽（跨父节点）

在 row-reorderable 之上加 tree-reorderable，拖拽行为升级为 Excel / Finder / 看板风格的”上下/中间”三段：

• 拖到目标行上 1/4 → 放在它前面（同父）
• 拖到目标行下 1/4 → 放在它后面（同父）
• 拖到中间一半 → 拖进目标行作为它的子节点

不会让你把祖先放进自己的后代里。

@tree-reorder 事件给到 { fromKey, toKey, pos: 'above' | 'below' | 'inside', rows }，业务方可以决定要不要持久化到后端。

TSV 反向粘贴

在 cell-selectable 上再加 cell-pastable：单击或框选起点单元格，按 Ctrl/⌘ + V 粘贴整片 TSV / CSV，从起点开始按行写回；column.editable 控制每格能否写、column.editValidate 拦截非法值。

@cell-paste 事件返回 { applied, skipped }，可以拿来给个 toast 提示。

历史撤销

history-enabled 把 sort / filter / search / pagination / columnsState 的每一次变化记到内存栈，监听 Ctrl/⌘ + Z 撤销、Ctrl/⌘ + Shift + Z / Ctrl + Y 重做。history-depth 控制最多保留多少步（默认 50）。

@history-change 事件吐 { canUndo, canRedo }，方便业务方亮 / 灭对应按钮。组件实例上还暴露 undo() / redo() 命令式调用。

变高行虚拟滚动

virtual 默认要求所有行高一致。如果每行高度不固定（比如 body 是 markdown 渲染、有多张图片），传 :get-row-height="(idx) => 42" 让组件按累计偏移做二分查找定位可见窗口。

注意：getRowHeight 必须纯函数，组件会在每次行数变化时重算累计偏移。如果高度真的需要等 DOM 渲染后才知道，目前的建议是先返回一个估值，DOM 测量完成后再 setState 改回真实值；后续会出 auto-row-height 模式自动用 ResizeObserver。

行编辑模式

把 edit-mode="row" 打开，双击任意行进入整行编辑：所有 editable 列同时变为 input，行尾单独多出一行 Save / Cancel 按钮。Enter 提交、Esc 取消，校验失败保留编辑态。

每个 cell 改动都通过 @cell-edit 事件抛出（与单格编辑一致），业务方决定是否调接口、是否合并提交。组件不 mutate rows。

批量操作工具栏

batch-actions + selectable="multiple"：选中至少一行后，表头上方出现 sticky 的批量操作条，自带 计数 / 导出选中 / 清空，可以通过 #batch-actions 插槽塞自定义按钮（接到 selectedKeys）。

冻结行

pinned-row-keys 的列表里所有 rowKey 会置顶并 sticky 到表体顶部，下面的内容滚动时它们一直可见。常用于”自选”、“高优先级”等需要永远先看到的行。

auto-row-height

virtual 默认按固定 rowHeight。如果 row 内容确实需要等浏览器渲染才能知道高度（富文本、图片、嵌套布局），开启 auto-row-height：组件内置 ResizeObserver 监听每个可见行的真实高度并写回累积偏移表。

第一次渲染会用 rowHeight 作为估值；测量完成后 padTop / padBottom 自动重算。比手写 getRowHeight 函数更省心，但代价是首次滚动可能短暂看到滚动条抖动（系统校准位移）。

服务端模式 · 防抖

输入框 / 过滤面板的状态变化每一帧都触发会把后端打爆。给 :server-debounce="300"（ms）让 update:globalSearch 与 update:filters 在静默 300ms 后才发出。其它信号（点排序 / 翻页）是显式点击，不需要防抖，所以保持同步触发。

<CfTable
  :columns="columns"
  :rows="rows"
  :pagination="{ page, pageSize, total }"
  :server-debounce="300"
  @update:globalSearch="(q) => loadData({ search: q })"
  @update:filters="(f) => loadData({ filters: f })"
/>

服务端模式

只要 pagination.total 是个数字，组件就不自己做客户端 slice：sort / filter / pagination 都通过事件抛给上层，由你去请求服务端：

<CfTable
  :columns="columns"
  :rows="rows"
  :sort="sort"
  :filters="filters"
  :pagination="{ page, pageSize, total }"
  :loading="loading"
  @update:sort="(s) => loadData({ sort: s, filters, page, pageSize })"
  @update:filters="(f) => loadData({ sort, filters: f, page: 1, pageSize })"
  @update:pagination="(p) => loadData({ sort, filters, ...p })"
  @update:globalSearch="(q) => loadData({ search: q })"
/>

API

TableProps

TableColumn

Events / Slots

性能笔记

• 内部所有派生（filtered → sorted → paginated → flat tree）都用 computed/useMemo，只在依赖变时重算。
• 列调宽 / 拖拽换序更新的是列状态对象，不会触发整张表重排——只有命中变化的列重新计算 style。
• 行 1k+ 的场景建议同时启用 pagination + sticky-header + height。如果必须一次渲染上万行，可以用 expandable + children 做”折叠树”分批展示；后续会出独立的 <CfVirtualTable> 做真正的虚拟滚动。
• 在 React 端 Row 组件已经独立化，可在外部用 memo 进一步包装；在 Vue 端单元格 render 函数会被 v-for 自动 patch。