技術記事

PDF Library for Delphiの自動フォントフォールバック

Arial設定の請求書テンプレートが「Invoice for」まで印字して沈黙します。テキスト呼び出しは1を返し、ファイルは検証を通り、テキスト抽出は10文字分足りません。北京示例科技有限公司の漢字がすべて消えたのです。Arialにはそれらが1つもないからです。PDF Library for Delphiの自動フォントフォールバックは既定で有効になっており、そのような文字をインストール済みフォントから引っ張ってきます。AddFontFallbackで独自の検索順を設定でき、フォールバックでも描けない文字には欠落グリフポリシーとJSONレポートが対処します

沈黙しているからこそ被害が大きいのです。取引先名があるべき場所に空白があるPDFは、構造検査をすべて通過し、どのビューアーでも開け、気づくのはたいていテストスイートではなく顧客です

非対応の文字がエラーではなく消えてしまうのはなぜか?

PDFにはフォントが文字を拒否するという概念がなく、欠落グリフはファイルレベルではエラーになりません。単純フォントはエンコーディングを通じて1バイトコードをグリフ名へ写し、複合フォントはCMapを通じてコードをCIDへ、さらにグリフインデックスへ写します。フォントに含まれないものを要求すると、グリフインデックス0、つまり.notdefに着地します。ISO 32000-1の§9.7.6.3はこれを未定義文字の標準的な結果として扱います。多くのフォントは.notdefをまったく描かず、空の箱を描くものもあります

どちらにしてもコンテンツストリームは正しく、ページは描画されます。仕様のどこも、テキストオペレータを書く前にカバレッジを確認することをプロデューサーに求めていないため、確認を飛ばすジェネレーターは、静かにコンテンツを失った適合ファイルを作ってしまうのです。だからこそフォールバックとレポーティングはペアでなければなりません。解決できるものを解決するのは仕事の半分で、残りを報告するのがもう半分であり、名前や金額が載る文書ではこちらのほうが重要だと私たちは考えています

PDF Library for Delphiでフォールバック連鎖を有効にする

フォールバックが働くのは、選択されたフォントが文字列内の文字を実際に欠いているときだけです。Latinだけのテキストは通常の経路を保ち、追加コストはゼロです。新しいTPDFlibインスタンスは自動フォールバックが既定で有効なので、描画コードに追加の呼び出しはまったく要りません:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // 自動フォールバックは既定で有効:絵文字、かな、ハングル、
    // 漢字、記号は組み込み候補テーブルで検索される
    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;

自動フォールバックが有効な状態では、ライブラリは未解決の文字1つ1つのスクリプトから候補を選びます。テーブルは固定でWindows志向です。絵文字と図形記号は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で描かれ、1行に混在します。欠けているものはなく、レポートは空のまま、日本語の読み手はすぐに何かがおかしいと気づきます

私たちの推奨は、漢字については自動順序に頼るのをやめ、文書のロケールから明示的な連鎖を組み立てることです。顧客レコードやテンプレートの言語から、たいていはすでに分かっているはずです:

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');
  // 絵文字、記号、上でカバーしていないスクリプトは引き続き
  // 組み込み候補を通る。ここで0を渡すとそれを禁じられる
  Lib.SetAutomaticFontFallback(1);
end;

文書ごとに1回、最初のDrawTextの前に呼びます。明示リスト内の順序も同じ意味を持ちます。文字をカバーした最初のフォントが勝つため、Arial Unicode MSのようなパンUnicodeフォントは、置くなら最後です。最初に置くとほとんどすべてを描いてしまい、注意して選んだスクリプト別フォントは一生顧みられません

フォールバックはクラスタ単位で働く

PDF Library for Delphiは書記素クラスタ単位でフォールバックを決めるため、1つのクラスタは必ず1つのフォントで描かれます。デーヴァナーガル文字の1音節、肌の色修飾子付き絵文字、結合アクセント付きの基底文字。どれも画面上は1つの単位であり、その内側のシェーピング判断は特定の1フォントのテーブルから来ます。クラスタの半分をArial、もう半分をフォールバックフォントで描くと、技術的には存在するのに見た目は壊れたグリフがページに載ります。空白より悪いと言ってもよいでしょう

まず選択されたフォントが文字列をシェーピングします。グリフ0として返ってきたクラスタだけが別のフォントを探しに行き、同じフォントに解決した隣接クラスタは1つの実行としてまとめて描かれます。10文字の中国語の名前は、10回のフォント切り替えではなく、1つのYaHei実行になります。右から左の順序も保持されます。アラビア語やヘブライ語のテキストの中のフォールバック実行は、双方向アルゴリズムが置いた場所に座ります。同じシェーピング機構が日本語と中国語の縦書きも駆動しています

