技术文章

在 Delphi 中使用 PDFium QuadPoints 实现文本标记注释

刚被 FPDFPage_CreateAnnot 返回的高亮注释,FPDFAnnot_CountAttachmentPoints 报告为 0,而对它调用 FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad),无论传什么坐标都返回 0。坐标不是问题。索引 0 的意思是“替换已有的 0 号四边形”,而新注释根本没有任何四边形;真正创建槽位的调用是 FPDFAnnot_AppendAttachmentPoints

道理一段话就能讲完,却极容易在上面耗掉几个小时,因为面对 false 返回值,人的第一反应是怀疑几何数据。有人调换角点顺序,有人翻转 Y 轴,有人来回转换设备空间。这些全都改变不了结果。下文将覆盖:按 ISO 32000-1 四边形必须包含什么、如何通过组件 API 和原始 C 函数写入它们、跨行选区,以及一个在 Delphi、Free Pascal 和 C++Builder 之间表现不同的索引陷阱。它是读取与审查现有注释一文在创建侧的姊妹篇,后者沿相同的结构反方向走了一遍

QuadPoints 在 ISO 32000-1 §12.5.6.10 中的含义

QuadPoints 是四种文本标记子类型(Highlight、Underline、Squiggly、StrikeOut)的必备条目:一个由 8×n 个数字组成的数组,在默认用户空间中给出 n 个四边形,每个四边形围住注释所覆盖文本中的一个词或一组连续的词。注释仍然带有每个注释都需要的 Rect,但对标记子类型来说,四边形指明哪些字形被标记,Rect 只负责框住它们。用四边形而不是矩形,是因为文本在页面上可能被旋转或剪切,所以每个角都作为独立的点存储:x1 y1 x2 y2 x3 y3 x4 y4

角点顺序是规范文本与流通文件分道扬镳的地方。§12.5.6.10 说四个顶点按逆时针顺序给出,并补充说明文本相对于从 (x1, y1) 到 (x2, y2) 的边定向。Acrobat 以及一长串为读取 Acrobat 输出而打造的工具用的却是 Z 字形:点 1 左上、点 2 右上、点 3 左下、点 4 右下。这种排布仍满足那句定向说明——1–2 边沿文本顶部延伸——但它并不是绕形状的逆时针行走。请写 Z 序。字面意义上的逆时针序列(左上、左下、右下、右上)在纸面上说得通,但按 Z 字形解读这些点的阅读器会得到左上、左下、右上、右下,这些边交叉成一个蝴蝶结

所有坐标都是以磅为单位的页面坐标,原点在页面左下角,Y 向上增长。因此靠近 A4 页面顶部的一行文字,Y 值大约在 700 到 800 之间,且其顶边的 Y 更大。规范还规定两者同时存在时,外观流(AP)优先于 QuadPoints,所以四边形对那些自行生成标记外观的查看器最重要

PDF 页面坐标下的 QuadPoints 几何图:展示 PDFium 文本标记批注使用的 Z 序角点编号 TL、TR、BL、BR
PDFium 要求 QuadPoints 按 Z 顺序排列:左上到右上、再左下到右下,使用 Y 向上增长的页面坐标

为什么 FPDFAnnot_SetAttachmentPoints 会返回 false?

FPDFAnnot_SetAttachmentPoints 在新注释上返回 false,是因为它只替换已经存在的四边形。PDFium 头文件把约定写得直白:quad_index “needs to be within the result of FPDFAnnot_CountAttachmentPoints()”。经 FPDFPage_CreateAnnot 创建的每个注释计数都从零开始,所以根本没有可替换的索引 0。FPDFAnnot_AppendAttachmentPoints 增加一个槽位并把计数加一;此后索引 0 才存在,Set 才会接受它。这两个函数在 PDFium 头文件中都标记为 experimental,而且当新四边形比旧四边形延伸得更远时,两者都会扩展现有外观流的包围盒

