win_ui_ux_design_skill/references/core-data-table.md

桌面数据表格交互规范

目录

1. 适用范围与交互契约
2. 状态模型
3. 指针事件与优先级
4. 筛选、排序与搜索
5. 勾选、多选与批量操作
6. 键盘与无障碍
7. 数据变化、分页与虚拟化
8. 视觉与反馈
9. 测试矩阵
10. 交付检查清单

1. 适用范围与交互契约

为展示结构化多列数据且支持选择、筛选、操作或编辑的表格、网格和高密度列表使用本规范。只读报表也要定义排序、复制、焦点和空状态；可编辑数据网格还要定义验证、提交和撤销。

在设计或编码前写出交互契约，至少回答：

• 选择单位是整行、单元格还是列；支持单选、连续多选还是非连续多选；
• 复选框代表“批量选择”还是一个真实业务字段；
• 单击行只选择，还是还会导航、展开或编辑；
• 双击行执行默认命令、进入编辑，还是禁用；
• 右键未选中行与已选中行时，命令作用于哪一组对象；
• 筛选作用于本地数据、当前页、已加载数据还是服务端完整结果；
• 排序、筛选、刷新、分页后是否保留选择和勾选；
• 主键、权限和数据变化如何使已有选择失效；
• 每个鼠标操作对应什么键盘和无障碍操作。

若产品未指定，采用本规范的推荐默认值。不要把框架初始属性当作已经确认的产品行为。

2. 状态模型

分离四类状态

状态	含义	推荐规则
当前行/当前单元格	后续键盘命令的目标和导航位置	同一表格通常只有一个；刷新后尽量保持稳定主键
键盘焦点	当前接收键盘输入的元素	必须始终可见；可能在单元格内按钮或编辑器上
选择集	详情、上下文命令或批量操作的对象	使用稳定记录 ID，不使用视图行号
勾选集	选择复选框或业务布尔字段的值	先确定语义；不得默认等同选择集

选择复选框与业务复选框

• 选择复选框： 复选框只是多选的可见入口，勾选集与选择集是同一状态；表头复选框控制明确范围内的选择。
• 业务复选框： 复选框表示“启用”“已审核”等领域字段，与行选择完全独立；列标题必须表达业务含义，不使用无标签的选择列样式。
• 同一表格同时需要两者时使用不同列、不同标题/工具提示和不同视觉反馈，并在规格中分别命名。
• 不要让整行单击切换业务复选框。不要维护两个看似相同但可能不同步的选择数组。

状态不变量

• 排序和筛选改变视图顺序，不改变记录 ID。
• 当前行可以未被多选；选中行也不一定拥有单元格焦点。
• 失效、无权限或被删除的记录必须从操作集合移除并告知用户。
• 行号只用于展示位置，不能作为选择、缓存、编辑或命令参数。
• 视觉上区分 hover、当前、焦点、选中、勾选、编辑、错误和禁用状态。

3. 指针事件与优先级

推荐交互矩阵

输入	目标	推荐结果
左键单击	行的非交互区域	将该行设为当前行；无修饰键时单选，Ctrl 切换，Shift 从锚点范围选择
左键单击	选择复选框	切换该行选择状态；更新当前行，但不触发行默认操作
左键单击	业务复选框	仅切换/提交该字段；不触发行默认操作，选择是否变化须显式规定
左键单击	按钮、链接、菜单或编辑器	仅执行该控件行为；事件不得冒泡成行操作
左键双击	行的非交互区域	执行唯一的非破坏性默认命令，或按契约进入编辑
右键/长按	未选中行	将其设为当前且唯一选中行，再打开针对该行的上下文菜单
右键/长按	已选中行	保留现有多选，打开针对整个选择集的菜单
右键	空白区域/表头	不借用旧行上下文；显示表格级/列级菜单或不显示菜单

事件优先级

按“单元格内控件 → 编辑器 → 行 → 表格空白区域”处理命中目标，内层处理后阻止外层重复执行。不得使用任意延时猜测单击还是双击。