PDF Library for Delphi: フォールバック連鎖の図。CJK クラスタ列が一次フォント Arial に見つからず、最初の代替 Microsoft YaHei で描画され、未カバーのクラスタはレポートまたは中止ポリシーに従う
このクラスタ実行では、プライマリのフォントから最初に対応できるフォールバックフォントへ処理が引き継がれ、実際に使用されたフォントだけが埋め込まれます。どのフォントも描画できないクラスタは欠落グリフポリシーに従い、報告して続行するか、エラー 521 で中止します

欠落グリフで文書を止めるべきか

文書の目的次第であり、PDF Library for DelphiはSetMissingGlyphPolicyで選択できます。PDF_MISSING_GLYPH_REPORTが既定です。テキスト操作はそのまま進み、どのフォントも描けない文字は出力から落ちて、1つ1つが記録されます。PDF_MISSING_GLYPH_ABORTは何かがページに書かれる前にテキスト操作全体を拒否し、DrawTextは0を返し、エラーコードは521(PDFLIB_ERROR_MISSING_GLYPH)になります

社内向けのバッチレポートなら、レポートポリシーを選んで欠落をログに残します。今日は少し不完全なレポートのほうが、レポートゼロよりましです。契約書、請求書、証明書、そして人名や会社名を載せるものすべてには、中止を選びます。取引先名で1文字落ちるのは、自分のパイプラインの中で見つけたい不具合であり、中止は書き込みの前に起こるため、半分だけ描かれた行がページに残りません

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をログします。1回だけ読み、値を保持してください

レポートの各イベントは、ページ、文字列内のUTF-16インデックス、10進とU+XXXX形式のコードポイント、選択されたフォント、その種類、問題に当たったAPI呼び出しを運びます。これがあればサポートチケットは症状の説明ではなく正確な文字を名指せます。validフラグはイベントが1つも記録されていないときだけtrueになり、バッチジョブの安価なゲートになります

ライブラリは最新256イベントを保持し、古いものは落とします。描画不能なテキストだらけの文書が、診断をメモリ問題に変えることはありません。イベントは同じTPDFlibインスタンス上の文書をまたいで蓄積するため、ファイルごとに1レポート欲しければ各文書の前にClearMissingGlyphReportを呼ぶか、documentIndexフィールドで区別してください

文字は中止し、装飾は容認する

文書全体に1つのポリシーというのは、ときに粗すぎます。配送ラベルが受取人名の隣に装飾の絵文字を載せているなら、ラベルを拒否するより絵文字を落とすほうがいい。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と同じクラスタ単位のフォールバック判断を通ります。当たり前に聞こえますが、まさにここが自作フォールバック層がしくじる場所です。描画呼び出しだけ直して計測は一次フォントのままにするため、右揃えの合計やテーブル列がすべて、ページに載るものと一致しない幅で計算されます。ここでは描画前に計測した文字列は、フォールバック実行込みで、計測時の幅を占有します。だからこそ、手作業で監査したテンプレートだけではなく、どこでもフォールバックを有効のままにして差し支えないのです

中止ポリシーでの帰結が1つあります。計測が解決不能な文字に当たると、GetTextWidthは0を返し、エラー521を設定します。幅で割ったり、幅からセルのサイズを決めたりするレイアウトコードは、その数値を使う前に確認してください

フォールバックフォントは、実際に何かを描いたときだけ埋め込まれます。連鎖の中で1つもクラスタを解決しなかったフォントはファイルに何も加えず、描いたフォントは描いたグリフのサブセットとして埋め込まれます。5,000のLatin文字の中に1文字だけ漢字がある文書は、数メガバイトのCJKフォントではなく漢字グリフ1つを運びます。そのサブセットの組み立て方はファイルサイズ最適化とフォントサブセット化が扱います。だからこそ、提供する全ロケールをカバーする長い連鎖を設定するのは安上がりで、各PDFは使った分だけを支払います。他の場所で作られ、埋め込みもしないのにフォントを参照するファイルは別種の修復であり、既存PDFへの欠落フォント埋め込みで述べています

配置時の注意は見落としやすいものです。フォールバックは、コードを実行するマシンにインストールされたフォントを頼りに解決します。Office一式入りの開発ワークステーションは、薄いサーバーイメージやコンテナよりはるかに多くのフォントを持っています。Yu GothicやMicrosoft YaHeiがそこになければ、連鎖には頼る先がありません。漢字名、ハングル名、絵文字をそれぞれ含んだ文書を1つ、対象サーバーで実行しJSONレポートを読んでください。そこでevents配列が空なら、自分のデスクトップでのどんなテストより多くを教えてくれます。依存するフォントを添付して出荷し、ライセンスが埋め込みを許すかも確認してください

同じフォールバック連鎖、欠落グリフポリシー、レポートはDLL版とActiveX版からも公開されており、C#、C++、スクリプトの呼び出し側も同じ呼び出しで設定できます。リファレンス文書とダウンロードはPDF Library for Delphiの製品ページにあります