在 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,就把这一切拴在了一起
物化本身不是可选项。只带 /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 对它重新挂父的每一页调用同一个辅助函数,所以在那里物化的页面同样拿到独立实例
只有复制还不够,因为引用的那一路仍指向共享对象。如果 SetPageBox 跟着引用去编辑对象 11,被移动的页面又会改到旧父节点和它的其他子节点。所以盒子写入器应用写时复制:只有页面自己的表项是直接数组时就地编辑,间接或缺失的盒子用新的直接数组替换。对象 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 库产品页