技术文章

在 Delphi 中把 PDF 内容重排为响应式 HTML

一份从文字处理器导出、导出时没勾"带标签 PDF"的合同,在屏幕上照样显得有结构:24 磅的粗体标题、编号条款、带横线的收费表。把它转成可重排 HTML,收费表回来了——是一个正经的 <table>;标题却是一个 <p>,与脚注地位完全相同。这个输出是对的。ISO 32000-1 §14.8 给 PDF 的唯一一处"这段文本是标题"的声明位置就是结构树,而无标签文件没有结构树。字号和加粗是排版选择,一个把每行大号粗体都变成 <h1> 的转换器,同样会把引言金句、表格合计和信头里的公司名一并升格

所以任何 PDF 转 HTML 管线都值得问一句:输出里的每个标题、列表项和表格从哪来,手机排版、屏幕阅读器或搜索索引各能信任它到什么程度。标题和表格给出的答案不同。导出这一步还要自己拿主意:换行、字符编码和内存

Delphi 中 PDFium Component 重排的管线图:GetStructuredText 把带标签结构树或版面阅读顺序喂给 BuildReflowDocument,再经自包含的 ToHtml 导出
重排模型里的每个节点都能回溯到同一个结构化文本层,无论其角色是结构树声明的,还是这个块退回到了普通版面顺序

标题和列表从哪来

PDFium Component 用 TPdf.BuildReflowDocument 构建重排模型,这个方法从 GetStructuredText 取每一个词、块和语义提示——就是 结构化文本块与阅读顺序讲的那个结构化文本层。它背后没有第二个解析器,也没有第二个文本抽取器。对请求范围内的每一页,它按物理版面顺序收集块。GetStructuredText 已经按重叠面积把每个块与页面的带标签内容配对,BuildReflowDocument 把找到的角色复制到块上:H 到 H6 成为带级别的标题,LI、Lbl 和 LBody 成为列表项,Figure 成为文本取自替代描述的图形,Caption 成为图注

由此得到两个结论,都很容易观察到。即使文件带标签,块顺序也永远跟随页面版面——标签决定一个块是什么,几何决定它去哪里。而在没有标签的页面上,每个块都是段落。标题和列表绝不靠字号猜测

每个节点带一个 TPdfReadingOrderSource 类型的 Source 字段:角色来自结构树是 rosStructure,只来自版面是 rosHeuristic。导出的 HTML 在每个元素上重复它,写作 data-source="structure" 或 data-source="inferred";文档级 TPdfReflowDocument.Source 只有范围内每一页都带标签时才是 rosStructure。表格永远是 rosHeuristic,因为它们来自几何检测而非 Table 标签。如果下游步骤把标题当导航地标用,先检查这个字段——带标签的文档给你的是作者亲自选的地标

扁平节点数组,而不是对象树

TPdfReflowDocument.Nodes 是前序遍历压平的树:一个 TPdfReflowNode 记录的动态数组,每个记录带 ParentIndex 和 Depth。页面节点在深度 0、父索引 -1。段落、标题、图形、图注、列表和表格挂在页下深度 1,列表项在其列表下深度 2,表格单元格在行下深度 3。连续的列表项共享同一个列表节点;中间插入任何其他块或表格,就另起一个列表

扁平布局是可移植性决定。包含自身动态数组的递归记录在 Delphi、C++Builder 和 Free Pascal 下都能编译,但三者在跨包或 DLL 边界时对递归托管类型的处理各不相同。普通记录的扁平数组在三者中行为一致,而且可以用一个 for 循环、不带递归地流式处理

uses
  SysUtils, PDFium;

var
  Pdf: TPdf;
  Options: TPdfReflowOptions;
  Doc: TPdfReflowDocument;
  Node: TPdfReflowNode;
  I: Integer;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'contract.pdf';
    Pdf.LoadDocument;

    Options := TPdfReflowOptions.Default;   // 全部页面、开表格、开 CSS
    Doc := Pdf.BuildReflowDocument(Options);

    for I := 0 to High(Doc.Nodes) do
    begin
      Node := Doc.Nodes[I];
      case Node.Kind of
        prnkHeading:
          Writeln(Format('%sH%d [%s] %s', [StringOfChar(' ', Node.Depth * 2),
            Node.HeadingLevel,
            BoolToStr(Node.Source = rosStructure, True), Node.Text]));
        prnkTable:
          // 表格节点上 RowSpan/ColumnSpan 存的是表格的行数与列数
          Writeln(Format('%stable %dx%d, page %d, confidence %.2f',
            [StringOfChar(' ', Node.Depth * 2), Node.RowSpan, Node.ColumnSpan,
             Node.PageNumber, Node.Confidence]));
      end;
    end;

    Writeln(Format('%d node(s), %d table(s), %d character(s), pages %d-%d',
      [Length(Doc.Nodes), Doc.TableCount, Doc.CharacterCount,
       Doc.FirstPage, Doc.LastPage]));
  finally
    Pdf.Free;
  end;
