技术文章

PDFlibPas MovePage:继承盒子何时共享实例

在 PDFlibPas(Delphi PDF 库)里,用 MovePage 移动的页面会得到它从旧 Pages 节点继承来的 MediaBox、CropBox 和 Resources 值的专属副本,而间接引用仍保持为引用。把旧 Pages 节点持有的对象原封不动交给被移动的页面是最顺手的实现,但那意味着之后对这一页的 SetPageBox 或 DrawText 会悄悄改写那个节点和每个仍在继承它的兄弟页面。同一条“复制而不共享”的规则还覆盖两条相关路径:多页共享的间接盒子上的 SetPageBox,以及在来源文档页面上物化继承值的 CopyPageRanges

这类别名问题的症状从不提对象身份。它们听起来像“我裁了第 7 页,第 8 到 12 页也跟着被裁了”,或者“我收窄 CropBox,MediaBox 跟着动了”,最迷惑的一个是“我把一页复制进新文档,原文件却变了”。什么都不崩溃,什么都不泄漏,保存的文件是完全合法的 PDF——只是带着一份没人要的几何

在一页上 SetPageBox 怎么会改到兄弟页面的尺寸?

当两个页面树条目指向同一个内存数组、而 SetPageBox 就地编辑其目标数组时就会发生:持有同一实例的任何页面或 Pages 节点都看到这次编辑。页面树编辑器里有三条代码路径能造出这种共享:

  • MovePage 在把页面从父节点摘下之前先物化可继承属性;如果附着的是祖先自己的对象而不是副本,被移动的页面和它昔日的兄弟们就会共享同一个盒子数组和 Resources 字典
  • 跟随间接引用并编辑被引用数组的盒子写入器,一次调用就能改写指向同一个 /MediaBox 11 0 R 对象的每一页,不管 MovePage 有没有参与过
  • CopyPageRanges 在把来源页克隆进目标文档之前在来源页上物化继承值;把 Pages 节点实例附着到来源页、再把 MediaBox 实例本身当作默认 CropBox,就把这一切拴在了一起
MovePage 别名陷阱示意图:被移动的页面与其昔日兄弟都持有祖先自己的 MediaBox 数组实例,SetPageBox 编辑一页却改了另一页的尺寸;PDFlibPas 的物化附着解码副本,编辑只影响你碰的那一页
两个页面树条目指向同一个内存数组,每次编辑都会落在每个持有者身上,而保存出的 PDF 全程合法

物化本身不是可选项。只带 /Resources 过去,移到不同父节点下的页面会悄悄继承那个父节点的尺寸和旋转,所以 MovePage 连 MediaBox、CropBox 和 Rotate 一起携带——这也是 CollateDocumentsEx 重排页面时依靠的行为。唯一的问题是这些值到达时是副本还是共享实例

直接值、间接引用与页面属性继承

正确复制一个继承来的页面属性,意味着直接值做副本、间接引用保持为引用,因为这是 ISO 32000-1 自己划下的界限。写在字典里的直接对象(如 [0 0 400 300])只属于那个字典。间接对象只定义一次(11 0 obj),引用写作 11 0 R,按设计就是共享的:ISO 32000-1 §7.3.10 让它可以从文件任何位置寻址,每个 11 0 R 都指同一个对象

页面属性继承(ISO 32000-1 §7.7.3.4)引入第三种情况。Resources、MediaBox、CropBox 和 Rotate 可以放在 Pages 节点上,作用于每个没有自定义的子孙页面。页面本身不持有值,而是顺着 /Parent 向上查。页面一换父节点,这条查找链就断了,所以 MovePage 和 BalancePageTree 都得先把生效值写到页面自己身上。问题只在怎么写

对象池为什么把错误藏了起来

在 PDFlibPas 里,每个解析或创建出来的 PDF 对象都归文档的 TPDFStructure 池所有,字典和数组存的只是指向表项的普通指针。TPDFDictionary.Add 只记下指针,别的什么都不做。于是把同一个实例挂进两个父容器,在运行时能检查的每一层上都合法:拆卸时不会双重释放,没有引用计数可出错,也没有异常。序列化同样宽容——每个容器把共享实例的当前值内联写出,任何编辑之前,输出与正确副本产出的逐字节相同

