技術記事

PDFium ComponentのXFA保存:改行、絵文字、restoreState

XFA の請求フォームで空だった Comments 欄が、1個の改行を抱えて再オープンされます。もう一度保存して開き直すと、今度は2個入っています。U+1F642(ほほえみ顔)で打ち込んだ顧客名が、U+F642、つまり多くのフォントが空の四角として描く私用領域のコードポイントで戻ってくることもあります。この3つの症状はみな、XFA 保存が datasets パケットへ書き込む XML に住んでいます。正しく扱う保存経路は、レイアウト用の空白をフィールド値から締め出し、追加面の文字を完全なサロゲートペアで運び、失敗した書き込みを壊れたファイルではなく保存結果で報告できなければなりません

どのPDFiumランタイムがXFAの値を保存できるのか

XFA 値を保存できるのは pdfium.v8.dll だけです。V8 JavaScript エンジンと XFA フォームランタイムの両方を載せた PDFium Component ビルドは、これ1つだからです。編集がコミットされると(フィールドがフォーカスを失うか、ClearFormFieldFocus がコミットを強制する)、そのランタイムは保存時に生の XFA データを datasets パケットへエクスポートします。コードでパケットを手術する必要はありません。各 Windows アーキテクチャには、V8 と XFA なしでビルドされた pdfium.dll も同梱され、これは格納済みのパケットを読んだとおりに書き戻します。フィールドにフォーカスがある間に書かれた値がどうなるかは、XFA フィールド編集が保存で消える理由で扱っています

Delphi ラッパーは、適切なライブラリをこちらの代わりに選ぼうとします。EnableV8Engine がまだ False で、PDFium ライブラリがまだロードされていないとき、TPdf はこれから開くファイルを見て、XFA の印(AcroForm 辞書の /XFA エントリ、カタログの /NeedsRendering true)を見つけると、ロードの前に EnableV8Engine を ON にします。この切替はプロセスごとに1回しか効きません。セッションの最初の文書が普通の PDF だったせいで pdfium.dll がすでに常駐していると、プロセスはそれに固定され、後から XFA 文書が来たときに TPdf.OnXfaRuntimeMissing が発火します

既定の検索順序が問題のもう半分です。LibraryName にディレクトリがないと、ローダーはアプリケーションフォルダかその親の1つにある DLLs\Win32 か DLLs\Win64 フォルダから探し始めるので、古い pdfium.v8.dll が先に見つかることがあります。ディレクトリを含む LibraryName は、まさにそのファイルに固定され、それが無ければロードは失敗します

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  //  LibraryName の中のディレクトリ指定は、まさにこのファイルに固定する。
  //  ファイルがなければ、フォールバックではなく例外で失敗する
{$IFDEF WIN64}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win64\pdfium.v8.dll';
{$ELSE}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win32\pdfium.v8.dll';
{$ENDIF}
  PDFium.EnableV8Engine := True;
  PDFium.LoadLibrary;  //  最初の保存ではなく、起動時に失敗させる
end;

ドキュメントを開いた後、TPdf.XFA はファイルが XFA を含むことを告げ、TPdf.XfaRuntimeAvailable はロードされたライブラリが、この文書に対して実際に XFA エンジンを始動できたことを告げます。静的フォームと動的フォームの区別は TPdf.FormType で付き、動的フォームには ftXfaFull、静的フォームには ftXfaForeground が返ります。V8 ランタイムのないマシンでのパケットレベルの調べ方は、DelphiでのXFAフォームの検出とXFAパケットの抽出が主題です

保存したXFAフィールドに余計な改行が積もるのはなぜか

保存した XFA フィールドに改行が積もるのは、ライターが各 start タグの後に改行を入れて XML を整列出力するときです。XFA 保存には2つのライターが関わり、汎用の XML 要素ライターとフォームパケットシリアライザの両方が、その癖で出力を整形します。ほとんどの XML 文書ではこの空白は化粧ですが、XFA データではそれが値そのものです。datasets パケットがもう一度パースされると、<Comments> と </Comments> の間の文字は、改行も含めて全部フィールドのものになります

