技术文章

在 Delphi 中用带标记输出实现声明式 PDF 排版

对一个从第 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') 都返回一个全新实例

HotPDF 声明式布局文档的归属树:小节、页眉、页脚和表格行各有唯一属主
布局树中每个节点都恰好有一个所有者,辅助方法返回新实例而非共享引用,重复出现的部件由注册工厂在每次调用时产出新组件
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 行的段落无论断一次还是断五次,成本都一样

条形图对比:HotPDF 中整子树克隆带来的二次方分页成本,与窄幅页面边界切分带来的平坦线性成本
每个跨页都克隆整个未放置子树会让多出的行变成平方级工作量;窄切分让长文本携带字符区间游标、表格携带行切片游标

放置本身走的是公开的 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),从不进入结构树

HotPDF 示意图:一个带标签段落保持为单个 PDF 结构元素,其两个页面片段携带各自的标记内容标识符,重绘的页眉被标记为 artifact
同一段落的分页片段通过其 K 数组收集的 Pg 与 MCID 对共享同一个结构元素,续页重绘的页眉以 artifact 身份随行而非作为内容

渲染树的同时检查结构规则

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 组件页面