别名问题只有在有人就地修改共享实例时才浮出水面。SetPageBox 干的正是这个——隔着现有数组的矩形包装改它;在页面上绘图时注册字体或图像,也会这样改 Resources 字典。编辑悄无声息地落在所有持有该指针的其他容器里

PDFlibPas 如何复制而不共享

PDFlibPas 从两头处理这个问题:物化附着副本,盒子写入只编辑页面拥有的数组。每条规则各覆盖另一条管不到的情形

物化辅助函数 PLInheritPageAttributes 附着的是 Page.Owner.Decode(Value.Output) 而不是 Value 本身。经序列化器往返一次是个笨办法,却能精确地免费拿到 PDF 语义。直接数组或字典序列化成字面文本,解码成全新的独立实例。间接引用序列化成 11 0 R,解码成一个仍指向对象 11 的新引用对象,所以页面引用的还是共享对象,而不是收到一份内联副本。复制的深度恰好等于直接结构:复制字典内部经引用抵达的东西仍然共享,这正是文件格式的本意。BalancePageTree 对它重新挂父的每一页调用同一个辅助函数,所以在那里物化的页面同样拿到独立实例

PDFlibPas 的物化往返:PLInheritPageAttributes 附着 Page.Owner.Decode(Value.Output)——直接数组序列化成字面文本再解码成全新实例,间接的 11 0 R 序列化并解码成仍指向共享对象 11 的新引用
序列化再重解析免费拿到 PDF 对象语义:直接值复制,引用仍是引用,与 ISO 32000-1 的意图一致

只有复制还不够,因为引用的那一路仍指向共享对象。如果 SetPageBox 跟着引用去编辑对象 11,被移动的页面又会改到旧父节点和它的其他子节点。所以盒子写入器应用写时复制:只有页面自己的表项是直接数组时就地编辑,间接或缺失的盒子用新的直接数组替换。对象 11 对引用它的其他页面原封不动

PDFlibPas SetPageBox 的写时复制决策:页面自己的表项是直接数组时就地编辑,是间接引用或缺失时写入新的直接数组,共享对象 11 对引用它的其他页面保持原值
只要引用还指向共享对象,物化时复制就不够,所以盒子写入器只编辑页面拥有的东西
代码路径共享实例(陷阱)PDFlibPas
MovePage 物化页面持有祖先自己的直接实例页面持有解码副本;引用仍是引用
SetPageBox跟随引用编辑共享数组只编辑页面上的直接数组,否则写入新数组
CopyPageRanges 来源页共享 Pages 节点盒子;CropBox 就是 MediaBox 实例来源页上每个物化值都是副本
克隆页面资源时的默认盒子CropBox、BleedBox、TrimBox 和 ArtBox 共享一个数组每个默认盒子有自己的数组

最后一行是最微妙的一处。库为页面捕获或合并克隆页面资源时,会补上缺失的 CropBox、BleedBox、TrimBox 和 ArtBox 条目,而四个值若都从同一个数组实例填出,就埋下了一个别名,等着第一个编辑其中之一的人。这些默认盒子值怎么选是另一个话题,见PDFlibPas 的 TrimBox、BleedBox 与 CropBox 默认值指南

手工构造 PDF 复现 MovePage 别名

测试页面树编辑代码有没有别名,最快的办法是用 LoadFromString 加载一份手写的小 PDF,每个对象号都事先知道。下面的辅助函数写出一张字节偏移计算正确的经典交叉引用表,让测试不依赖解析器对损坏文件的恢复行为

uses
  System.SysUtils, PDFlibrary;

function BuildPdf(const Objects: array of AnsiString): AnsiString;
var
  Offsets: array of Integer;
  I, XRefPos: Integer;