单击行只负责当前项和选择，不执行打开、删除、提交等业务副作用。这样双击产生的两次单击不会重复执行业务命令。双击仅在同一有效记录的非交互区域触发；滚动条、复选框、按钮、链接、输入框和空白区不得触发。

双击默认命令必须满足：

• 非破坏性，通常是打开详情、预览或开始编辑；
• 同时提供 Enter、显式按钮或菜单入口；
• 与内联编辑的双击触发二选一，不同时绑定；
• 数据变化后按稳定 ID 再次确认目标仍存在且允许操作。

上下文菜单打开前先解析命中行和有效选择集。命令文案、启用状态和作用对象数量必须一致；菜单关闭不清除选择。提供 Shift+F10、菜单键或可见命令入口。

4. 筛选、排序与搜索

筛选模型

• 明确全局搜索、列筛选、固定范围筛选和高级条件之间是 AND 还是 OR。
• 按字段类型提供合适运算：文本包含/等于，数字和日期范围，枚举多选，布尔三态，空值/非空。
• 显示每个活动筛选、结果数量和“清除全部”；仅靠输入框内容或列标题颜色不足以表达状态。
• 区分“无数据”与“筛选后无结果”，后者保留条件并提供清除入口。
• 定义大小写、重音、全半角、区域设置、时区、空白和无效输入规则。
• 本地筛选保持界面即时；服务端筛选使用防抖、取消或请求 ID，忽略过期响应并显示加载/错误状态。
• 筛选条件变化通常返回第一页或合适的首个结果，同时避免让焦点跳回页面顶部。

排序

• 表头明确未排序、升序和降序；向无障碍 API 暴露排序状态。
• 多列排序必须显示优先级；不支持时只保留一个排序键。
• 使用稳定排序，定义空值位置和区域感知比较。
• 排序后按记录 ID 保持当前项、选择和未提交编辑，不按旧行号恢复。

筛选与选择的关系

默认保留被筛选隐藏的已选记录，并在批量工具栏显示“已选 N 项，其中 M 项当前不可见”，同时提供仅清除隐藏选择或清除全部。若业务要求筛选即清除选择，必须在操作发生前明确提示并保持一致。

表头全选必须标明范围：当前可见页、当前已加载结果，或所有符合筛选的结果。跨服务端完整结果选择时使用“筛选条件 + 排除 ID”或后端选择令牌等模型，不要假装客户端已持有所有 ID。

5. 勾选、多选与批量操作

• 选择复选框列固定在行首，表头使用三态：无、部分、全部；状态以已声明的全选范围计算。
• 点击表头全选前后都应让范围可理解，例如“选择本页 50 项”或“已选择全部 2,418 个匹配项”。
• Ctrl 支持独立增减选择，Shift 使用上次选择锚点扩展范围；筛选、排序后锚点无效时安全重置。
• 批量工具栏显示选择数量，只提供所有选中记录共同允许的命令。
• 对危险批量操作显示准确对象数和影响；可恢复操作优先支持撤销。
• 处理部分成功：列出成功、失败、跳过和权限不足的数量，允许重试失败项。
• 选择数很大时不要为每个 ID 创建 Widget 或重复复制完整对象；存储 ID/选择表达式。
• 禁用行仍可按需求查看，但不可勾选或执行命令；说明禁用原因。

6. 键盘与无障碍

键盘基线

按键	推荐行为
上/下方向键	移动当前行；是否同时改变选择取决于选定的选择模式
左/右方向键	单元格导航，或在行模式下滚动/进入单元格控件
Ctrl+Space	切换当前行的多选状态
Shift+方向键/单击	从选择锚点扩展连续范围
Ctrl+A	选择明确定义的当前范围；大规模/服务端数据需二次表达全量范围
Space	当前焦点为复选框时切换它；不得同时触发行默认操作
Enter	执行与双击相同的默认命令，或提交当前编辑
F2	进入可编辑单元格；与双击编辑契约保持一致
Escape	取消菜单/编辑；再次按键是否清除选择须明确规定
Shift+F10/菜单键	为当前行或选择集打开上下文菜单

