技术文章

PDF 中的 Fast Web View:线性化改变了什么

从一个链接打开一份 200 页的 PDF,浏览器经常是一片空白,直到文件的大部分到达才有动静。Fast Web View 是 Adobe Acrobat 对线性化 PDF(ISO 32000-1 附录 F)的叫法:第一页和一份小索引放在文件最前面,阅读器因此能早早画出第一页,后续页面再用 HTTP Range 请求按需取回。HotPDF 与 PDFium Component 都能在 Delphi 里写出线性化文件

这些都不是独立的文件格式。线性化 PDF 是一份普通 PDF,任何符合规范的阅读器无需特殊处理就能打开;差别在于字节的排列顺序,外加两个额外结构:线性化参数字典和提示流。阅读器能不能享受到好处,取决于两个条件。文件必须被线性化并保持这一状态——一次追加式编辑会悄悄破坏它;Web 服务器还必须用 206 Partial Content 应答字节范围请求。在本地磁盘上,寻道到文件末尾不花任何代价,线性化 PDF 的表现与其他文件毫无二致,所以 Fast Web View 纯粹是一种网络优化,只对直接从 URL 打开的大文档才有回报

线性化 PDF 重排了什么

线性化 PDF 把第一页所需的一切收拢到文件开头附近的一个连续块里,放在所有其他页面之前。普通 PDF 的对象可以以几乎任意顺序散落,因为文件末尾的交叉引用表把每个对象号映射到字节偏移量:阅读器定位到尾部,读取 startxref 指针,加载 xref 表,之后就能找到任何对象(PDF 文件结构总览完整走了一遍头部、主体、xref 与尾部的布局)。这套设计在磁盘上很出色,在网络上却很糟糕,因为尾部恰恰是最后到达的部分。要画出第一页,传统阅读器需要页面对象、其内容流,以及用到的字体和图像,而在一份无序文件里,这些东西中的任何一个都可能躺在最后 1 MB 里

线性化把顺序固定下来。头部之后是线性化字典和一小节第一页交叉引用,然后是 catalog 等文档级对象、主提示流,以及带全部资源的第一页。其余页面逐一跟上,接着是后续页面之间共享的对象,最后才是主交叉引用表。忽略这一优化的阅读器仍然从文件末尾起步、经由主表找到每个对象,这正是线性化文件与旧软件保持完全兼容的原因。于是在十六进制编辑器里看,对象编号是倒着排的:前部块拿着最大的编号,它后面的一切都从 1 开始编号

普通 PDF 与启用 Fast Web View 的线性化 PDF 的字节布局对比
线性化文件把线性化字典、第一页 xref 和提示流搬到一切之前;普通 PDF 唯一的索引仍留在文件尾部

线性化字典与提示表

在 %PDF 头部之后,线性化文件中的第一个对象是线性化参数字典,附录 F 要求它落在文件头 1024 字节之内,让流式阅读器在开头的数据包里就能找到它。表 F.1 列出了它的条目:/L 是整个文件的字节长度,/H 是主提示流的偏移量和长度,/O 是第一页的对象号,/E 是第一页结束处的偏移量,/N 是页数,/T 是主交叉引用表中第一个条目的偏移量。/L 这个条目的分量比看上去更重。当它与真实文件大小不一致时,表 F.1 指示阅读器把文档当作普通 PDF 对待,无视其中每一条提示

提示流是让跳转到第 40 页变得廉价的关键。它装着两张表:页面偏移提示表为每一页记录其对象从哪里开始、覆盖多少字节;共享对象提示表对多页共用的字体、徽标等资源做同样的事。想要第 40 页的阅读器查到它的字节范围,只请求这一段,字节一到就渲染,尚未持有的共享对象也用同样的方式拉取。两个细节会让自制的线性化工具翻车。提示偏移是逻辑偏移,按提示流本身不存在来计算,写入器若存了物理偏移,之后的每个范围请求都会偏差一个提示对象的大小。而收集页面资源时顺着页面的 /Parent 链走的写入器,会沿页面树一路回溯,把整个文档都拖进第一页部分。两种文件照样自称线性化。哪种也不会加载得更快

为什么 Fast Web View 需要服务器配合