end;

对开头那份无标签合同,这个循环一行 H 都不打印,每张检出的收费表打一行。对同一份文档的带标签副本运行,标题带着旁边的 True 出现。选项里的 FirstPage 和 LastPage 默认 0,表示文档第一页和最后一页;超出页数的范围在任何页面被读取之前抛 EPdfError

表格文本为什么不会出现两次?

表格检测在结构化文本收集完之后对每页运行,这意味着表格里的词存在两份:一份作为文本块,一份作为单元格。两者都输出,HTML 里每张表格后面就跟着一份以松散段落形式重复的自身内容——"把表格加到文本里"的天真合并产出的正是这个

模型用几何规则化解它。外接框至少有一半落在检出表格边界内的文本块被丢弃,表格节点取而代之。表格随后与剩下的块按垂直位置交织(页面上更高者在前,顶边相差不到半磅时以从左到右为次序),所以表格落在上方段落与下方段落之间,而不是被追加到页面末尾

Delphi 重排中 PDFium Component 表格检测几何规则的图示:覆盖文本块至少一半的表格将其替换,单元格文本绝不出现两次
检出表格覆盖文本块至少一半时,表格节点替换该块,单元格文本恰好出现一次

半面积阈值有一条可见的边界。横跨表格边界、大部分在外的块原样幸存,所以偶尔会有一行文字同时出现在最后一行和紧随其后的段落里。宁要这一侧的错误。把阈值压到足以移除所有重叠块,也会删掉只是碰到表格外接框的正文;一行重复远比一句缺失容易察觉、容易原谅

检出的表格还带置信度,两种检测策略落在不同的区间。靠边线找到的表格得分 0.88 到 1.0,取决于多少单元格装着文字;纯靠留白对齐推断的表格得分 0.58 到 0.88。表格节点的 Confidence 存这个分数,每个单元格节点重复它,HTML 把它写成 <table> 元素上的 data-confidence。低于 TableOptions.MinConfidence(默认 0.5)的表格根本不会创建,被拒的表格其文字就地留在模型里当普通段落

对搜索索引或移动阅读视图,错误的表格代价很小、检对的表格收益很大,保持默认即可。档案转换则相反——围绕两栏地址块凭空造出的网格比没有网格更糟——把检测限制在带边线的表格:

Options := TPdfReflowOptions.Default;
Options.DetectTables := True;
Options.TableOptions.DetectWhitespaceTables := False; // 只要带边线的表格
Options.TableOptions.MinConfidence := 0.9;            // 连稀疏的带线网格也丢掉
Options.TableOptions.MaxTables := 200;                // 全文档上限
Options.TableOptions.MaxCells := 50000;               // 全文档上限

Doc := Pdf.BuildReflowDocument(Options);
if Doc.TableCount = 0 then
  Writeln('No ruled tables; all page text is emitted as paragraphs');

重排构建内部,MaxTables 和 MaxCells 按整个页面范围计数、不是按页,所以每页一张带线表格的 300 页对账单需要 MaxTables 至少 300,否则构建在第一张超限表格处抛 EPdfError 停下。默认是 1000 张表格、100000 个单元格

检测本身的内容——画成边线的细实心矩形、跨页延续的表格——见 表格检测与抽取

导出不依赖任何外部资源的 HTML

TPdfReflowDocument.ToHtml 遍历已构建好的模型,不再回头碰 PDFium,同一模型导出两次得到同一字符串。设了 FullDocument(默认)时结果是一整页:doctype、<meta charset="utf-8">、viewport meta 标签、取自文档 Title 条目的 <title>(空则是"PDF document"),以及来自文档语言的 lang 属性。关掉 FullDocument 得到单个 <div class="pdf-reflow"> 片段,丢进你自己的模板即可

IncludeCss 的可选样式表是一段内联 <style>:72rem 的阅读栏,IncludePageSections 打开时每页一张白色卡片,表格边框合并,以及一条 40rem 以下的媒体查询去掉卡片内边距、缩小表格文字。没有脚本、没有网络字体、没有任何外部 URL——文件因此能待在邮件里、CHM 风格的帮助查看器里或沙箱化的浏览器控件里。1 到 6 之外的标题级别写成 h2,表头单元格成为 th,RowSpan 或 ColumnSpan 大于 1 的单元格带上 rowspan 和 colspan。打开 IncludeGeometry 会附加 PDF 磅值计的 data-left、data-top、data-right 和 data-bottom,把搜索命中高亮回渲染页面上时很趁手

