table-template-designer

设计和生成企业级复杂数据表格模版的 UI 规范与交互标准。

这项技能的核心价值：将 ToB 产品中最复杂、最容易出错的"数据密集型表格"从经验驱动提升为规范驱动。一张费用申报表、一张多维统计报表，往往涉及 30+ 列、多级表头、冻结列、级联选择、条件只读等复杂交互——这些细节如果没有标准化规范，每次都要从零试错。

适用场景

• 计划编制/汇总表（如多维成本套表）
• 财务报表/损益表
• 数据录入模版（带下拉选择、联动筛选）
• 审批流中的明细数据展示表
• 任何列数 ≥ 10、需要横向滚动的复杂表格

输入

• PRD 中的表格结构描述（列定义、数据类型、业务规则）
• 可选：已有的 Excel 业务模版截图或说明

调用方随调用给出的参数，优先作为输入源。

表格整体结构规范

1. 标题行（Title Row）

表格最顶部必须有一行全宽合并的标题行。标题行是报表的"门牌号"——在企业场景中，一个报表审批人可能同时打开多张表，标题行帮助他在一秒内确认"我在看哪张表"。

规范：

标题行背景使用中性灰底，不用深主题色，也不用过浅的底色。核心原则：标题行是"锚点"而非"焦点"，它的视觉重量不应超过数据区域。

2. 多级表头（Multi-level Header）

企业报表通常有 3～4 层表头。这不是过度设计——当一张表有"年度合计、Q1计划、Q1实际、Q2计划..."等列时，如果没有分组表头，用户根本无法定位到目标列。

Row 0: 标题行（全宽合并）
Row 1: 一级分组（组织列 rowSpan=3 | 历史数据区 | 填报数据区 | 备注列 rowSpan=3）
Row 2: 二级分组（季度分组）
Row 3: 三级明细（月份列）

分区色彩语义——通过颜色让用户无需读文字就能区分区域性质：

3. 冻结列（Sticky Columns）

当表格超过屏幕宽度时，左侧的组织架构列必须冻结。这是因为用户横向滚到第 25 列去填数据时，如果看不到这行属于哪个部门，就完全无法工作。

布局常量定义模式（逐级累加，便于维护）：

const COL_W = { seq: 50, unit: 110, dept: 90, category: 120, subject: 130 };
const STICKY = {
  seq: 0,
  unit: COL_W.seq,
  dept1: COL_W.seq + COL_W.unit,
  // ... 后续列的 left 值 = 前面所有列宽度之和
};

关键 CSS 规则：

• 所有 sticky 单元格添加 bg-clip-padding——这是解决 sticky 元素背景色覆盖边框的必要手段
• 最右侧冻结列添加 boxShadow: '2px 0 4px rgba(0,0,0,0.06)' 作为与滚动区的分割线
• 表头 zIndex (30) > 数据行 zIndex (10)，避免滚动时层叠穿透

4. 序号列

最左侧固定宽度 50px，自动递增 1, 2, 3...，末行显示 ... 表示可无限扩展。样式 font-medium text-gray-500。

单元格交互规范

1. Excel 风格下拉选择器

这是本规范最核心的交互模式。原理是用一个透明的原生 <select> 覆盖在展示层上方，这样既有自定义的视觉效果，又获得了原生的下拉行为（无需自己实现弹出层和键盘导航）。

详见 references/dropdown_cell.md 中的完整代码模板和交互要点。

2. 级联下拉（Cascading Dropdown）

多级联动的下拉选择器，例如：集团总部→区域→门店，采购品类→子品类。

核心规则：

1. 上级未选择时，下级 disabled + 背景置灰（bg-gray-50/30）+ 箭头隐藏
2. 上级变更时，所有下级自动重置为空——防止出现"一级组织=东区一店，二级组织=东区"这种脏数据
3. 无下级时统一显示 -- 占位符，而非隐藏列
4. 联动重置逻辑集中在 updateRow 函数中管理

详见 references/cascading_dropdown.md 中的数据结构和联动代码。

3. 只读与空行

空行使用 \u00A0 而非 ''，因为浏览器会对空内容单元格执行高度塌陷，导致行高不一致。

模版表 vs 实例表

边框与单位

• 所有单元格统一 border border-gray-200
• 冻结列与滚动区边框必须一致（bg-clip-padding 解决 sticky 背景覆盖问题）
• 数值区表头分组右侧标注"单位：元"，绝对定位右对齐

与 ui-generator 的关系

本技能是 ui-generator 的下游专项技能。当 ui-generator 在生成页面时遇到列数 ≥ 10 的复杂表格场景，应引用本技能的规范。

ui-generator（页面级）
  └── table-template-designer（组件级，本技能）

质量自检

• 标题行使用了 bg-gray-100 低饱和灰底？
• 冻结列全部添加了 bg-clip-padding？
• 最右侧冻结列有 boxShadow 分割线？
• 下拉选择器实现了悬浮显示箭头的交互？
• 级联下拉在上级变更时自动重置下级？
• 空行使用了 \u00A0 保持行高一致？
• 数据行数 ≥ 5 行 + 1 行 ... 省略行？
• 数值区表头标注了"单位：元"？
• 分区色彩遵循语义（琥珀=历史、蓝=当前、绿=自动）？
• 标题行 colSpan 精确匹配总列数？

停机条件

同时满足才算完成：

1. 质量自检各项都有结论，并在交付说明里逐项写明：满足、不适用（附理由）或已修复
2. 已做代码缺陷自查并修复，见 代码缺陷自查。这是作者自己的质量动作：发现即修，向用户简述修了什么，不出报告。

停下交用户：表格的列、分区或联动规则在输入里缺失；与所在页面的既有表格规范冲突。