PDFium Component の XFA 保存サイクルの図:ライターが start タグの後に改行を加え、再オープンしたパーサが Comments タグ間の LF をフィールド値として読み、ライターが自分の合成した空白だけを取り除かない限り、以降の保存がさらに改行を1個足す
1回の保存と再オープンのサイクルが最初の改行を植え付け、以降の周回がさらに1個足します。ズレの全体像が見えるのは第2世代になってからです

したがって空のフィールドは、LF を1個抱えた状態で再オープンされます。以降の保存はその LF の周りを整形するので、誰も触れていないフィールドが、レビュー1周につき1行ずつ育ちます

ロード時に値を切り詰めるのは安易な修復に見えますが、本物のデータを壊します。人は XFA フィールドに先行スペース、末尾スペース、意図的な改行を打ち込みます。住所ブロックは行構造を保たねばならず、固定幅の参照コードはバイト単位で生き延びねばなりません。PDFium Component の XFA ライターはその代わり、シリアライザ自身がタグの周りで合成した空白だけを落とします。ユーザーの値、ファイルに既にあったテキストノード、CDATA セクションはそのまま通るので、" indented" はインデントを保ち、意図的に空にしたフィールドは空のままです

絵文字、サロゲートペア、16ビットのwchar_t

絵文字が別の文字として戻ってくるのは、デコード経路が Unicode スカラー値まるごとを1個の wchar_t(Windows では16ビット幅)に格納するときです。XFA ロードにはこの露出が2箇所あります。UTF-8 ストリームデコーダと、&#x1F642; のような数値文字参照のパーサです。U+1F642 は17ビット必要です。16に押し込めると上位ビットが落ち、U+F642 が私用領域に残ります

フォームシリアライザは逆方向に失敗することもあります。1個ずつ wchar_t をふるいにかけるやり方では、サロゲートコードユニット2個、D83D と DE42 が見えます。それぞれ単独では不正なので、両方とも落とされます。絵文字はフォームパケットから消え、置換文字すら残りません

PDFium Component のサロゲート処理の図:U+1F642 は UTF-16 ペア D83D DE42 として届き、素朴な2つの経路がこれを壊し得る。16ビット wchar_t のデコーダはスカラーを私用領域の U+F642 へ切り詰め、単独サロゲートをふるい落とすシリアライザは絵文字を丸ごと消す
Windows の wchar_t は16ビット幅です。サロゲートペアを要するスカラーは、両経路がペアを一緒に保たない限り、上位半分を失うか、パケットから消えます

PDFium Component では、デコーダは各スカラー値を完全に消費し、正しいサロゲートペアを出力します。出力バッファの空きがあと1ユニットしかないときも、4バイトの UTF-8 シーケンスが2つの読み取りブロックに分断されているときも、同じです。出力側では、フォームエクスポータが有効なサロゲートペアを一緒に保ち、数値文字参照も正しいペアにデコードします

Latin-1 のテストデータは、これらの経路をどれも通過しません。XFA フォームのラウンドトリップテストには、テキストフィールドに U+FFFF を超える文字が少なくとも1個必要です。そして保存されたバイトに4バイトの UTF-8 シーケンス F0 9F 99 82 があることを確認するほうが、描画されたフィールドを見るより多くを物語ります

単一ストリームXFAと保存結果

単一ストリームの XFA 文書が編集を保つのは、保存経路が1本の XDP ストリームをその場で書き直せるときだけです。そして書き直せない入力は、保存を失敗させなければなりません。ISO 32000-1 §12.7.8 は、対話フォーム辞書の /XFA エントリを、パケット名とストリームを交互に並べる配列としても、XDP 文書全体を抱える単一ストリームとしても許しています。配列専用に書かれた保存経路は単一ストリームを拒み、呼び出し側がその結果を無視すると、フォームデータは古い値のまま PDF が書き出されます

PDFium Component の V8 ランタイムは、定義済みの単一ストリーム部分集合を3ステップで扱います。生きている2つのパケット、datasets と form をステージング領域へエクスポートして検証する。その後で初めて、元の XDP の対応するパケットを置き換える。他のパケットとルートの名前空間宣言は保持します。ステージングが失敗すれば、永続的な XFA ストリームには決して触れず、文書は変更マークを保つので、後の保存が再挑戦できます

