ADR-0021:组件中的语义表格插槽
问题
组件原先只返回绘制命令。把语义 Table 提前绘制为命令后,单元格来源、字段及外链无法进入最终页码解析。静态 TableComponent 因此明确拒绝字段、外链和具名字体角色。直接将它改成分页组件会扩大信息损失。
决策
ComponentLayout 保留静态命令,并增加有序 SemanticPlacement。每个插槽保存命令位置、源 Table、测量后的 TableFragment、实际字体组及字体角色快照。绘制时按原命令顺序插入语义内容,不重新测量或分页。旧五参数构造器继续产生纯静态布局。
组合器使用 ComponentSemantics.append 传递插槽。统一几何遍历按相同的 Save、Restore、Transform 和 Clip 顺序定位插槽;字段、外链和书签均使用这一结果。当前只接受平移,语义片段必须完整位于组件及有效裁剪区内;拒绝旋转、缩放和部分裁切。静态绘制仍保留原有仿射变换能力。
语义字段在目录偏移、分节编号和全部正文页面确定后解析。最终替换轮廓不改变预留宽度、原文 UTF-16 范围或单元格几何。插槽保存测量时的字体策略,避免 FontScope 内的字段误用文档默认字体。普通缺字诊断由语义单元格保留来源,不再扁平复制到父组件。
旧 commands() 在包含语义插槽时明确失败,防止未迁移的自定义组合器丢弃内容。自定义组合器应使用 append;需要检查静态部分时,同时处理 staticCommands() 和 semanticPlacements()。页区装饰暂不接入语义终态解析,因而拒绝此类布局。
首批范围
SemanticTable 是固定单视口组件,经 FlowColumn、RowComponent、BoxComponent、组件网格及分栏组合。它沿用核心 Table 测量、富文本、图片、自动列宽和字体角色,不借助 GridTable 模拟语义表格。超出完整新视口的表格明确失败。外部间距由父组件控制。
所有嵌套语义表格与顶层块共享 ID、源文字、单元格、图片和交互预算。首批每个嵌套源只能呈现一次,重复表头中重复放置同一语义表格会因 ID 重复被拒绝。长语义表格的区域分配及按实际呈现解析重复表头留待下一批;本决策不关闭 GAP-03。
后果与兼容
没有新增依赖。文档模型、布局 IR、Display List 与后端的职责仍然分离。DOCX 继续直接映射语义模型;组件中的语义插槽不等于 DOCX 已支持嵌套表格。静态 TableComponent 的兼容契约保持,包含字段或外链的调用应显式改用 SemanticTable。
新增 record 分量保留旧构造调用的源码兼容,但不是已发布二进制兼容承诺。项目尚未发布,仍需重新编译调用方并执行隔离消费验证。