技術文章

PDF Library for Delphi 自動字型後援:CJK 與 Emoji 缺字

一份用 Arial 排版的發票範本,印出了「Invoice for」之後就一片空白。文字呼叫回傳 1,檔案驗證通過,擷取出來的文字卻短了十個字:北京示例科技有限公司 裡的每個漢字都不見了,因為 Arial 一個都沒有。PDF Library for Delphi 的自動字型後援預設開啟,會從已安裝的字型裡把這類字元抓出來,AddFontFallback 讓你自訂搜尋順序,而缺字政策搭配 JSON 報告,則負責處理任何字型都畫不出來的部分

無聲正是它代價高昂的原因。該出現往來單位名稱的地方是一塊空白的 PDF,能通過每一項結構檢查、在每個檢視器裡正常開啟,而它通常是被客戶發現,而不是被你的測試套件

不支援的文字為何會消失而不是拋出錯誤?

PDF 根本沒有「字型拒收某個字元」這種概念,所以缺字在檔案層級不算錯誤。簡單字型透過編碼把位元組碼對應到字形名稱;複合字型則透過 CMap 把碼位對應到 CID,再對應到字形索引。向一個字型要求它不包含的東西,你會落在字形索引零,也就是 .notdef,ISO 32000-1 §9.7.6.3 把它視為未定義字元的標準結果。多數字型把 .notdef 畫成什麼都沒有,有些則畫一個空白方框

無論哪一種,內容串流格式正確,頁面照樣渲染。規範沒有任何一條要求產生器在寫入文字運算子前先檢查涵蓋範圍,所以跳過檢查的產生器會輸出一份合規、卻悄悄遺失內容的檔案。這正是後援與回報要成對出現的原因:把解析得了的解析掉只是半份工作;把剩下的告訴你是另外一半,而在我們看來,對任何載有姓名或金額的文件來說,後面這一半更要緊

在 PDF Library for Delphi 中開啟後援鏈

只有當所選字型真的缺字串裡的某個字元時,後援才會介入,所以純拉丁文字維持原本路徑,零額外成本。新建的 TPDFlib 實體已經把自動後援打開,繪圖程式碼連一行額外呼叫都不需要:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // 自動後援預設開啟:Emoji、假名、韓文、
    // 漢字與符號會在內建候選表中查尋
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = 以子集內嵌
    Lib.SetTextSize(11);
    Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
    Lib.DrawText(72, 700, 'Delivery status: on time ✅');

    Lib.SaveToFile('invoice.pdf');
  finally
    Lib.Free;
  end;
end;

自動後援開著時,程式庫按每個未解析字元所屬的文字系統挑候選。這張表是固定的,而且以 Windows 為中心:Emoji 與繪文字依序試 Segoe UI Emoji、Segoe UI Symbol、Arial Unicode MS;假名先試 Yu Gothic;韓文先試 Malgun Gothic;統一漢字區依序試 Microsoft YaHei、Microsoft JhengHei、Yu Gothic、Malgun Gothic 與 SimSun;數學與技術符號交給 Segoe UI Symbol 與 Cambria Math。其餘全部落到一份以 Nirmala UI 與 Segoe UI 開頭的寬清單

你用 AddFontFallback 註冊的字型會在內建表之前被嘗試,而且照你加入的順序。SetAutomaticFontFallback(0) 只關掉內建表:明確指定的鏈仍然生效,當你希望輸出只用你核可的字型、其他都不用時,選的就是這個設定。AddFontFallback 會忽略已存在清單裡的名字並回傳其 1 起算的位置,而 ClearFontFallbacks、RemoveFontFallback 與 GetFontFallbackCount 讓你能在文件之間重建這條鏈

漢字統一碼陷阱:共用漢字誰贏?

中文、日文與韓文共用 Unicode 裡大部分的漢字表意文字,但每個語言圈對其中許多字的字形有不同期待。直或骨的碼位,在東京的地址與北京的地址裡是同一個;本地讀者期待的字形卻不是。後援鏈只回答「哪個已安裝字型有這個碼位的字形」,而每個 CJK 字型都有,所以誰排前面,誰就贏下所有共用漢字

自動表把 Microsoft YaHei 排在漢字的第一位。對簡體中文沒問題,對日文是錯的。那份發票上的日文地址,假名由 Yu Gothic 繪製(假名會先把查尋送去日文字型),漢字卻由 YaHei 用中文字形繪製,全部擠在同一行裡。沒有缺任何字,報告保持空白,而日文讀者一眼就看出哪裡不對勁

