组件/DiffTable 变更表格

DiffTable 变更表格

按阶段呈现 AI 提议的改动:标红、展开新增行

Verified自 0.3.9

用法

DiffTable

提议的菜单精简

挂载后自动播放一次,停在完成态;重新播放按钮走 reset() + play()。

Loading demo...

最佳实践

  • 用 change 表达语义,不要靠自定义 class 硬涂颜色;配色、删除线与折叠都跟着它走。
  • 徽标、彩色 chip 所在列设 tintText: false,否则会被变更色整体重涂。
  • 列宽用百分比或固定 px,避免展开新增行时列错位。
  • 文档站、快照测试与不需要动画的场景用 play="settled",可以直接拿到完成态。
  • 需要按钮触发时用 play="manual" 配合 reset() + play(),不要靠 :key 重挂整个组件。

API 参考

Props

属性名类型默认值说明
columnsDiffTableColumn[][]列配置
rowsDiffTableRow[][]行配置,每行携带自己的变更类型
titlestring-卡片头文案;不传则整条头栏不渲染
play'auto' | 'manual' | 'settled''auto'播放模式
stageDelays[number, number, number][800, 1000, 1000]三段阶段时长(毫秒)
durationnumber400染色与展开的补间时长(毫秒)
selectablebooleanfalse变更行右侧渲染采纳开关,整行也成为切换控件
modelValue(string | number)[]-v-model — 当前被采纳的行 key。绑定即全受控;不传则组件内部记录,且新到的变更行默认已采纳
footerbooleanfalse渲染底部汇总栏(左侧计数、右侧应用按钮)
hintstring-卡片头右端的提示文案,如「点选变更行可切换是否采纳」
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 / modifiednumber仅统计已采纳的行,因此汇总反映的是「按下应用会发生什么」,而不是「差异提议了什么」
totalnumber三者之和

DiffTableColumn

字段类型说明
keystring列 key,同时决定 cell-<key> 插槽名
titlestring表头文本
dataIndexstring从 row.data 取值的字段名,默认取 key
widthstring | number列宽;数字按 px,字符串原样透传(如 '34%')
align'left' | 'center' | 'right'对齐方式
strikeOnRemoveboolean该列在 removed 行加删除线,用于被撤下的值
tintTextboolean该列文字是否跟随变更色,默认 true;自带颜色的徽标列应设为 false
format(value, row, index) => string默认文本格式化

DiffTableRow

字段类型说明
keystring | number行唯一标识
dataT行数据
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全部行保持原样
2removed / 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