DiffTable 变更表格
按阶段呈现 AI 提议的改动:标红、展开新增行
用法
DiffTable
提议的菜单精简
挂载后自动播放一次,停在完成态;重新播放按钮走 reset() + play()。
Loading demo...
最佳实践
- 用
change表达语义,不要靠自定义 class 硬涂颜色;配色、删除线与折叠都跟着它走。 - 徽标、彩色 chip 所在列设
tintText: false,否则会被变更色整体重涂。 - 列宽用百分比或固定 px,避免展开新增行时列错位。
- 文档站、快照测试与不需要动画的场景用
play="settled",可以直接拿到完成态。 - 需要按钮触发时用
play="manual"配合reset()+play(),不要靠:key重挂整个组件。
API 参考
Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columns | DiffTableColumn[] | [] | 列配置 |
rows | DiffTableRow[] | [] | 行配置,每行携带自己的变更类型 |
title | string | - | 卡片头文案;不传则整条头栏不渲染 |
play | 'auto' | 'manual' | 'settled' | 'auto' | 播放模式 |
stageDelays | [number, number, number] | [800, 1000, 1000] | 三段阶段时长(毫秒) |
duration | number | 400 | 染色与展开的补间时长(毫秒) |
selectable | boolean | false | 变更行右侧渲染采纳开关,整行也成为切换控件 |
modelValue | (string | number)[] | - | v-model — 当前被采纳的行 key。绑定即全受控;不传则组件内部记录,且新到的变更行默认已采纳 |
footer | boolean | false | 渲染底部汇总栏(左侧计数、右侧应用按钮) |
hint | string | - | 卡片头右端的提示文案,如「点选变更行可切换是否采纳」 |
summaryFormatter | (counts: DiffTableCounts) => string | 见下 | 汇总文案。默认 2 removals · 1 addition 式英文 |
applyLabelFormatter | (count: number) => string | 见下 | 应用按钮文案。默认 Apply N changes |
rowToggleLabelFormatter | (accepted, change) => string | 见下 | 行开关的无障碍名。默认 Accept / Reject this change |
三个 formatter 都有英文默认值:TuffEx 不带文案目录,复数与翻译归宿主。
DiffTableCounts
| 字段 | 类型 | 说明 |
|---|---|---|
added / removed / modified | number | 仅统计已采纳的行,因此汇总反映的是「按下应用会发生什么」,而不是「差异提议了什么」 |
total | number | 三者之和 |
DiffTableColumn
| 字段 | 类型 | 说明 |
|---|---|---|
key | string | 列 key,同时决定 cell-<key> 插槽名 |
title | string | 表头文本 |
dataIndex | string | 从 row.data 取值的字段名,默认取 key |
width | string | number | 列宽;数字按 px,字符串原样透传(如 '34%') |
align | 'left' | 'center' | 'right' | 对齐方式 |
strikeOnRemove | boolean | 该列在 removed 行加删除线,用于被撤下的值 |
tintText | boolean | 该列文字是否跟随变更色,默认 true;自带颜色的徽标列应设为 false |
format | (value, row, index) => string | 默认文本格式化 |
DiffTableRow
| 字段 | 类型 | 说明 |
|---|---|---|
key | string | number | 行唯一标识 |
data | T | 行数据 |
change | 'unchanged' | 'added' | 'removed' | 'modified' | 变更类型,默认 'unchanged';modified 走警示色 |
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
stageChange | (stage: number) | 每次阶段推进时触发 |
settled | () | 到达终态时触发一次,无论由哪条路径抵达 |
update:modelValue | (keys) | 采纳集合变化。按行序发出,不是按点击顺序 |
toggle | ({ key, accepted }) | 单行被采纳或取消 |
apply | (keys) | 应用按钮被按下,带上当时仍被采纳的 key |
Slots
| 名称 | 说明 |
|---|---|
title | 替换卡片头文案 |
hint | 替换卡片头右端提示 |
footer | 替换整个底部栏;接收 { counts, accepted } |
cell-<columnKey> | 自定义单元格;接收 { row, column, value, change, index },change 让插槽内容自行响应变更态 |
Expose
| 名称 | 说明 |
|---|---|
play() | 从当前阶段继续推进 |
reset() | 回到原始表格并清掉待执行的阶段 |
settle() | 直接跳到完成态 |
stage | 当前阶段序号;完成态等于 stageDelays.length |
阶段与播放模式
stageDelays 是三段时长 [停顿, 标红, 展开],默认 [800, 1000, 1000]。第一段是刻意的阅读停顿:在它和第二段走完之前(默认 1.8 秒)表格完全不动,让人先读清原始数据,再看到改动。
| 阶段 | 画面 |
|---|---|
| 0–1 | 全部行保持原样 |
| 2 | removed / modified 行染色、变色、加删除线 |
| 3(终态) | added 行以 0fr → 1fr 展开 |
play 决定谁来推进:auto 挂载即播一次并停在终态;manual 保持原样直到调用 play();settled 直接渲染完成态且不注册任何定时器(文档站与测试用)。
概述
- 阶段机是这个组件的语义本体,不是 demo 编排;宿主用
play与 expose 控制节奏,用rows[].change描述改动。 - 定时器在
onBeforeUnmount清理;play="settled"不注册任何定时器。 - 减弱动效(
prefers-reduced-motion: reduce)下只砍补间,不砍状态机:阶段照常推进,只是不再有过渡动画。冻结状态机会让人看着一张永远不显示改动的表格。 - 行染色由 class 驱动而非内联样式,因此被标红的行仍然有 hover 反馈。
- 新增行折叠时带
aria-hidden与inert,不会被朗读,也不在 Tab 序列里。 - 新增行的内层网格与
<colgroup>都由columns推导,只有一份真相。
技术实现
- 组件源码:
packages/tuffex/packages/components/src/diff-table/src/TxDiffTable.vue;类型见types.ts,index.ts手写TxDiffTableInstance(泛型组件的 expose 面按解包类型声明)。 - 来源: Adapted from Beautiful UI (https://www.beautifului.dev), © 2026 Shane Levine, MIT。新增行按
rows中的位置渲染,modified为本移植新增。 - 已知限制: 高对比主题(
html[data-tx-contrast='high'])下--tx-bui-*保持 BUI 原值,不参与高对比 ramp。
查看源码
packages/tuffex/packages/components/src/diff-table/index.ts