PDFium Component の単一ストリーム XFA 保存パイプライン:生きている datasets と form パケットをステージングへエクスポートし、検証し、コメントをマーカーで保持しながら元の XDP の内側で置き換える。ステージングの失敗や、DTD、XMLDSig といった入力は保存を明示的に拒否する
ステージング済みのエクスポートは、何かを置き換える前に検証されます。だから失敗した保存は永続的な XFA ストリームを触らず、文書は変更マークを保ちます

XML コメントと処理命令には余分な手当てが要ります。書き直しに使うパーサがそれらを落とすからです。各コメントと処理命令は、パースの前に一意なマーカーと交換され、後で戻されます。そしてすべてのマーカーがちょうど1回ずつ現れたときにだけ、ストリームは書き出されます。生きているパケットの外側のコメントは、テキストも順序も保たれます

一部の入力はその場で拒否され、各拒否は失敗した保存として届きます

  • 生きているdatasetsかformパケットの内側のコメントや処理命令。元の位置を新しくエクスポートしたコンテンツへ写像できないからです
  • DTD宣言とXMLDSig署名。XDPの書き直しは、XML署名を有効なまま保てないからです
  • 不正なUTF-8やUTF-16のエンコーディング、不完全なタグ、不正な文字参照、未知の実体、奇形の処理命令は、黙って修理する代わりに拒否されます

拒否のほうが良い取引です。False を返す保存は、再試行も記録も人の手への引き渡しもできます。一方、黙って正規化された XDP は、数週間後、変更したコードから遠く離れた場所で、署名や下流のインポーターを壊しかねません。単一ストリーム経路が保つのは XML のコンテンツモデルで、UTF-8 で書かれます。ソースストリームの元のバイトレイアウトとエンコーディング宣言は引き継がれません

最後にバッファされたブロック

最後の罠は XFA の下、汎用の PDF ライターに座っています。出力を固定サイズのブロックでバッファするファイルライターは、最後の端数ブロックを最後に押し出さなければなりません。それが、文書ライターがすでに成功を報告した後のクリーンアップコードで起こると、最終ブロックでのディスクフルや I/O エラーは呼び出し側に届かず、ディスク上のファイルは短いままです。PDFium Component の両ランタイムでは、最終フラッシュは保存結果の一部であり、XFA の変更マークは、書き込みが本当に成功した後にだけクリアされます

Delphi 側にはもう1層あります。TPdf.SaveAs はターゲットの隣の一時ファイルへ書き込み、ストリーム保存が True を返したときだけ、それをターゲットの上へ動かします。False の結果は前のファイルを元どおりに残し、最後の置換の失敗は、黙って返る代わりに OS エラーを上げます

動的XFAフォームがより少ないページ数で再オープンするのはなぜか

動的 XFA フォームがより少ないページ数で再オープンするのは、ルートサブフォームが restoreState="auto" を宣言していないときで、この判断はフォームオーサリングに属します。XFA 3.3 では、ルートサブフォームの restoreState の既定は manual です。manual の下では、XFA プロセッサは保存済みフォームパケットから限られた状態だけを復元し、残りをフォーム自身のスクリプトに委ねます。フィールド値と繰り返しサブフォームのインスタンス数は戻りますが、実行時に設定された幾何プロパティは戻りません

ユーザーが記入している間に、スクリプトがサブフォームを h="450pt" まで伸ばす3ページのフォームを考えてみます。保存されたフォームパケットは、新しい高さとフィールド値とインスタンス数を保持します。再オープンでは、レイアウトはテンプレートの高さから組み立て直され、サブフォームは縮み、コンテンツは2ページへ再流し込みされます。テンプレートが自動復元を要求したことがないときに、XFA 仕様が求める動作はまさにこれです。ルートサブフォームで宣言すると、再オープンは変わります