begin
  Result := '%PDF-1.4'#10;
  SetLength(Offsets, Length(Objects));
  for I := 0 to High(Objects) do
  begin
    Offsets[I] := Length(Result);   // "N 0 obj" 的 0 起算字节偏移
    Result := Result + AnsiString(IntToStr(I + 1)) + ' 0 obj'#10 +
      Objects[I] + #10'endobj'#10;
  end;
  XRefPos := Length(Result);
  Result := Result + 'xref'#10'0 ' + AnsiString(IntToStr(Length(Objects) + 1)) +
    #10'0000000000 65535 f '#10;
  for I := 0 to High(Offsets) do      // 每条表项恰好 20 字节
    Result := Result + AnsiString(Format('%.10d 00000 n ', [Offsets[I]])) + #10;
  Result := Result + 'trailer'#10'<< /Size ' +
    AnsiString(IntToStr(Length(Objects) + 1)) + ' /Root 1 0 R >>'#10 +
    'startxref'#10 + AnsiString(IntToStr(XRefPos)) + #10'%%EOF'#10;
end;

function StreamObj(const Content: AnsiString): AnsiString;
begin
  Result := '<< /Length ' + AnsiString(IntToStr(Length(Content))) +
    ' >>'#10'stream'#10 + Content + #10'endstream';
end;

测试文档有两个中间 Pages 节点。节点 3 带间接 MediaBox(对象 11,400 × 300 磅)、直接 CropBox 和直接 Resources 字典,管着两页。节点 4 带信纸尺寸的 MediaBox,管第三页。把第 1 页移到位置 3 会把它重新挂到节点 4 之下,这正是需要物化的那一步移动:不物化,这页就会变成信纸页

procedure Check(Condition: Boolean; const Msg: string);
begin
  if not Condition then
    raise Exception.Create(Msg);
end;

procedure CheckMovedPageIsIsolated;
var
  Lib: TPDFlib;
  FontID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Check(Lib.LoadFromString(BuildPdf([
      '<< /Type /Catalog /Pages 2 0 R >>',
      '<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 3 >>',
      '<< /Type /Pages /Parent 2 0 R /Kids [5 0 R 6 0 R] /Count 2 ' +
        '/MediaBox 11 0 R /CropBox [10 20 390 280] /Resources << >> >>',
      '<< /Type /Pages /Parent 2 0 R /Kids [7 0 R] /Count 1 ' +
        '/MediaBox [0 0 612 792] >>',
      '<< /Type /Page /Parent 3 0 R /Contents 8 0 R >>',
      '<< /Type /Page /Parent 3 0 R /Contents 9 0 R >>',
      '<< /Type /Page /Parent 4 0 R /Contents 10 0 R >>',
      StreamObj('1 w'), StreamObj('2 w'), StreamObj('3 w'),
      '[0 0 400 300]']), '') = 1, 'load failed');

    Lib.SelectPage(1);
    Check(Lib.MovePage(3) = 1, 'MovePage failed');
    Lib.SelectPage(3);                       // 刚移动过来的那页
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'inherited MediaBox lost');

    Lib.SetPageBox(1, 0, 200, 200, 200);     // MediaBox 200 x 200
    Lib.SetPageBox(2, 0, 100, 100, 100);     // CropBox 100 x 100
    FontID := Lib.AddStandardFont(4);        // Helvetica
    Lib.SelectFont(FontID);
    Lib.SetTextSize(12);
    Lib.DrawText(20, 20, 'MOVED');

    // 在选择另一页之前检查旧父节点(见下文)
    Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
      'font registered in the old Pages node');

    Lib.SelectPage(1);                       // 原第 2 页,仍在节点 3 之下
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling MediaBox changed');
    Check(Abs(Lib.GetPageBox(2, 2) - 380) < 0.001, 'sibling CropBox changed');
    Check(Pos(AnsiString('400'), Lib.GetObjectToString(11)) > 0,
      'shared object 11 was rewritten');
  finally
    Lib.Free;
  end;
end;

GetPageBox(BoxType, Dimension) 的盒子类型 1 是 MediaBox、2 是 CropBox,维度 2 是宽度。在默认左下原点下,SetPageBox(1, 0, 200, 200, 200) 意为左 0、顶 200、宽 200、高 200。物化器若共享实例,兄弟检查就会失败:CropBox 的编辑落进节点 3 的直接数组,跟随引用的盒子写入器还会改写对象 11

CopyPageRanges 会改动源文档吗?

CopyPageRanges 确实会写到来源页上,但它写的每个值都是独立副本,所以之后对来源的编辑只影响你编辑的那一页。写入本身是有意的:来源页在字典被克隆进目标之前需要显式的 MediaBox、CropBox、Rotate 和 Resources,否则副本会丢掉全部继承物。重新编号并把页面复制进目标见PDFlibPas 的跨文档对象深拷贝;这里的陷阱在来源一侧——大多数人以为复制只读来源