PDFium Component 在 PDFium.pas 中暴露了所有 FPDFAnnot_* 入口点,FS_QUADPOINTSF 记录和 size_t 别名则在 FPdfView.pas 中。如果你自己持有注释句柄,每次写入前都先按计数分流:

uses
  SysUtils, PDFium, FPdfView;

// 在活动页注释 AnnotIndex 上写入 QuadIndex 处的四边形:
// 槽位存在则替换,否则追加一个新槽位
procedure WriteQuad(Pdf: TPdf; AnnotIndex: Integer; QuadIndex: size_t;
  var Quad: FS_QUADPOINTSF);
var
  Annot: FPDF_ANNOTATION;
  Count: size_t;
  Ok: Boolean;
begin
  Annot := FPDFPage_GetAnnot(Pdf.Page, AnnotIndex);
  if Annot = nil then
    raise Exception.CreateFmt('No annotation at index %d', [AnnotIndex]);
  try
    Count := FPDFAnnot_CountAttachmentPoints(Annot);
    if QuadIndex < Count then
      Ok := FPDFAnnot_SetAttachmentPoints(Annot, QuadIndex, Quad) <> 0
    else
      Ok := FPDFAnnot_AppendAttachmentPoints(Annot, Quad) <> 0;
    if not Ok then
      raise Exception.Create('PDFium rejected the quad');
  finally
    FPDFPage_CloseAnnot(Annot);
  end;
end;

同一个函数族里还埋着第二个陷阱。FPDFAnnot_CountAttachmentPoints 返回 size_t,是无符号类型,所以对一个没有任何四边形的注释写惯用的 for I := 0 to Count - 1,会在无符号算术下计算 0 − 1 并回绕到最大可能值。进入任何四边形循环之前先测 Count > 0,或者先转成有符号类型。其他工具产出的标记几乎总是至少带一个四边形;刚创建的注释则一个都没有

使用 TPdf.CreateAnnotation 创建高亮

走组件 API 就永远不必在 Append 和 Set 之间做选择。TPdf.CreateAnnotation 和 TPdf.SetAnnotation 都会检查注释已持有多少个四边形,替换已存在的槽位、追加其余的,于是创建路径追加、更新路径替换。你要提供的是一个 TPdfAnnotation 记录,内含 Subtype、颜色、四边形和一个 Rectangle

这里有两个记录细节要紧。用 Default(TPdfAnnotation) 初始化记录。这个记录持有字符串和动态数组,对已经携带字符串的记录上 FillChar 就是纯粹泄漏,所以对你复用的每个记录,Default 都是更稳妥的习惯。还有,务必填 Rectangle:组件在每次创建和更新时都把它写成注释的 Rect,全零记录即使四边形正确,也会产出 [0 0 0 0] 的 Rect。CreateAnnotation 作用于活动页——新页面由 AddPage 设置,既有文档由 PageNumber 设置;当 PDFium 无法创建所请求的子类型时,它会抛出 'Unsupported annotation subtype'

var
  Pdf: TPdf;
  A: TPdfAnnotation;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.CreateDocument;
    Pdf.AddPage(0, 595, 842);                // A4,成为活动页

    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;                     // alpha 随颜色一并传入
    A.HasAttachmentPoints := True;
    A.AttachmentPoints[1].X := 50;  A.AttachmentPoints[1].Y := 700;  // 左上
    A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700;  // 右上
    A.AttachmentPoints[3].X := 50;  A.AttachmentPoints[3].Y := 680;  // 左下
    A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680;  // 右下
    A.Rectangle.Left := 50;   A.Rectangle.Top := 700;                // 包住四边形
    A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
    A.ContentsText := 'Highlighted region';
    Pdf.CreateAnnotation(A);

    Pdf.SaveAs('highlighted.pdf');
  finally
    Pdf.Free;
  end;
end;