我們的建議是:漢字不要依賴自動順序,改為按文件的語言圈建立明確的鏈。這個資訊你通常本來就知道,從客戶紀錄或範本語言而來:

procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
  Lib.ClearFontFallbacks;
  if Locale = 'ja' then
  begin
    Lib.AddFontFallback('Yu Gothic');
    Lib.AddFontFallback('Meiryo');
  end
  else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
    Lib.AddFontFallback('Microsoft JhengHei')
  else if Locale = 'ko' then
    Lib.AddFontFallback('Malgun Gothic')
  else
    Lib.AddFontFallback('Microsoft YaHei');
  // Emoji、符號與上方未涵蓋的文字系統仍會走
  // 內建候選;在這裡傳 0 可禁止這個行為
  Lib.SetAutomaticFontFallback(1);
end;

每份文件呼叫一次,在第一個 DrawText 之前。明確清單裡的順序同樣要講究:第一個涵蓋某字元的字型勝出,所以 Arial Unicode MS 這種泛 Unicode 字型若要放,就放在最後。放在最前面的話,幾乎所有東西都由它繪製,你精心挑選的文字系統專用字型永遠輪不上

後援以整個叢集為單位

PDF Library for Delphi 以字位叢集為單位決定後援,所以一個叢集永遠由同一個字型繪製。一個天城文字音節、一個帶膚色修飾符的 Emoji、一個帶組合符號的基礎字母:每一個在螢幕上都是單一單位,其內部的塑形決策來自某一個特定字型裡的資料表。半個叢集來自 Arial、另一半來自後援字型,會在頁面上放一個技術上存在、視覺上破碎的字形,某種程度上比留白還糟

所選字型會先對字串做塑形。只有回傳字形零的叢集才會去找別的字型,而解析到同一個字型的相鄰叢集會合併成一個 run 一起繪製,所以十個字的中文名稱會變成單一 YaHei run,而不是十次獨立的字型切換。右到左順序同樣保留:阿拉伯文或希伯來文裡的後援 run 會待在雙向演算法替它安排的位置。同一套塑形機制也支撐著 日文與中文直式書寫

PDF Library for Delphi 後援鏈圖解:CJK 字元叢集在主要字型 Arial 中缺字,由第一個可涵蓋的後援字型 Microsoft YaHei 繪製,未被涵蓋的叢集則依回報或中止政策處理
這個叢集 run 會從主要字型退回到第一個能涵蓋的後援字型,只有實際用到的字型才會內嵌。沒有任何字型能繪製的叢集則遵循缺字政策:回報後繼續,或以錯誤 521 中止

缺字該讓文件停下了嗎?

取決於文件是做什麼用的,而 PDF Library for Delphi 用 SetMissingGlyphPolicy 讓你選。PDF_MISSING_GLYPH_REPORT 是預設值:文字操作照常進行,沒有任何字型畫得出的字元會從輸出中捨棄,並逐一記錄。PDF_MISSING_GLYPH_ABORT 則在任何東西寫上頁面之前就拒絕整個文字操作,DrawText 回傳 0,錯誤碼為 521(PDFLIB_ERROR_MISSING_GLYPH)

內部批次報表選回報政策並把缺漏寫進紀錄;今天略有缺漏的報表總比沒有報表好。合約、發票、憑證,以及任何載有個人 or 公司名稱的文件選中止。當事人姓名裡少一個字,是你要在自己的流程裡發現的缺陷,而且因為中止發生在寫入之前,頁面上不會留下畫了一半的行

var
  Lib: TPDFlib;
  Err: Integer;
  Report: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
    Lib.AddTrueTypeFont('Arial', 2);
    Lib.SetTextSize(11);

    if Lib.DrawText(72, 660, CustomerName) <> 1 then
    begin
      Err := Lib.LastErrorCode;   // 讀取它同時會把它重設為 0
      if Err = PDFLIB_ERROR_MISSING_GLYPH then
      begin
        Report := Lib.GetMissingGlyphReportJSON;
        // {"valid":false,"policy":1,"eventCount":1,"events":[
        //   {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
        //    "codePoint":983041,"unicode":"U+F0001",
        //    "fontName":...,"fontType":...,"operation":"DrawText"}]}
        EscalateToOperator(Report);
      end;
    end;
  finally
    Lib.Free;
  end;