只有服务器能按请求交付文件的任意切片,Fast Web View 才工作得起来。阅读器发送带 Range 头的 HTTP 请求,期望拿回 206 Partial Content;如果服务器从不通告 Accept-Ranges: bytes,或者它前面的代理或 CDN 把范围请求合并成完整传输,阅读器就无法自行取回第 40 页,只能退而下载整个文件。此时 PDF 内部的结构正确却完全被浪费,这正是最常被误诊为“线性化坏了”的故障。在重建文档之前,先对阅读器实际打开的那个 URL 请求头一千字节,比如用 curl -r 0-1023,确认状态码是 206。静态文件主机默认通常就做对了,而用自己的处理器输出 PDF 流的应用端点经常做不到

线性化提示表驱动 HTTP 范围请求,为 Fast Web View PDF 的单页返回 206 Partial Content
提示表把任意页的字节范围交给阅读器,支持范围的宿主用一个部分响应即可送出第 40 页;没有字节服务就得重新下载整个文件

如何检查 PDF 是否有 Fast Web View

别信产出文件的那个工具,去验证字节,而且条件的两半都要查:文件声明自己是线性化的,且这份声明仍与磁盘上的文件相符。三个检查几乎覆盖所有情况,从桌面上的快速一眼,到发布管线里的自动闸门:

  • Adobe Acrobat 或 Reader:打开 File > Properties,Description 选项卡的右下角会显示 Fast Web View: Yes 或 No。Acrobat 只在结构存在且为最新时才报 Yes,所以线性化之后又被编辑过的文件会显示 No
  • 命令行上的 qpdf:qpdf --check-linearization 把提示表与真实对象位置做核对,qpdf --show-linearization 则转储字典和每一条提示表条目
  • 文件的头一千字节:用文本或十六进制编辑器打开,在前 1024 字节里找一个含有 /Linearized 1 的对象;找到之后,把它的 /L 值与操作系统报告的文件大小比对
# 按实际布局核对线性化字典与提示表
qpdf --check-linearization report-web.pdf

# 转储 /L、/H、/O、/E、/N、/T 与每一条提示表条目
qpdf --show-linearization report-web.pdf

值得接进管线的检查是 qpdf 那一个,因为它把提示表与真实对象位置做了核对;只确认字典存在的检查,会愉快地为偏移量指错字节的文件放行。从 Delphi 侧看,HotPDF 的 THotPDF.IsLoadedLinearized 报告已加载文档是否声明自己线性化,解析前先扫描头 1024 字节找 /Linearized。PDFium Component 用类函数 TPdf.InspectAvailability 回答同一个问题,其 Linearization 字段返回 plnLinearized、plnNotLinearized 或 plnUnknown,完全不必加载文档。两个标志报告的都是文件的声明;至于声明是否仍与磁盘上的字节相符,要看 /L 的比对:

uses
  System.SysUtils, System.Classes, System.Math, System.StrUtils, PDFium;

type
  TFastWebView = (fwvNo, fwvStale, fwvYes);

// 自定义辅助函数:是否线性化由 PDFium 判定,
// /L 比对负责抓住其后追加的编辑
function FastWebViewState(const FileName: string): TFastWebView;
var
  Stream: TFileStream;
  Head: AnsiString;
  Text: string;
  P, Q: Integer;
begin
  Result := fwvNo;
  Stream := TFileStream.Create(FileName, fmOpenRead or fmShareDenyWrite);
  try
    if TPdf.InspectAvailability(Stream).Linearization <> plnLinearized then
      Exit;
    SetLength(Head, Min(Stream.Size, 1024));   // 附录 F:头 1024 字节
    Stream.Position := 0;
    if Length(Head) > 0 then
      Stream.ReadBuffer(Head[1], Length(Head));
    Text := string(Head);
    P := Pos('/Linearized', Text);
    if P = 0 then
      Exit;
    P := PosEx('/L ', Text, P + Length('/Linearized'));
    if P = 0 then
      Exit;
    Inc(P, 3);
    Q := P;
    while (Q <= Length(Text)) and CharInSet(Text[Q], ['0'..'9']) do
      Inc(Q);
    if StrToInt64Def(Copy(Text, P, Q - P), -1) = Stream.Size then
      Result := fwvYes
    else
      Result := fwvStale;   // 曾线性化,之后被修改过
  finally
    Stream.Free;
  end;
end;

在 Acrobat、qpdf 与 Delphi 中打开 Fast Web View

