一張在 Windows 桌機上產生的出貨單,字型字典裡寫的是 Arial,卻沒有帶字型程式,而在那台機器上的每個檢視器裡看起來都正常。同一個檔案拿到 Debian 容器裡點陣化,每個字形都改由另一款無襯線字型畫出來。文字的起點仍然在該在的位置,因為字形位置來自 PDF 裡儲存的 /Widths 陣列,但字母的形狀變了,凡是替代字型的外框比它所佔寬度還窄的地方,字距看起來就不均勻,而替代字型缺少的字元則留下一個空洞。這不是轉譯器的錯。文件把字型的選擇權交給了任何負責轉譯它的人,而這個選擇可以在你自己的程式碼裡做,方法是提供隨應用程式一起出貨的字型位元組
ISO 32000-1 允許這麼做。§9.6.2.2 的標準 14 種字型永遠可以只用名稱參照,其他任何簡單字型只要字典與字型描述元(§9.8)描述了度量與旗標,也可以不內嵌。PDF/A 則直接禁止(ISO 19005-1 §6.3.4 要求每個字型程式都必須內嵌),這很能說明一件事:檔案一旦離開了寫出它的那台機器,只靠名稱的字型有多不可靠
為什麼不乾脆把字型裝到伺服器上?
有時候裝字型就夠了。但在三種常見情境下會行不通。字型授權可能允許桌面使用,卻不允許安裝在自動轉譯文件的伺服器上。容器映像經常重新建置,手動複製進去的字型會隨下一次部署一起消失。受監管的流程希望轉譯堆疊能從版本控制下的產出物重現,而機器全域的字型資料夾並不在其中
還有一個中間步驟。在函式庫載入前透過 ConfigurePdfLibrary 傳入的 TPdfLibraryConfiguration.UserFontPaths,會告訴 PDFium 的原生對應器要掃描哪些資料夾找字型檔。這份清單是取代平台預設值而不是附加上去,而且在 Windows 上還會關閉 GDI 字型列舉,所以若文件仍需要已安裝的字型,請把系統字型資料夾也放進去。至於某個要求最後由哪個檔案勝出,仍由對應器依它自己的比對規則決定。當你需要確切知道是哪些位元組在回應「Arial、粗體、西里爾字元集」時,這個決策必須落在你讀得到的程式碼裡,而這正是系統字型供應器給你的
在 PDFium 載入前安裝 IPdfSystemFontProvider
PDFium Component 透過一個只有一個方法的介面公開字型對應。IPdfSystemFontProvider.ResolveFont 收到一個帶著 FaceName、Weight、Italic、Charset 與 PitchFamily 的 TPdfSystemFontRequest,並以一個 TPdfSystemFontData 記錄回應,裡面裝著字面名稱、完整的 TrueType、OpenType 或 TrueType Collection 位元組、一個字元集,以及一個 TTCIndex。回傳 False 就是婉拒這個要求
ConfigureSystemFontProvider 必須在函式庫載入之前執行。PDFium 只在初始化時接收一次字型對應器,所以如果 Loaded 已經是 true,元件會丟出 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 的集合檔回應四種不同字元集的要求時,會對預算計四次,即使你的供應器每次回傳的是同一個陣列。當 governor 拒絕預留時,字型仍然會被提供,只是不快取。請讓 governor 物件一直存活到 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 頁面 則涵蓋版本與原生函式庫的部署