技术文章

在 Delphi 中使用 HotPDF 进行 PDF 遮蔽与 N-up 拼版

一个需求落到你桌上:拿一批已经渲染好的对账单,把账号涂黑,再为省纸按每张纸两页输出。这件事的两半,都是对一份并非你生成的 PDF 做内容流手术,没有友好的页面画布可画,也没有字体管理器可靠。你是在直接编辑已加载文档的对象图,把原始绘图操作符追加到别人排版好的页面上。HotPDF 为此恰好只暴露两个入口,而两者之中更危险的那个,恰恰是看起来无害的那一个

HotPDF 是面向 Delphi 和 C++Builder 的原生 VCL PDF 组件,它的已加载文档 API 里有一批方法,能在你从磁盘打开的页面(而非从头搭建的页面)上创建全新内容。本文关注其中两个:RedactLoadedRect 在区域上涂一层不透明矩形,StitchLoadedPage 把一页缩放后画到另一页上。两者的实现,都是往页面的 /Contents 流里写入 ISO 32000-1 §8.5 的内容流操作符。弄清这些操作符做什么、以及同样重要的它们不做什么,正是工具可用与数据泄露之间的分界线

向已加载的页面追加操作符

用常规 HotPDF API 搭页面时,内容流归组件所有,TextOut 和矢量调用都由它替你序列化。已加载的页面是另一回事:它的 /Contents 是一个现成的流对象,可能被共享,也可能是内容数组的一员,你必须在不破坏既有内容的前提下把自己接进去。三个小辅助例程保证了这件事的安全:NewIndirectStream 分配一个带空缓冲区和 /Length 0 条目的全新间接 THPDFStreamObject;ResolveLoadedStream 沿间接引用一路解析到底层流;AppendLoadedStream 在流末尾写入原始字节并改写 /Length,让保存出来的对象保持良构

两个公开方法遵循同一个模式:找到页面的 /Contents,把它解析成流;没有可用的流就建一个再挂上去;然后追加操作符。新字节写在流的末尾,画家模型保证了它们渲染在原始版面所绘内容之上。这个顺序就是遮蔽矩形背后的全部机制,也是那个矩形并非多数人想象之物的原因

HotPDF:向已加载页面追加操作符要依次走过三个辅助例程——定位页面 Contents 流、解析或创建它、最后追加原始字节;画家模型保证这些字节盖在原版面所绘内容之上
NewIndirectStream、ResolveLoadedStream 和 AppendLoadedStream 把新操作符接到既有 /Contents 流的末尾,画出的内容叠在原页面版面之上,而不重写其中一个字节

RedactLoadedRect:是不透明遮盖,不是删除

RedactLoadedRect 接收一个从零起算的页面索引、四个用户空间坐标,以及三个取值 0–1 的颜色分量:

var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('statement.pdf') > 0 then
    begin
      // 用纯黑盖住第 1 页的账号栏带。
      // 坐标是 PDF 用户空间:原点在左下角,单位为点。
      Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
      Pdf.SaveLoadedDocument('statement-covered.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

在底层,这个方法往内容流里写入三个操作符:DeviceRGB 填色设置(r g b rg)、矩形路径(x y w h re)和填充(f)。宽高按 X2 - X1 与 Y2 - Y1 推出,所以你只需给出两个对角点,范围交给方法自己算。颜色传 0, 0, 0 得到黑条,传 1, 1, 1 则得到与白页匹配的白条。坐标用的是已加载页面自己的用户空间,原点在左下角、单位是点;这也意味着想放得精确就需要页面的 /MediaBox,用 GetLoadedPageBox 传 pbMediaBox 即可拿到

这段要读两遍:填充矩形只是在视觉上盖住内容,并没有删掉它。矩形下面的文字、图像或矢量图形仍然留在 PDF 里、留在对象图里,任何复制页面、跑文本提取器、或者干脆从内容流里删掉你那个矩形的人,照样能把它们提取出来。这是视觉遮罩,不是法律或安全意义上的遮蔽。如果你要藏的确实是敏感数据——账号、病历、身份信息、任何受监管的内容——拿黑盒子盖住再把文件发出去,就是一桩等着被发现的数据泄露。真正的遮蔽需要删除底层的内容对象,而不是在上面涂一层黑

HotPDF:涂黑遮住的账号在“遮蔽”后依然存活:查看器在账号行上显示一条深色实带,而内容流仍列着 ACCT 字符串,任何文本提取器都原样输出它
r g b rg、re 和 f 这三个操作符只在上面叠像素——原始文本对象在对象图中仍然存活,一次复制加提取就能拿回黑条遮住的每一个字符

方法名里写着 “Redact”,这是个有用的提醒:它预告了这个结果会被怎么误读,而不承诺删掉什么。RedactLoadedRect 设计上就是一个视觉遮蔽原语;会移除内容的遮蔽是另一种操作,需要遍历并重写内容流里现有的操作符。所以安全用法很窄:只拿 RedactLoadedRect 做非敏感的装饰性遮罩——盖住草稿水印、截图前清掉一块区域、遮住内部校样上的过时 logo。一旦盒子底下的东西泄露出去会造成麻烦,这个方法就是错的工具,正确做法是重新生成一份不含该数据的文档,或者走真正的内容移除管线

StitchLoadedPage:缩放、平移、绘制

N-up 拼版是更友好的那类问题,因为没有东西被藏起来,只是被重新排列。StitchLoadedPage 接收目标页索引、源页索引、一个 X/Y 偏移和一个缩放系数,然后按这个位置和大小把源页画到目标页上:

// 把第 2 页(索引 1)叠到第 1 页(索引 0)上,
// 缩放到 70% 并向右上微调。
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);

