ADR-0019:嵌套文字与合并格的显式续页
背景
列内 .text() 创建不可分页组件,合并行组保持整组移动。用户编写长报告时需要另选文字类,长合并格则直接失败。链式调用未解决实际续页问题。
决策
FlowColumn.Builder.text()创建FlowText,新增fixedText()表达整块移动。配置回调使用FlowText.Builder;最低高度等固定框需求迁至fixedText()。GridTable新增显式allowRowSplit,默认false,原有四/五参数构造器保持整组行为。标准文字格创建FlowText,固定自定义组件继续保持原子性。- 拆分模式先按列宽测量文字一次,准备完整行;显式 OpenType 文字保持轮廓与逻辑文字。混合列递归准备文字、原子组件及间距。准备结果只存在于本次布局,不共享可变游标。
- 按现有合并约束确定自然行高。逐区分配逻辑行高度,跨区格按完整行或原子组件消耗。续区重复表头、格内边距和嵌套列内边距;未消耗内容为所在格的末行补足剩余高度,保证末片段不丢内容。垂直对齐应用于各个可见片段。
- 不能容纳下一原子内容的短首区可以跳过;完整续区必须推进。超高图片、固定文本、不可满足的行数约束和片段预算明确失败,不裁切内容或缩字。
.grid()明确表达组件网格;保留列内.table()作为兼容入口。语义Table与组件网格暂不合并,不宣称字段/DOCX 路径已经统一。
替代方案
直接裁切完整显示列表会切断文字和图片;重复按页重新换行会改变首行缩进、塑形和来源;移植竞争库实现有许可证及架构问题。均不采用。
影响与限制
默认合并组不拆的历史契约保持。拆分仅在显式开关下生效,组件级诊断不冒充语义单元格来源。语义表格字段、富文本合并及 DOCX 合并仍分别跟踪。固定区域仍只接受单片段。自定义组件只测量一次,必须满足既有可信组件契约。
验证
完整行、错位合并、短首区、逐栏表头、图片唯一、固定组件失败、缺字 UTF-16、可重复测量与取消;增加合成 PDF/SVG 样例并独立检查全部页面、原文顺序和坐标,验证隔离坐标调用方。