任何按附录 F 顺序重写整个文件的工具都能打开 Fast Web View,而最要紧的是它必须放在最后一步跑。在 Acrobat 里,先在 Preferences > Documents 下启用 Save As optimizes for Fast Web View,然后用 File > Save As 而不是 Save,因为普通 Save 可能追加一次增量更新。在服务器或构建脚本里,qpdf --linearize in.pdf out.pdf 能把任何 PDF 重写为线性化形式且不碰输入。Delphi 代码有两条路,取决于文档是你生成的还是接手的。HotPDF 在 THotPDF.LinearizeOutput 为 True 时直接写出线性化输出;在 BeginDoc 之前把它与其他输出选项一起设置好,附录 F 布局就会在 EndDoc 内部计算并写入:

qpdf --linearize report-final.pdf report-web.pdf
var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.AutoLaunch := False;       // EndDoc 之后不打开阅读器
    PDF.FileName := 'catalog-web.pdf';
    PDF.LinearizeOutput := True;   // 在 BeginDoc 之前设置
    PDF.BeginDoc;                  // BeginDoc 之后第 1 页已存在
    PDF.CurrentPage.TextOut(72, 72, 0, 'Spring catalog');
    PDF.AddPage;
    PDF.CurrentPage.TextOut(72, 72, 0, 'Price list');
    PDF.EndDoc;                    // 线性化布局在这里写入
  finally
    PDF.Free;
  end;
end;

对已经存在的文件,PDFium Component 提供 TPdf.SaveAsLinearized。它先执行普通的 PDFium 保存、把结果写进一个中间存储,页面编辑与表单值走的路径与其他保存完全相同,然后按附录 F 重排这份输出,再写入你的目标文件。该方法接受与 SaveAs 相同的 TSaveOption 和 TPdfVersion 参数,拒绝 saIncremental 以及低于 PDF 1.2 的版本;文件名重载会先写到临时文件,保存成功之后才拿它替换目标。由于写入器从当前修订版重建整个文件,它也是给被追加过编辑的文件恢复 Fast Web View 的办法。加密输入需要 saRemoveSecurity:给对象重新编号会使标准安全处理器的逐对象密钥失效(ISO 32000-1 §7.6.2),所以 Web 副本以不加密方式写出

var
  Pdf: TPdf;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'manual-rev3.pdf';   // 带有追加的编辑
    Pdf.Active := True;
    if not Pdf.SaveAsLinearized('manual-web.pdf', saNoIncremental) then
      raise Exception.Create('Linearized save failed');
  finally
    Pdf.Free;
  end;
end;

增量更新悄悄关掉 Fast Web View

增量更新是一份正确线性化的文件日后丢掉 Fast Web View 的最常见原因。工具通过增量保存添加签名、填写表单字段或贴上便签时,原始字节原封不动,被更改的对象、新的交叉引用部分和新的尾部追加到文件末尾。前部的线性化字典描述的仍是旧布局,其 /L 不再与文件大小相符,符合规范的阅读器退回去把文档当普通 PDF 对待——哪怕线性化结构还完好地待在文件前部。HotPDF 正是通过 BeginIncrementalUpdate 和 SaveIncrementalUpdate 追加这类修订:文档还在改的时候,它是正确的工具;对一份要送到 Web 服务器的文件来说,把它当收尾一步就是错的:

// 追加一个修订版:快,保留之前的字节,
// 代价是结果不再有 Fast Web View
PDF.BeginIncrementalUpdate('report.pdf');
PDF.AddPage;
PDF.CurrentPage.TextOut(72, 760, 0, 'Addendum');
PDF.SaveIncrementalUpdate('report-rev2.pdf');
增量更新追加的修订让线性化字典失去同步,直到最后一次完整重写才恢复 Fast Web View
每次增量保存都在过期的前部字典之后再叠一层修订;以完整重写收尾、把重新线性化放在最后,Fast Web View 才保持完好

可行的规则是:文档还在变动时就用增量编辑,把线性化作为最后一步只做一次;对先被邮件发出或下载、之后才有人打开的文件,干脆别开 Fast Web View——更大的前置索引对它们毫无收益。已签名的文档则逼你做真正的取舍:完整重写会改动每个签名的 /ByteRange 所覆盖的字节,事后签名又会追加一次更新,把 /L 失配原样带回来,所以合同类文件保住签名、接受完整下载。附录 F 的写入侧——包括偏移量如何在第一个字节写出之前收敛,以及线性化输出为何放弃对象流——在用 HotPDF 提示表写线性化 PDF 与 用 PDFium Component 在 Delphi 中实现 Fast Web View 线性化两篇文章里有展开。LinearizeOutput 与 IsLoadedLinearized 随 HotPDF Delphi Component 提供,SaveAsLinearized 与 InspectAvailability 则属于 PDFium Component for Delphi, C++Builder and Lazarus