// 便捷的 2-up:源页放在目标页右半边。
Pdf.StitchLoadedPageSideBySide(0, 1);

它追加的操作符串是一段标准的变换加绘制序列:q 保存图形状态,cm 矩阵把缩放放在对角线上、把偏移放进平移槽位,/StitchSrc Do 调用外部对象,最后 Q 恢复状态。q/Q 这一对很关键:它隔离了变换,拼接页面的坐标系才不会渗进之后追加的任何内容。方法也防着几种明显的错误——索引越界、目标等于源页、非正的缩放系数(会被钳到 1.0)——并且安静返回而不是抛异常,所以请自己检查输入,静默的空操作看起来和成功一模一样

StitchLoadedPageSideBySide 是通用方法之上的一层薄封装:读出目标页媒体框宽度并取一半,然后以这个半宽作 X 偏移、固定缩放 0.5 调用 StitchLoadedPage,把源页放到右半边。这个写死的 0.5 假设源页和目标页同宽;一旦不同宽,源页就没法干净地填满自己那半边,这时你应该改用通用的 StitchLoadedPage,缩放系数自己按两个媒体框算

拼接如何引用源页面

在你把输出交给各种阅读器检验之前,先弄清这个细节。经典的 N-up 拼版会把源页内容包进一个 Form XObject——一个自包含的可绘制对象,按 ISO 32000-1 §8.10.1 的说法,它必须带 /Type /XObject、/Subtype /Form 和自己的 /BBox 裁剪框。StitchLoadedPage 走的是更轻的路线:把源页面字典本身直接注册到目标的 /Resources /XObject 下,名字叫 StitchSrc,然后用 Do 绘制它。页面字典和 Form XObject 的内容模型重合度足够高——两者都引用一个内容流和一个资源字典——所以很多阅读器都能渲染出结果

由于注册对象不带 /Subtype /Form 标记,也没有自己的 /BBox,严格的消费方完全有理由忽略这个 Do,或者按与预期不同的方式裁剪。所以拼接结果要在客户实际使用的阅读器里验证,不能只看你自己机器上的那一个;要产出归档用或必须过严格校验器的 PDF,就在上游用完整的 Form XObject 包装来完成拼版。这条纪律适用于一切建立在已加载对象图上的操作,这正是每当以编程方式改动文档时,在 Delphi 中做 PDF 预检就该在发布管线里占一席之地的原因

HotPDF:拼接向目标页追加 q、携带缩放与偏移的 cm 矩阵、一次 StitchSrc Do 调用和 Q;资源字典收到的就是源页面字典本身,没有 Form 子类型也没有 BBox
q/Q 对括住一个 cm 变换加 /StitchSrc Do,但注册对象缺少 /Subtype /Form 和 /BBox,拼接结果需要在客户使用的每个阅读器里做视觉验证

它们适合什么,不适合什么

两个方法都是内容流工具,心智模型和直接绘图时一样。如果你用这个组件从头搭过页面,这些调用背后的矢量与颜色操作符在Delphi 中的 HotPDF 画布绘图一文里就见过;区别只在于这次你是往别人写的流里追加,而不是往自己拥有的流里写。记住三条边界:

  • 遮蔽只是表面功夫。RedactLoadedRect 只是往内容上涂色,永远不会删除内容。涉及敏感信息时,重新生成源文件或用真正的内容移除——黑盒子不是安全
  • 在你的目标阅读器里验证拼接页。源页是被直接引用的,没有经过带 /Subtype /Form 和 /BBox 的 §8.10.1 Form XObject,请确认目标阅读器中的渲染效果,需要严格校验的场景就在上游完成拼版
  • 坐标是页面用户空间。原点在左下角,单位是点,由页面自己的媒体框决定。放置任何内容前先用 GetLoadedPageBox 读一下框,加载进来的页面未必是你以为的尺寸

守住这些边界来用,这对方法覆盖一个真实的工作流:为打印重排页面、遮罩非机密区域、再用 SaveLoadedDocument 把结果写回——全程不需要完整重渲染。包含这些拼接与遮蔽原语的已加载文档 API,连同表单字段、批注和 FDF 方法,一起随面向 Delphi 和 C++Builder 的 HotPDF Delphi Component 发布