技术文章

用 PDFium 在 Delphi 中控制 PDF 字体替代

Windows 办公桌上产出的装箱单在字体字典里写着 Arial,不带任何字体程序,在这张桌子上的每个查看器里都显示正常。放进 Debian 容器里光栅化,同一份文件的每个字形都换了一款无衬线体来画。文字仍然从该开始的地方开始,因为字形位置来自 PDF 里存的 /Widths 数组,但字母形状变了,替代字体的轮廓比它占据的宽度窄的地方间距显得松散,替代字体缺的字符则留下空洞。渲染器没有错。文档把字体的选择权交给了渲染它的那一方,而这个选择可以在你自己的代码里做出——随应用一起打包字体字节就行

ISO 32000-1 允许这么做。§9.6.2.2 的 14 种标准字体任何时候都可以只按名字引用,其他简单字体只要字典和字体描述符(§9.8)描述了度量和标志,也可以不嵌入。PDF/A 则直接禁止(ISO 19005-1 §6.3.4 要求每个字体程序都必须嵌入),这足以说明只报名字的字体在文件离开写入它的那台机器之后有多可靠

命名未嵌入 Arial 字体的 Delphi PDF:在默认宿主映射器下三台机器渲染各异,而 PDFium 一旦从 IPdfSystemFontProvider 拿到随附字体字节就渲染一致
文档每次提到未嵌入的字体,PDFium 都会索要字体字节;提供者用你自己随附的字节取代宿主映射器的每机猜测

为什么不直接把字体装到服务器上?

有时候把字体装上就够了。它在三种常见情形下失效:字体许可可能只允许桌面使用、不允许装到自动渲染文档的服务器上;容器镜像经常重建,手工拷进去的字体会随下一次部署消失;受监管的工作流要求渲染栈能从版本控制下的产物复现,而机器级的字体目录不在其列

还有一个中间步骤。TPdfLibraryConfiguration.UserFontPaths 在库加载之前经 ConfigurePdfLibrary 传入,告诉 PDFium 的原生映射器去哪些目录扫描字体文件。这份列表是替换平台默认值而不是追加,在 Windows 上它还会关掉 GDI 字体枚举,所以文档仍需要已安装字体时,记得把系统字体目录也列进去。某个请求最终由哪个文件胜出,仍然由映射器按它自己的匹配规则决定。当你需要确切知道应答 "Arial, bold, Cyrillic charset" 的是哪些字节时,这个决定必须放在你能读到的代码里——系统字体提供者给的就是这个

在 PDFium 加载之前安装 IPdfSystemFontProvider

PDFium Component 用一个只有单方法的接口暴露字体映射。IPdfSystemFontProvider.ResolveFont 接收一个携带 FaceName、Weight、Italic、Charset 和 PitchFamily 的 TPdfSystemFontRequest,以一份 TPdfSystemFontData 记录作答,内含字体名、完整的 TrueType、OpenType 或 TrueType Collection 字节、字符集和 TTCIndex。返回 False 就是拒绝这次请求

ConfigureSystemFontProvider 必须在库加载之前运行。PDFium 只在初始化时收一次字体映射器,所以 Loaded 已经为真时组件会抛出 EPdfError("Configure the system font provider before loading PDFium")。很多调用都会按需加载库,包括特性探测,所以把配置放在启动的最顶端。下面的提供者在构造函数里建好查找表并读入所有字体文件;此后 ResolveFont 只做读取:

uses
  System.SysUtils, System.Classes, System.IOUtils, PDFium;

type
  TBundledFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FKeys: TStringList;           // 构造函数中排序一次,此后只读
    FFonts: array of TBytes;
    FFaces: array of WString;
    class function KeyFor(const Face: string; Bold, Italic: Boolean): string; static;
    procedure AddFont(const Face: string; Bold, Italic: Boolean;
      const ReportedFace, FileName, FontDir: string);
  public
    constructor Create(const FontDir: string);
    destructor Destroy; override;
    function ResolveFont(const Request: TPdfSystemFontRequest;
      out Font: TPdfSystemFontData): Boolean;
  end;

class function TBundledFontProvider.KeyFor(const Face: string;
  Bold, Italic: Boolean): string;
begin
  Result := LowerCase(Face) + '|' + IntToStr(Ord(Bold)) + IntToStr(Ord(Italic));
end;