换一种装饰只需改一行。anUnderline、anStrikeout 和 anSquiggly 接受完全相同的记录,四边形等一切照旧;ISO 32000-1 把四种放在一起描述,差别只在四边形区域的绘制方式。该家族之外的子类型,如 anSquare、anCircle 和 anText,仅凭 Rectangle 定位;对这些,让 HasAttachmentPoints 保持 False、AttachmentPointSets 留空即可,不会写出任何四边形

跨行选区:一个注释,多个四边形

换行折成三行的选区需要三个四边形,每行一个,因为一个横跨三行的四边形会把第一行的右端和第三行的左端也一起涂上。TPdfAnnotation 用 AttachmentPointSets 携带所有四边形——一个 TQuadrilateralPoint 动态数组;单一 AttachmentPoints 字段保留为第一个条目的别名。当 AttachmentPointSets 非空时,CreateAnnotation 依序写出它的全部条目,单一字段被忽略

也可以每行建一个注释。渲染效果一样,但审查者会看到三条评论、三个弹窗、三个要删的条目,而它们本是一次高亮。把各行放进同一个注释。几何数据从搜索里拿很方便,因为 TPdf.CreateDocumentSearch 返回的每个匹配都带一个 Rectangles 数组,一行上一段文本一个矩形,且已经是页面坐标:

function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
  Result[1].X := R.Left;  Result[1].Y := R.Top;     // 左上
  Result[2].X := R.Right; Result[2].Y := R.Top;     // 右上
  Result[3].X := R.Left;  Result[3].Y := R.Bottom;  // 左下
  Result[4].X := R.Right; Result[4].Y := R.Bottom;  // 右下
end;

// 你自己的辅助函数,不属于库:各行矩形的并集
function UnionRect(const Rects: TPdfRectangles): TPdfRectangle;
var
  I: Integer;
begin
  Result := Rects[0];
  for I := 1 to High(Rects) do
  begin
    if Rects[I].Left < Result.Left then Result.Left := Rects[I].Left;
    if Rects[I].Right > Result.Right then Result.Right := Rects[I].Right;
    if Rects[I].Top > Result.Top then Result.Top := Rects[I].Top;
    if Rects[I].Bottom < Result.Bottom then Result.Bottom := Rects[I].Bottom;
  end;
end;

procedure HighlightMatches(Pdf: TPdf; const Needle: WString);
var
  Search: TPdfDocumentSearch;
  Match: TPdfDocumentSearchResult;
  Found: array of TPdfDocumentSearchResult;
  A: TPdfAnnotation;
  I, J: Integer;
begin
  // 先收集所有匹配,再动任何页面
  Search := Pdf.CreateDocumentSearch(Needle, [seWholeWord]);
  try
    while Search.Next(Match) do
      if Length(Match.Rectangles) > 0 then
      begin
        SetLength(Found, Length(Found) + 1);
        Found[High(Found)] := Match;
      end;
  finally
    Search.Free;
  end;

  for I := 0 to High(Found) do
  begin
    Pdf.PageNumber := Found[I].PageNumber;
    A := Default(TPdfAnnotation);
    A.Subtype := anHighlight;
    A.HasColor := True;
    A.Color := clYellow;
    A.ColorAlpha := $80;
    SetLength(A.AttachmentPointSets, Length(Found[I].Rectangles));
    for J := 0 to High(Found[I].Rectangles) do
      A.AttachmentPointSets[J] := QuadFromRect(Found[I].Rectangles[J]);
    A.Rectangle := UnionRect(Found[I].Rectangles);
    A.ContentsText := Found[I].Text;
    Pdf.CreateAnnotation(A);
  end;
end;

搜索矩形是轴对齐的,每个只有四个数字,所以旋转文本上得到的四边形覆盖的是该段文本的包围盒,不跟随倾斜。对水平直排文本——被高亮的大多数情形——包围盒与字形区域重合。如果你需要的是逐字符几何,PDFium Component 文本提取指南覆盖了 CharacterRectangle 及相关文本页调用,文本测量与自动换行一文则演示了如何为将要生成的文本计算行范围

