docs: 重构 Windows UI UX skill 分层

references/core-data-table.md

@@ -0,0 +1,198 @@
+# 桌面数据表格交互规范
+
+## 目录
+
+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 已按项目准确版本验证。