procedure TBundledFontProvider.AddFont(const Face: string; Bold, Italic: Boolean;
  const ReportedFace, FileName, FontDir: string);
var
  I: Integer;
begin
  I := Length(FFonts);
  SetLength(FFonts, I + 1);
  SetLength(FFaces, I + 1);
  FFonts[I] := TFile.ReadAllBytes(TPath.Combine(FontDir, FileName));
  FFaces[I] := WString(ReportedFace);
  FKeys.AddObject(KeyFor(Face, Bold, Italic), TObject(NativeInt(I)));
end;

constructor TBundledFontProvider.Create(const FontDir: string);
begin
  inherited Create;
  FKeys := TStringList.Create;
  FKeys.Sorted := True;
  FKeys.Duplicates := dupError;
  AddFont('Arial', False, False, 'Arial', 'arial.ttf', FontDir);
  AddFont('Arial', True,  False, 'Arial', 'arialbd.ttf', FontDir);
  // 别名:上报实际提供的字族,让策略看得见
  AddFont('Helvetica', False, False, 'Arial', 'arial.ttf', FontDir);
end;

destructor TBundledFontProvider.Destroy;
begin
  FKeys.Free;
  inherited;
end;

function TBundledFontProvider.ResolveFont(const Request: TPdfSystemFontRequest;
  out Font: TPdfSystemFontData): Boolean;
var
  Index: Integer;
begin
  Font := Default(TPdfSystemFontData);
  Result := FKeys.Find(KeyFor(string(Request.FaceName),
    Request.Weight >= 600, Request.Italic), Index);   // 600 及以上按粗体提供
  if not Result then
    Exit;
  Index := Integer(NativeInt(FKeys.Objects[Index]));
  Font.FaceName := FFaces[Index];
  Font.FontData := FFonts[Index];
  Font.Charset := Request.Charset;
  Font.TTCIndex := 0;                // .ttc 集合内的字面编号
end;

procedure ConfigureFonts(const FontDir: string; Audit: Boolean);
var
  Policy: TPdfSystemFontPolicy;
begin
  Policy := TPdfSystemFontPolicy.Default;
  Policy.AllowDefaultFallback := not Audit;
  Policy.AllowFaceSubstitution := not Audit;
  Policy.MaxFontBytes := 32 * 1024 * 1024;
  Policy.MaxCacheEntries := 64;
  ConfigureSystemFontProvider(TBundledFontProvider.Create(FontDir), Policy);
  // 到这里才能打开文档;第一个需要 PDFium 的调用会加载它
end;

这个示例里的表键是故意从简的。真实文档会把同一家字族拼写成好几种样子,所以在冻结这张表之前,先从有代表性的一批文档里把 Request.FaceName 记下来;下文的记录包装器产出的正是这份清单。字重阈值也是一个决策点:FPdfExtensions 单元里 FXFONT_FW_NORMAL 是 400、FXFONT_FW_BOLD 是 700,600 的 semibold 请求总得落到其中一边

策略标志到底决定了什么?

每个请求都按同一顺序走。组件先查自己的缓存,再调用你的提供者,然后校验答案。被接受的答案进入缓存并交给 PDFium。被拒绝或未通过校验的答案转给 FPDF_GetDefaultSystemFontInfo 返回的平台映射器——但仅在 AllowDefaultFallback 打开时;否则这次请求计为失败,PDFium 在没有你字体的情况下继续渲染

校验本身很短。空的 FontData 会被拒绝,超过 MaxFontBytes 的也一样。答案里空缺的 FaceName 会被补上请求的名字。AllowFaceSubstitution 关闭时,上报的字体名与请求的名字不同(比较忽略大小写)同样会被拒绝。这条检查只读你上报的名字,别的什么都不看。提供者交出 Liberation Sans 的字节却报名 "Arial" 能一路畅通,所以示例才为它的 Helvetica 别名上报真实的字族:旗帜关闭时,用 "Arial" 应答 Helvetica 请求会被拒绝,落进 RejectedProviderResponses

PDFium Component 的验证闸门在字节到达 PDFium 之前检查空数据、MaxFontBytes 大小和字面替换,AllowDefaultFallback 决定走宿主回退还是请求失败
校验在组件内部、任何提供者字节到达 PDFium 之前运行;关闭回退时,无法映射的请求在 FailedRequests 里计一次,PDFium 用自带的替代字体画出文本