end;

注意那個區域變數。LastErrorCode 被讀取時會自我清零,所以在一個地方檢查 Lib.LastErrorCode = 0、又在另一個地方把 Lib.LastErrorCode 寫進紀錄的程式碼,記下來的會是 0。讀一次,把值留下

報告裡的每一筆事件都帶有頁碼、字串內的 UTF-16 索引、以十進位與 U+XXXX 形式表示的碼位、被選中的字型、其類型,以及撞上問題的 API 呼叫。有了這些,支援工單能指名確切的字元,而不是描述一個症狀。valid 旗標只有在沒有記錄到任何事件時才是 true,這讓它可以當批次工作裡廉價的把關

程式庫只保留最近 256 筆事件,捨棄更舊的,所以一份塞滿無法渲染文字的文件不會把診斷變成記憶體問題。事件會在同一個 TPDFlib 實體的多份文件之間累積;若想要一檔一份報告,每份文件前先呼叫 ClearMissingGlyphReport,或者用 documentIndex 欄位區分它們

字母要中止,裝飾可以容忍

整份文件一套政策有時太粗。出貨標籤可能在收件人姓名旁邊帶一個裝飾性 Emoji,你寧可丟掉 Emoji 也不想拒印整張標籤。OnMissingGlyph 事件會為鏈中沒有任何字型畫得出的每個字元觸發,收到政策作為預設動作,並可以逐碼位覆寫它:

type
  TGlyphGate = class
    procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
      UTF16Index, Page: Integer; const FontName, Operation: WideString;
      var Action: Integer);
  end;

procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
  UTF16Index, Page: Integer; const FontName, Operation: WideString;
  var Action: Integer);
begin
  // 繪文字與雜錦符號屬於裝飾:捨棄並記錄
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // 字母與數字不能消失
end;

// 把事件接起來
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

這個事件在後援已經試過之後才執行,所以它只看得到在這台機器上真正無解的字元。無論處理常式選了哪個動作,每一個都會照樣進到 JSON 報告裡

量測、內嵌與部署

GetTextWidth 走的是與 DrawText 相同的逐叢集後援決策。這聽起來理所當然,卻正是自製後援層最容易出錯的地方:它們修補了繪製呼叫,量測卻留在主要字型上,於是每一個靠右對齊的合計與表格欄位,都是用與頁面實際結果不符的寬度算出來的。在這裡,繪製前量測過的字串就占著量測時的寬度,後援 run 也算在內,這正是可以放心把後援到處開著、而不是只開在你手動稽核過的範本裡的原因

中止政策下有一個後果:量測撞上無解字元時,GetTextWidth 回傳 0 並設錯誤 521。會拿寬度去除、或用它決定儲存格大小的版面程式碼,使用那個數字前應該先檢查

後援字型只在真的畫了東西時才內嵌。鏈中從未解析過叢集的字型不會為檔案增加任何位元組,畫過的字型則以它畫過的字形子集內嵌。一份在 5,000 個拉丁字元中夾了一個漢字的文件,承載的是一個漢字字形,而不是一套好幾 MB 的 CJK 字型;檔案大小最佳化與字型子集化 說明了這個子集怎麼建。正因如此,配一條涵蓋你服務的所有語言圈的長鏈成本低廉,每份 PDF 只為它用到的部分付錢。別處產生、引用了從未內嵌字型的檔案是另一種修復,見 在既有 PDF 中內嵌缺少的字型

部署上的注意事項很容易被漏掉。後援是對著執行你程式碼的那台機器上安裝的字型解析的,而裝了完整 Office 的開發工作站,字型遠比精簡的伺服器映像或容器多。Yu Gothic 或 Microsoft YaHei 不在那裡,鏈就沒有東西可以退。在目標伺服器上跑一份帶漢字姓名、韓文姓名與一個 Emoji 的文件,然後讀 JSON 報告:那裡一個空的 events 陣列,比你自己桌面上任何測試都能說明更多。把你依賴的字型隨部署出貨,並確認授權允許內嵌

同一套後援鏈、缺字政策與報告也透過 DLL 與 ActiveX 版本提供,C#、C++ 或指令碼呼叫端用同樣的呼叫來設定。參考文件與下載都在 PDF Library for Delphi 產品頁