保存的输出永远看不出来。共享也好复制也好,物化后的值序列化结果相同,两种做法保存的文档逐字节一致。只有复制之后再编辑来源文档,别名才现形:

procedure CheckSourceSurvivesCopy;
var
  Lib: TPDFlib;
  SourceID, TargetID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Check(Lib.LoadFromString(BuildPdf([
      '<< /Type /Catalog /Pages 2 0 R >>',
      '<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 2 ' +
        '/MediaBox [0 0 400 300] /Resources << >> >>',
      '<< /Type /Page /Parent 2 0 R /Contents 5 0 R >>',
      '<< /Type /Page /Parent 2 0 R /Contents 6 0 R >>',
      StreamObj('1 w'), StreamObj('2 w')]), '') = 1, 'load failed');
    SourceID := Lib.SelectedDocument;

    TargetID := Lib.NewDocument;             // 成为当前选中的文档
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // 只收窄 CropBox
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'MediaBox followed CropBox');
    Lib.SetPageBox(1, 0, 200, 200, 200);

    Lib.SelectPage(2);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling page resized');

    Lib.SelectDocument(TargetID);            // 副本保持原始尺寸
    Lib.SelectPage(Lib.PageCount);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
  finally
    Lib.Free;
  end;
end;

这个测试里两页都继承根节点的直接 MediaBox。如果复制步骤把那个实例附着到来源页 1,又把它再次附着成页 1 的 CropBox,收窄 CropBox 就会收窄 MediaBox,改 MediaBox 的尺寸就会经根节点改到页 2。先复制页面出去、再继续编辑来源的工作流——比如修剪原件之前把双面扫描件整理成一份 PDF——正是这类别名现形的地方

实例别名为什么这么难测?

实例别名难测,是因为可观察的效果需要按特定顺序走三步:造出别名,改动一侧,然后在别的东西碰它之前检查另一侧。大多数测试只做第一步,然后比较保存的输出——别名在不在,输出都一样

PDFlibPas 里的顺序陷阱是 SelectPage。选择页面会经 SelectFont 重新应用当前字体,从而把该字体注册进页面资源。没有自己的 /Resources 的页面会解析到父节点的字典,所以单纯选择这种页面就会合法地把 /Font 加进 Pages 节点。在上面的 MovePage 测试里,选择原第 2 页会把 Helvetica 条目加进节点 3——这是正确行为,不是泄漏。这正是 GetObjectToString(3) 检查放在 SelectPage(1) 之前的原因;两者一换,即使没有别名测试也会失败

这条规则也划出了 PDFlibPas 刻意不管的地界。向继承 Resources 字典的页面写资源,写进的是祖先的字典,每个兄弟都看到新条目。这是继承按规范工作,不是实例共享,而且无害——往共享字典里加一个字体或图像名不会改变其他页面的渲染。需要某页停止继承时,先给它自己的 Resources 字典

PDF 对象模型代码的检查清单

这些教训适用于任何建在对象池和指针容器之上的 PDF 对象模型,Delphi 里外都算数:

  • 按 ISO 32000-1 §7.7.3.4 物化继承属性时,直接值深拷贝,间接引用保持为指向同一对象的新引用
  • 除非共享是有意为之且写进文档,否则绝不把既有实例 Add 进第二个容器;池管所有权意味着运行时永远不会抱怨
  • 只就地编辑当前节点作为直接对象拥有的东西;间接或继承的值用全新的直接对象替换(写时复制)
  • 由其他条目派生的默认值——比如从 MediaBox 派生的 CropBox——需要自己的实例
  • 用“先变异、再检查另一个持有者”的序列测别名,并检查中间可能合法写入的调用顺序
  • 在这里比较保存的输出证明不了任何事:共享与复制的值在第一次编辑之前序列化结果完全相同

PDFlibPas 通过一个 TPDFlib 类向 Delphi、C++Builder 和 Free Pascal 暴露页面树编辑、跨文档复制与页面盒子控制。版本、平台与完整 API 参考见 PDFlibPas Delphi PDF 库产品页