TTC 索引在另一个环节被检查。PDFium 经常一次只索要一个 sfnt 表,比如 cmap 或 glyf,组件应答这类查询的方式是遍历你交回字节里的表目录。对集合来说,遍历从 TTCIndex 选择的那个目录开始;索引超过 ttcf 头里声明的字体数,或者单字体文件配了非零索引,这些表查询就什么都拿不到。目录遍历识别 TrueType(0x00010000 和 true)、带 CFF 轮廓的 OpenType(OTTO)和集合(ttcf)。WOFF 和 WOFF2 文件必须在提供者交回之前先解压成普通 sfnt

TPdfSystemFontPolicy.Default 把两个标志都打开,单字体上限 64 MB、缓存 32 条。这适合逐步铺几个字族的提供者:还没映射的字体照旧按老样子渲染。审计构建应当把两个标志都关掉。缺口会以计数失败和被拒替换的形式现形,回退命中再也无法替字体集漏掉的字族打掩护

哪个线程会调用 ResolveFont?

ResolveFont 运行在正在加载或渲染需要该字体的页面的那个线程上,未必是主线程。组件用临界区保护自己的缓存和计数器,但在你的方法执行期间不持有这把锁。如果你的应用在后台线程渲染,提供者在构造之后改动的任何状态都得自己加锁

异常是第二件要留在方法内部的东西。组件在与原生库的边界上捕获任何从 ResolveFont 逃逸的异常,当作一次拒绝的请求处理,请求继续走回退或失败。依赖这个机制,等于把映射代码里的 bug 变成由别人悄悄提供的字体。下面的包装器在锁下记录每一次脱靶,并把异常留在本地,顺便给你列出该补进表里的字体名:

uses
  System.SysUtils, System.Classes, System.SyncObjs, PDFium;

type
  TRecordingFontProvider = class(TInterfacedObject, IPdfSystemFontProvider)
  private
    FInner: IPdfSystemFontProvider;
    FLock: TCriticalSection;
    FMisses: TStringList;
  public
    constructor Create(const Inner: IPdfSystemFontProvider);
    destructor Destroy; override;
    function ResolveFont(const Request: TPdfSystemFontRequest;
      out Font: TPdfSystemFontData): Boolean;
    function MissedFaces: string;
  end;

constructor TRecordingFontProvider.Create(const Inner: IPdfSystemFontProvider);
begin
  inherited Create;
  FInner := Inner;
  FLock := TCriticalSection.Create;
  FMisses := TStringList.Create;
  FMisses.Sorted := True;
  FMisses.Duplicates := dupIgnore;
end;

destructor TRecordingFontProvider.Destroy;
begin
  FMisses.Free;
  FLock.Free;
  inherited;
end;

function TRecordingFontProvider.ResolveFont(const Request: TPdfSystemFontRequest;
  out Font: TPdfSystemFontData): Boolean;
begin
  try
    Result := FInner.ResolveFont(Request, Font);
  except
    Result := False;            // 在这里记日志;别让它传到 PDFium
  end;
  if Result then
    Exit;
  FLock.Enter;
  try
    FMisses.Add(Format('%s weight=%d italic=%s charset=%d pitch=%d',
      [string(Request.FaceName), Request.Weight,
       BoolToStr(Request.Italic, True), Request.Charset, Request.PitchFamily]));
  finally
    FLock.Leave;
  end;
end;

function TRecordingFontProvider.MissedFaces: string;
begin
  FLock.Enter;
  try
    Result := FMisses.Text;
  finally
    FLock.Leave;
  end;
end;

除了对象变量,还要用一个接口变量握住记录器。组件持有自己的接口引用,ClearSystemFontProvider 会把它放掉;如果那是最后一个引用,对象随之销毁,一个普通的类变量从此指向已释放的内存。想在渲染开始之前知道文档引用了哪些字体,分析 PDF 字体属性 里的按文档清单会把已嵌入和未嵌入字体并列列出

给字体缓存定容

映射请求在渲染过程中反复出现,所以被接受的答案会进缓存。缓存键覆盖字体名(不区分大小写)、字重、斜体标志、字符集和间距族,达到 MaxCacheEntries 时按最近最少使用淘汰。取值 0 会关闭缓存,每个请求都到达你的提供者并被重新校验。负值,或小于等于零的 MaxFontBytes,会让 ConfigureSystemFontProvider 抛出 "Invalid system font provider policy"