<template xmlns="http:// www.xfa.org/schema/xfa-template/3.3/">
  <subform name="form1" layout="tb" restoreState="auto">
    <pageSet>
      <pageArea name="Page1">
        <contentArea x="0.25in" y="0.25in" w="8in" h="10.5in"/>
        <medium stock="letter"/>
      </pageArea>
    </pageSet>
    <subform name="Details" layout="tb" w="7.5in">
      <!-- fields; scripts may change h or add instances at run time -->
    </subform>
  </subform>
</template>

テンプレートを所有していないなら、手を出さないでください。manual モード向けに作られたフォームは、状態を組み立て直すのは自分の初期化スクリプトだと期待しており、その足元でモードを切り替えると、スクリプトが前提としていたものが変わります。ユーザーが打っている間のライブ再ページングは別のメカニズムで、PDFium Componentが動的XFAのページ数と移動したフィールドを追跡する仕組みで説明しています

DelphiからXFAのラウンドトリップを検証する

XFA 保存の検証は、保存済みファイルを新しい TPdf インスタンスで開き直して格納データを読み戻すことで行います。SaveAs の True は、ファイルが書かれたことしか言わないからです。TPdf.GetXfaDatasets は、生のデータモデルではなく、文書に格納されたとおりの datasets パケットを返します。保存の前に読むと前回のロード値が見え、再オープンの後には、書かれたものが正確に見えます。単一ストリームの文書には個別の名前付きパケットがありません。PDFium は XDP 全体を空の名前の1パケットとして報告するので、GetXfaPacketByName('datasets') も GetXfaDatasets も空の配列を返し、下のコードは GetXfaFormPackets からの完全なストリームへフォールバックします

uses
  System.SysUtils, PDFium, FPdfXfa;

function ReadSavedXfaData(const FileName: string): string;
var
  Pdf: TPdf;
  Packets: TXfaPacketList;
  Bytes: TBytes;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    Bytes := Pdf.GetXfaDatasets;          //  パケット配列レイアウト
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   //  単一ストリーム:名前なしパケット1つ
      if Length(Packets) = 1 then
      begin
        SetLength(Bytes, Length(Packets[0].Content));
        if Length(Bytes) > 0 then
          Move(Packets[0].Content[0], Bytes[0], Length(Bytes));
      end;
    end;
    Result := TEncoding.UTF8.GetString(Bytes);  //  保存されたXDP出力はUTF-8
  finally
    Pdf.Free;
  end;
end;

保存ルーチンは、保留中の編集をコミットし、SaveAs の結果をチェックし、開き直した値と比較します。TPdf.ClearFormFieldFocus はフォームフォーカスを取り除きます。PDFium がフォーカス中フィールドの編集バッファをコミットするのはこのときです。TPdf.SetFocusedFormFieldText はコードからフォーカス中フィールドを埋められますが、これはウィジェット注釈を通って追跡されるフォーカスに依存しており、動的 XFA ページには通常それがありません。そこでは False が返り、テキストは普段どおり TPdfView でのキーボード入力から届きます

//  XmlText は自分で足すヘルパー。PDFium Component の一部ではない
function XmlText(const S: string): string;
begin
  Result := StringReplace(S, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [rfReplaceAll]);
end;

procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
  Expected: string);
var
  Saved: string;
begin
  //  任意のスクリプトによる記入。False は追跡対象フィールドにフォーカスがないこと
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              //  編集バッファをコミットする
  if not Pdf.SaveAs(FileName) then      //  False:前のファイルは元の位置に残る
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  //  新しい TPdf で開き直し、要素テキストが正確にあるか確かめる
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

部分文字列テストはスモークテストにすぎません。空の要素は <Tag/> と書かれることもあり、データ要素は属性を運べるし、& と < を越えたエスケープはシリアライザ次第です。だから本番のチェックは本物の XML パーサの中に置くべきです。同じ入力でルーチンを2回続けて走らせてください。改行のズレが全体の姿を見せるのは第2世代だからです

XFA ランタイムを直接動かすホストアプリケーションには、ランタイムが期待するコールバック構造も必要です。これは DelphiにおけるFPDF_FORMFILLINFOバージョン2とXFA ABI の主題です。Win32 と Win64 の両 Windows ランタイム、Delphi と C++Builder のラッパー、TPdfView ビューアーコントロールは、PDFium Component for Delphi and C++Builder に同梱されます