Windows 办公桌上产出的装箱单在字体字典里写着 Arial,不带任何字体程序,在这张桌子上的每个查看器里都显示正常。放进 Debian 容器里光栅化,同一份文件的每个字形都换了一款无衬线体来画。文字仍然从该开始的地方开始,因为字形位置来自 PDF 里存的 /Widths 数组,但字母形状变了,替代字体的轮廓比它占据的宽度窄的地方间距显得松散,替代字体缺的字符则留下空洞。渲染器没有错。文档把字体的选择权交给了渲染它的那一方,而这个选择可以在你自己的代码里做出——随应用一起打包字体字节就行
ISO 32000-1 允许这么做。§9.6.2.2 的 14 种标准字体任何时候都可以只按名字引用,其他简单字体只要字典和字体描述符(§9.8)描述了度量和标志,也可以不嵌入。PDF/A 则直接禁止(ISO 19005-1 §6.3.4 要求每个字体程序都必须嵌入),这足以说明只报名字的字体在文件离开写入它的那台机器之后有多可靠
为什么不直接把字体装到服务器上?
有时候把字体装上就够了。它在三种常见情形下失效:字体许可可能只允许桌面使用、不允许装到自动渲染文档的服务器上;容器镜像经常重建,手工拷进去的字体会随下一次部署消失;受监管的工作流要求渲染栈能从版本控制下的产物复现,而机器级的字体目录不在其列
还有一个中间步骤。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
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)、存活字体句柄、缓存字体数、缓存字节数和淘汰次数
合规运行在批次结束后读计数器,然后卸载。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 页面 介绍各版本与原生库的部署