PreserveLineBreaks 值得深思熟虑。PDF 段落里的换行是为某一条固定栏宽做出的排版决定;把它留在 360 像素的屏幕上,每行折两次——那种参差感正是重排要消灭的东西。散文请保持关闭(默认)。换行自带含义的文档——地址、诗行、代码清单——再打开,此时写出的是 <br> 而不是空格

长文档下,把整页攒成一个 WString 再编码会把内存峰值翻倍。WriteHtml 把同样的标记流式写进 TPdfReportWriter,以 ASCII 写出、每个非 ASCII 字符写成数字字符引用,所以无论接收方怎么猜编码,字节都有效:

uses
  Classes, SysUtils, PDFium, FPdfAsync, FPdfReport;

procedure ExportReflowHtml(Pdf: TPdf; const FileName: string;
  const Token: IPdfCancellationToken);
var
  Options: TPdfReflowOptions;
  Doc: TPdfReflowDocument;
  Limits: TPdfReportLimits;
  Stream: TFileStream;
  Writer: TPdfReportWriter;
begin
  Options := TPdfReflowOptions.Default;
  Options.MaxNodes := 500000;
  Options.MaxCharacters := 20000000;
  Doc := Pdf.BuildReflowDocument(Options, Token);   // 页面状态事后会恢复

  Limits := TPdfReportLimits.Default;
  Limits.MaxCharacters := 64 * 1024 * 1024;  // 输出字节上限,最大 64 MiB
  Limits.MaxItems := Options.MaxNodes;       // 每节点一项,最大 1048576

  Stream := TFileStream.Create(FileName, fmCreate);
  try
    Writer := TPdfReportWriter.Create(Limits, Stream);  // 流仍归调用者所有
    try
      Doc.WriteHtml(Writer);
    finally
      Writer.Free;
    end;
  finally
    Stream.Free;
  end;
end;

WriteHtml 查的比 ToHtml 多。它拒绝节点数超过 Options.MaxNodes 的模型,对写出的文字执行 Options.MaxCharacters,把嵌套限制在 MaxDepth 参数内(默认 64),并核验每个 ParentIndex 都指向更早的节点。最后这条在你的代码在导出前过滤或改写 Nodes 时很要紧:带前向父索引的改后数组抛 EPdfReportLimit,而不是产出标签错配的标记

预算、取消与页面状态

PDF 是不受信任的输入,一份畸形或敌意的文件可以声明几千页的小字。BuildReflowDocument 在每个节点加入之前检查字符、节点、表格和单元格预算,超限的文件以 EPdfError 和一条点名预算的消息停下(比如"Reflow node budget exceeded"),内存占用始终有界。MaxCharacters 和 MaxNodes 都必须为正;默认 1000 万字符、100 万节点

可选的 IPdfCancellationToken 在每页之前、块与块之间、每张表格之前和每个表格行之前被检查。传入你窗体拥有的 TPdfCancellationTokenSource 的 Token,在按钮处理器里调 Cancel,构建在下一个检查点抛 EPdfOperationCancelled。请把它与 EPdfError 分开捕获,用户的取消不该被记成坏文件。无论构建以哪种异常收场,都不会返回半成品;失败若发生在 WriteHtml 内部靠后的位置,目标文件里是半页残缺内容,请在自己的异常处理器里删掉它

页面状态是 GUI 代码依赖的细节。构建靠移动 PageNumber 访问范围内每一页,一个 try/finally 在成功、预算失败和取消三种结局下都把调用者的页面放回去。用户正在读第 340 页时发起导出的查看器,导出返回时还在第 340 页

重排适合哪里

重排输出很适合当输入:搜索索引、无障碍阅读视图、手机展示、向 CMS 的内容迁移。它刻意放弃绝对定位、精确字体、矢量图形和页面几何——可选的 data-* 坐标除外。工作需要页面看起来一模一样时,渲染它;需要文字在别处可读时,重排它

因为标题和列表只来自标签,HTML 的质量跟着上游标记的质量走。通过 PDF/UA 结构树校验各项检查的文档产出带真实标题层级的模型,同一份带标签内容也驱动着 构建无障碍阅读器里的阅读功能

重排、结构化文本、表格抽取和渲染在 Delphi、C++Builder 和 Lazarus 里都作用于同一个 TPdf 对象;选项记录、异常和报告写手都记录在 PDFium Component for Delphi 产品页上