无障碍

• 为表格提供可感知名称、列标题、行/列关系、排序状态、选择状态、复选状态和总数/可见数。
• 焦点与选择使用不同视觉信号，不只依赖颜色。
• 复选框、按钮和链接使用其真实控件语义与名称；不要让整个数据行伪装成多个按钮。
• HTML 静态数据优先使用原生 <table>。只有实现完整二维键盘导航时才使用交互式 grid 语义，并采用 roving tabindex 或 aria-activedescendant。
• 表格发生筛选、批量完成或错误时，以不过度打扰的方式播报结果数量和状态变化。
• 高对比度、200% 缩放和长文本下仍能辨认当前行、选中、勾选、编辑和错误状态。

7. 数据变化、分页与虚拟化

• 所有交互状态关联稳定记录 ID；代理模型、排序、筛选和虚拟化层必须能映射回源记录。
• 刷新时保留仍存在且仍有权限的当前项与选择；不存在的项从集合移除并反馈。
• 编辑期间收到远程更新时定义覆盖、合并、冲突或刷新策略，不得静默丢失输入。
• 分页、增量加载和虚拟滚动不得导致复选状态闪烁、重复触发命令或焦点落到另一条记录。
• 服务端操作携带筛选、排序、页游标和请求 ID；只应用最新有效响应。
• 行命令启动后防止重复提交，显示行级或批量进度，并支持合理取消。
• 大型表格保持虚拟化；不要在每个单元格嵌入常驻复杂控件。

8. 视觉与反馈

• 表头固定或滚动时保持列对应关系；列宽、截断、换行和水平滚动策略必须明确。
• 当前行、选择、勾选与焦点各有可区分状态，但避免叠加过多高饱和背景。
• 可排序列显示方向；可筛选列显示入口和活动状态；不要只在 hover 时显示关键筛选信息。
• 批量操作栏出现时不遮挡表头、分页或最后几行，并保持选择数量可见。
• 行内错误靠近相关单元格，同时提供行级摘要；不要仅用红色边框。
• 加载骨架不得伪装成可选行；刷新时避免清空整个表格造成焦点和滚动跳动。
• 空状态区分首次无数据、筛选无结果、权限不足、加载失败和离线缓存。

9. 测试矩阵

至少验证：

1. 单选、多选、Ctrl、Shift、表头全选和三态复选框；
2. 单击、双击、右键、长按以及单元格内复选框/按钮/链接/编辑器；
3. 右键未选中行、已选中行、空白区和表头；
4. Enter、F2、Space、Ctrl+Space、Ctrl+A、Shift+F10、Escape 和方向键；
5. 筛选后无结果、多个条件、清除全部、服务端延迟、失败和过期响应；
6. 排序、筛选、刷新、分页和虚拟滚动后的当前项、选择、勾选及焦点；
7. 删除选中项、权限变化、部分成功、重复提交和窗口提前关闭；
8. 0、1、少量、大量和超大数据，长文本、空值、重复显示值和稳定 ID；
9. 浅色、深色、高对比度、100%–200% 缩放、键盘和屏幕阅读器；
10. 原型与最终桌面实现使用同一交互契约的对照验收。

10. 交付检查清单

• 已定义行/单元格选择模式及当前项、焦点、选择集、勾选集的关系。
• 已明确复选框是选择入口还是业务字段。
• 单击、双击、右键和单元格内控件不会重复触发行默认命令。
• 右键目标、多选保留和键盘上下文菜单行为明确。
• 筛选运算、服务端/本地范围、空值、结果数和清除入口完整。
• 表头全选范围、隐藏选择、三态和大规模全选模型明确。
• 排序、筛选、刷新、分页和虚拟化均使用稳定 ID 保持状态。
• 鼠标功能具有键盘、触控和无障碍等价路径。
• 原型与最终桌面实现已按测试矩阵验证，而非只检查静态视觉。
• 组件/API 已按项目准确版本验证。