多行高亮:由三个四边形逐个追加到 Delphi 中创建的单个 PDFium 批注构成
跨三行的选区变成一个携带三个四边形的注释,通过 AppendAttachmentPoints 调用构建并增加槽位数

编辑既有标记注释走 Pdf.Annotation[Index] := A,它调用 SetAnnotation;记录中的子类型必须与已存储的一致,否则调用抛出 'Incorrect annotation subtype'。四边形按索引逐一重写,AttachmentPointSets 里多余的条目会被追加。PDFium 没有暴露删除单个四边形的调用,所以从三个四边形缩到两个,第三个仍留在文件里。要收缩高亮,用 DeleteAnnotation 删掉再用更短的数组重建

AttachmentPoints 从 1 数起,C++ 除外

TQuadrilateralPoint 声明为 array [1..4] of TPdfPoint,编号与规范中的角点编号一致:元素 1 是 (x1, y1),元素 4 是 (x4, y4)。凭记忆写代码、带着从零起步的习惯,就会以编译器不一定能抓住的方式出错。像 for I := 0 to 3 do A.AttachmentPoints[I] := ... 这样的循环,在 Delphi 和 Free Pascal 里都能编译,因为索引要到运行时才确定。范围检查关闭时——Delphi 工程默认如此——索引 0 的写操作落在数组前面紧邻的字节上,进入前面的记录字段,四边形本身则保有一个零角点。什么都不抛

常量索引是另一回事。编译器可以在任何东西运行之前把它与声明的边界比较,fpc 就会以范围错误直接拒绝字面的 AttachmentPoints[0]。溜过去的是计算索引那种形式。在信任注释代码之前,用 Delphi 的 {$R+} 或走 fpc 至少构建一次;范围检查开启时,上面的运行时循环会在索引 0 处抛出 ERangeError

C++Builder 把规则反过来。生成的 PDFium.hpp 把 TQuadrilateralPoint 声明为 System::StaticArray<TPdfPoint, 4>,而 C++ 静态数组从零起步,不管 Pascal 下界是什么。因此在 C++ 里角点是 AttachmentPoints[0] 到 AttachmentPoints[3],仍是 Z 序。逐行照搬 Delphi 示例代码会保住 1 到 4 的索引,每个角点错位一格,最后一个还写到数组末尾之外

把四边形读回来

验证标记注释是否落对了位置,最快的办法是用同一个 API 读回来。Pdf.Annotation[Index] 会把注释上存储的每个四边形填进 AttachmentPointSets,只要有一个,HasAttachmentPoints 就是 True:

var
  I, Q: Integer;
  B: TPdfAnnotation;
begin
  Pdf.PageNumber := 1;
  for I := 0 to Pdf.AnnotationCount - 1 do
  begin
    B := Pdf.Annotation[I];
    if B.Subtype in [anHighlight, anUnderline, anStrikeout, anSquiggly] then
      for Q := 0 to High(B.AttachmentPointSets) do
        Writeln(Format('annot %d quad %d: TL (%.1f, %.1f)  BR (%.1f, %.1f)',
          [I, Q,
           B.AttachmentPointSets[Q][1].X, B.AttachmentPointSets[Q][1].Y,
           B.AttachmentPointSets[Q][4].X, B.AttachmentPointSets[Q][4].Y]));
  end;
end;

对前面创建的那个高亮,预期输出是 annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0);左上的 Y 低于右下的 Y,说明角点上下颠倒了。与其他工具交换标记时,四边形也随注释一起走:XFDF 里的 coords 属性存放所有四边形,每个四边形八个数字,见XFDF 导出与导入一文。之后在第二个查看器里打开保存的文件,确认颜色落在字形上而不是旁边——因为从 QuadPoints 自建外观的查看器,正是会暴露错误角点顺序的那一个

本文用到的注释记录、多四边形数组和按计数感知的写入器,都随面向 Delphi、C++Builder 和 Lazarus 的 PDFium Component 交付;完整的注释 API 参考就摆在这些示例所依赖的文本搜索与提取调用旁边