对一个从第 4 页底部开始、到第 5 页顶部结束的段落,读者眼里它就是一个段落。在带标记的 PDF 里,它分布在两个内容流中,而每一页都各自为自己的标记内容序列编号,所以结构树需要的是一个 P 元素,其 /K 数组同时指向第 4 页的 MCID 7 和第 5 页的 MCID 3。如果先用坐标代码把页面画出来、事后才补打标记,无障碍检查器里的标签树通常会把一个段落显示成两个,还会把一整套列标题塞进每张续排表格的数据里
坐标路线还有一笔来得更早的第二笔成本。报表的第一版能跑。然后客户地址长到了三行,某个本地化标题折了行,某张表格多出四十行,从此往下的每个 y 位置全都是错的。分页检查散落在业务逻辑里,而当无障碍需求在两年后出现时,这段只认识 x 和 y 的代码根本不知道段落从哪里开始
在 Delphi 中构建 HotPDF 布局树
HotPDF 用 HPDFLayoutDOM 单元里的声明式布局树同时回应这两个问题。THPDFDOMDocument 持有小节;每个 THPDFDOMSection 带有页面尺寸、页边距、可选的页眉页脚,以及一个 Body 堆栈,你往里面添加文本、标题、间隔、列表、图片、容器和表格。树里没有任何东西携带 y 坐标。THPDFDOMRenderer 负责测量整棵树、决定分页点、在每页上绘制页眉页脚,而且由于 GenerateStructure 默认为 True,它还会顺手写出结构树
树中的所有权是严格的:文档拥有小节,小节拥有正文、页眉和页脚,堆栈、容器和表格拥有各自的子项,所以 Section.Body.Add(Table) 一调用,表格就永久交了出去。一个挂到两个父节点下的组件会被按不同约束测量两次,并在拆除时释放两次。签名栏这类重复部件因此要么来自 Clone、SetHeaderClone / SetFooterClone,要么来自用 RegisterComponent 注册的工厂,此后每次 CreateComponent('signature') 都返回一个全新实例
uses
SysUtils, HPDFDoc, HPDFLayoutDOM;
type
TAssetRow = record // 你自己的数据类型
Name, ServiceDate, Status: WideString;
end;
function BuildMaintenanceReport(const Assets: array of TAssetRow): THPDFDOMDocument;
var
Doc: THPDFDOMDocument;
Section: THPDFDOMSection;
Heading: THPDFDOMText;
Table: THPDFDOMTable;
Row: THPDFDOMTableRow;
I: Integer;
begin
Doc := THPDFDOMDocument.Create; // 默认 GenerateStructure = True、Language = 'en-US'
try
Section := Doc.AddSection; // 默认 A4 纵向,页边距 36 pt
Section.MarginLeft := 56;
Section.MarginRight := 56;
Section.Style.FontName := 'Helvetica';
Section.Style.FontSize := 10;
Section.Style.LineHeight := 13;
Section.Body.Style.Spacing := 6; // 正文子项之间的间距
Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');
Heading := Section.Body.AddHeading('Annual maintenance report', 1);
Heading.Style.FontSize := 18;
Heading.Style.LineHeight := 22; // LineHeight 不跟随 FontSize
Section.Body.AddText('Every asset inspected during the reporting ' +
'period is listed below, grouped by site.');
Table := THPDFDOMTable.Create('assets'); // 默认 RepeatHeaders = True
Table.AddColumn(3); // 权重,不是以磅计的宽度
Table.AddColumn(1);
Table.AddColumn(1);
Row := Table.AddRow(18, True); // 表头行必须排在最前
Row[0].Text := 'Asset';
Row[1].Text := 'Last service';
Row[2].Text := 'Status';
for I := 0 to High(Assets) do
begin
Row := Table.AddRow(16);
Row[0].Text := Assets[I].Name;
Row[1].Text := Assets[I].ServiceDate;
Row[2].Text := Assets[I].Status;
end;
Section.Body.Add(Table); // 正文从此拥有这张表格
Result := Doc;
except
Doc.Free;
raise;
end;
end;
这份清单里有两个默认值容易让人踩坑。LineHeight 在样式链里没人设置时会解析成 12 磅,不管 FontSize 是多少,所以一个没有自带 LineHeight 的 18 磅标题会得到 12 磅的行高,直接压到下一行上。表格行的高度就等于传给 AddRow 的高度:单元格文本只排一行,所以请按你选的字体来定行高
Render 自己打开并关闭文档
THPDFDOMRenderer.Render(Doc, Pdf) 会在目标上调用 BeginDoc,渲染每个小节,返回之前调用 EndDoc。不要在外面再包一层自己的 BeginDoc / EndDoc。凡是必须在文档开始前设置的东西,先放到 THotPDF 实例上:FileName、Title,如果输出要声明 PDF/UA,还有 PDFUACompliance。结构生成打开时,Render 还会顺带打开 EnableTaggedPDF,并在你留空的情况下把 Doc.Language 复制到 Pdf.Lang
var
Doc: THPDFDOMDocument;
Pdf: THotPDF;
Renderer: THPDFDOMRenderer;
Stats: THPDFDOMRenderStatistics;
begin
Doc := BuildMaintenanceReport(Assets);
Pdf := THotPDF.Create(nil);
Renderer := THPDFDOMRenderer.Create;
try
Pdf.FileName := 'maintenance-report.pdf';
Pdf.Title := 'Annual maintenance report';
Pdf.PDFUACompliance := True; // 同时启用图片替代文本检查
// 这里没有 BeginDoc / EndDoc:开关文档由 Render 负责
Stats := Renderer.Render(Doc, Pdf);
Writeln(Format('%d page(s), %d placement(s), %d split(s)',
[Stats.PageCount, Stats.PlacementCount, Stats.SplitCount]));
Writeln(Format('structure elements=%d marked content=%d artifacts=%d',
[Stats.StructureElementCount, Stats.MarkedContentCount,
Stats.ArtifactCount]));
Writeln(Format('header draws=%d footer draws=%d deepest chain=%d',
[Stats.HeaderDrawCount, Stats.FooterDrawCount,
Stats.MaximumContinuationDepth]));
finally
Renderer.Free;
Doc.Free;
Pdf.Free;
end;
end;
每次运行都把统计记录写进日志,因为它能暴露从不抛异常的模板退化。模板改动后 SplitCount 骤升,通常意味着某个组件的测量高度超出了它原来放得下的空间。MaximumContinuationDepth 一路爬升,则指向某个 Split 每页推进太少的组件。ArtifactCount 涵盖页面页眉页脚、表格默认 0.5 磅边框这类装饰边框以及重复的表头行,所以请拿同一模板的多次运行互相比较,而不是去对手工算出来的目标值
长表格如何在分页时不把自己在每一页上复制一遍?
渲染器只拆分真正跨页面的那部分。朴素的树分页办法是把放不下的内容克隆一份带到下一页;对一张一万行的表格,这意味着每页克隆一次剩余行,把线性工作量变成平方级。HotPDF 按索引遍历正文子项,从不克隆整个小节或正文。跨页的嵌套堆栈或容器只克隆受影响的子树,两类重量级的叶子携带的是游标而不是拷贝
续排段落是对原文的引用加上它还欠着的字符区间,并且复用按同一宽度早已算好的折行。续排表格是对原表格的引用加上还没放置的行片段。一个 300 行的段落无论断一次还是断五次,成本都一样
放置本身走的是公开的 THotPDF.PlaceLayoutElement。它拿剩余正文高度去测量元素,放得下就整块绘制,放不下就要求它 Split,重测已放置的那一半,画出来,再把剩余部分作为溢出对象返回,由渲染器带到一个新页上。Measure 绝不能画任何东西;一次放置可能触发多次测量。DOM 渲染器在这条例程之上再叠加页面装饰元素、子项间距和新页决策
为什么一行表头能让整个渲染停下来?
重复表头带着两条规则,都是为了不让报表产出没有数据的页面。表头行必须构成最前面的连续段:在正文行之后再调 AddRow(Height, True) 会抛出 "Table header rows must precede body rows" 的 EInvalidOpException。表格的第一次拆分必须装下所有表头行再加至少一行正文。如果一张表格会让表头孤零零地挂在页尾,它就整体挪到下一页去
第二条规则有一道硬边界。如果连空页面都装不下表头行加一行正文,那就不存在能让这张表格起跑的页面,Render 会带上组件路径抛出 "Layout component ... cannot fit an empty body page",比如 Sections[0]/Body/Items[2]/assets。这正是值得要的行为。一个指望下一页会更宽敞而不断加页的排版引擎,会把一个超大的表头变成写满磁盘的死循环
自定义组件得到同样的保护。继承 THPDFDOMComponent,实现 Clone、Measure、Draw 和 Split,渲染器会统计每个正文子项产出了多少个续接段。超过 THPDFDOMRenderer.MaximumContinuationDepth(默认 100,000)就停止渲染,报 "exceeded the continuation depth limit"。一个不断返回等价尾部、永远不前进的 Split 会带着组件路径失败,而不是跑到磁盘写满为止
在续接页上,表头行在一个 /Artifact 标记内容序列里重绘,结构树里原始的 TR 仍然只有一份。文本提取因此不会在数据行之间插进一行重复表头,辅助技术也不会在表格中间把列标题再念一遍。每个表头单元格都打上 TH 标签,带 /Scope /Column 属性
一个逻辑段落,多个页面片段
被拆分的段落仍是一个 P 结构元素。每个可见片段在自己所在页上开一个新的标记内容序列,HotPDF 向该元素的 /K 数组追加一个标记内容引用字典 << /Type /MCR /Pg page /MCID n >>,并把 MCID 登记进该页的 ParentTree 条目,回指同一个元素。这正是 ISO 32000-1 §14.7.4 为跨页内容描述的安排,也是标签树视图能把两页上的碎片显示成一个段落的原因
语义身份是续接副本与你自己的克隆行为不同的原因。调用 Clone 意味着“全新的逻辑内容”,结果在绘制时会得到新的结构元素。分页期间产生的副本继承的是它们所延续组件的身份,所以一个跨三页的堆栈仍只产出一个 Div,跨两页的列表仍只产出一个 L。页面的页眉页脚走另一条路:在每一页上都包装成 /Artifact << /Type /Pagination /Subtype /Header >>(或 /Footer),从不进入结构树
渲染树的同时检查结构规则
GenerateStructure 打开时,渲染器会当场拒绝那些日后通不过 PDF/UA 校验的结构。第一个标题必须是 H1,后续标题不允许跳级,所以 H1 后面直接来一个 H3 会抛出 "Semantic heading levels cannot skip an intermediate level"。LI 需要 L 父节点,Lbl 和 LBody 需要 LI,TR 需要表格或行组,TH / TD 需要 TR。目标设置了 PDFUACompliance 时,没有替代文本的 Figure 同样会被拒绝。每条违例都会以异常终止 Render
var
List: THPDFDOMList;
Bmp: TBitmap; // Vcl.Graphics
begin
Section.Body.AddHeading('Findings', 2); // 前面已有 H1,所以 H2 合法
List := THPDFDOMList.Create('Decimal'); // 打上 L 标签,ListNumbering /Decimal
List.AddItem('1.', 'Replace the intake filter on pump P-14');
List.AddItem('2.', 'Re-torque the flange bolts on line 3');
Section.Body.Add(List); // AddItem 构建 LI、Lbl 和 LBody
Bmp := TBitmap.Create;
try
Bmp.LoadFromFile('site-plan.bmp');
// 图片会复制图形;PDFUACompliance 下空替代文本无法通过
Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
'Site plan of plant 3 with the inspected pumps circled'));
finally
Bmp.Free;
end;
end;
渲染期间检查正是这些规则的正确时机,原因就在时序。文件已经落盘才报告缺替代文本的校验器,只能告诉你一万份对账单得重新生成;而 Render 期间抛出的异常,会在产生问题的记录仍在作用域内时点名是哪条规则失败。正式的合规校验仍然应该保留在流水线里,而且由于 Render 返回后文档对象依旧可读,这一步可以立即执行。PDF/A、PDF/X 和 PDF/UA 校验 讲的就是这一步,结构顺序与文本提取 则说明标签树如何决定提取工具读到什么
什么时候继续手工绘图
布局树画在与直接 API 相同的 THPDFPage 对象上。由于 Render 从 BeginDoc 到 EndDoc 全程持有文档,签名图片这类手工定位的图形应当放进树里:自定义组件的 Draw 会拿到页面及其边界,可以在里面调用普通的页面方法。关页仍然由 AddPage 和 EndDoc 负责,所以在 THotPDF 实例上设置 ImmediateFlushLayout 后,完成的页面随渲染即写即出,渲染器手里不攒已完成的页面;内存占用就取决于打开中的续接段、字体资源和文档的对象图
DOM 文本组件按每字符 0.55 × 字号的估计平均步进来折行,并给每行套上解析后的 LineHeight。这让测量足够便宜且在每台机器上一致,对数据驱动的报表绰绰有余。宽字形文本,比如全大写、加粗串或 CJK,排出来会比估计值宽,所以这些列宽要留余量,并用最长的真实字符串试排一次。要求精确字形度量、一行内混排多种字体或两端对齐的排版页面,更适合走直接文本 API;文本两端对齐 走的就是那条路,而如果痛的只有表格分页,在 PDF 中生成表格 是更小的改动
布局树、它的渲染器、这里讲到的打标签以及直接绘图 API 都封装在同一个适用于 Delphi 和 C++Builder 的组件里;各版本与完整功能列表见 HotPDF Delphi PDF 组件页面