单个 CJK 集合就能跑出 20 MB 以上,此时条目数说明不了内存占用。要按字节预算管理,用 ConfigureSystemFontCacheGovernor 挂一个 FPdfCache 单元的 TPdfCacheGovernor,按最大字节数创建,并与组件的其他缓存共享。它同样必须在库加载之前设置。每个缓存条目按其字体数据的完整长度计费,所以一个应答四种不同字符集请求的 20 MB 集合,即使你的提供者每次交回同一个数组,也按四倍计入预算。调控器拒绝预留时字体照样提供,只是不进缓存。调控器对象要活到 UnloadLibrary 跑完,因为缓存条目持有对它的预留

在生产环境中证明映射结果

GetSystemFontProviderStatistics 返回一份 TPdfSystemFontStatistics 记录。Configured 和 Installed 说明是否设置了提供者、是否已交给 PDFium。MapRequests 统计每一次映射请求,CacheHits、ProviderHits 和 DefaultFallbackHits 显示它们分别如何被应答。FailedRequests 统计无人应答的请求,RejectedProviderResponses 统计被策略拒绝的应答。其余字段跟踪表级读取(FontDataRequests)、存活字体句柄、缓存字体数、缓存字节数和淘汰次数

GetSystemFontProviderStatistics 把 PDFium 字体映射请求拆分为缓存、提供程序与回退命中;Delphi 一致性运行中只要出现 DefaultFallbackHits 或 FailedRequests 即抛出
统计记录把字体替换变成一致性运行可以断言的对象;任何回退或失败请求都意味着文档需要该集合没有随附的字体

合规运行在批次结束后读计数器,然后卸载。UnloadLibrary 先把提供者从 PDFium 分离、释放平台映射器、清空缓存,然后才关闭 PDFium,文档还开着时它拒绝运行。ClearSystemFontProvider 放在最后;PDFium 还加载着时它会抛异常,并且会重置计数器,所以先读后清:

var
  Recorder: TRecordingFontProvider;
  RecorderRef: IPdfSystemFontProvider;   // 让对象保持存活
  Policy: TPdfSystemFontPolicy;
  Stats: TPdfSystemFontStatistics;
begin
  Recorder := TRecordingFontProvider.Create(TBundledFontProvider.Create(FontDir));
  RecorderRef := Recorder;
  Policy := TPdfSystemFontPolicy.Default;
  Policy.AllowDefaultFallback := False;
  Policy.AllowFaceSubstitution := False;
  ConfigureSystemFontProvider(RecorderRef, Policy);

  // FontDir、SampleFiles 和 RenderCorpus 是你自己的;批次必须
  // 在 UnloadLibrary 运行前关闭它打开的每个文档
  RenderCorpus(SampleFiles);

  Stats := GetSystemFontProviderStatistics;
  Writeln(Format('requests=%d cache=%d provider=%d fallback=%d',
    [Stats.MapRequests, Stats.CacheHits, Stats.ProviderHits,
     Stats.DefaultFallbackHits]));
  Writeln(Format('rejected=%d failed=%d evictions=%d cachedBytes=%d',
    [Stats.RejectedProviderResponses, Stats.FailedRequests,
     Stats.CacheEvictions, Stats.CachedFontBytes]));

  UnloadLibrary;               // 先分离提供者,再关闭 PDFium
  ClearSystemFontProvider;     // 只在 PDFium 卸载后才允许调用

  if (Stats.FailedRequests > 0) or (Stats.RejectedProviderResponses > 0) then
    raise Exception.Create('Font set incomplete:' + sLineBreak +
      Recorder.MissedFaces);
end;

回退关闭时,DefaultFallbackHits 恒为零,每个缺口都落进 FailedRequests——提供者答了但策略拒绝名字或大小时,往往还伴随 RejectedProviderResponses。回退打开的生产构建里,同样的缺口挪进 DefaultFallbackHits,要画曲线的就是这个计数器:新客户开始送文件后它一路上涨,说明某个字体集没覆盖的字族正在用宿主碰巧提供的字体渲染。组件其余部分的线程规则遵循另行描述的渲染锁纪律

同一个库实例在 Delphi、C++Builder 和 Lazarus 中处理字体供给、渲染和文本提取;PDFium Component for Delphi 页面 介绍各版本与原生库的部署