LlosLab Software Development BlogEngineering notes for PDF, Delphi, and document software developers.

技術記事

HotPDF Component: Delphi での XFA, AcroForm, and flattening decisions

HotPDF Component

HotPDF は Delphi/C++Builder アプリケーション向けのネイティブ VCL PDF ライブラリです。外部 PDF ランタイムを配置せずに、PDF 作成、編集、フォーム、注釈、暗号化、デジタル署名、Unicode フォント、標準対応出力、プリフライトレポートを扱えます。

この記事は teams receiving mixed form documents that must be archived, reviewed, or converted by a Delphi workflow 向けです。XFA, AcroForm, and flattening decisions を単なるコンポーネント呼び出しではなく、本番向けのドキュメントエンジニアリングとして扱います。

実務上のリスクは dynamic XFA, static XFA, and AcroForm fields behave differently, so a naive flattening step can lose values or preserve hidden state unexpectedly です。そのため、明確な契約、観測可能な診断、実際の顧客ファイルに近い回帰サンプルが必要です。

アーキテクチャ上の判断

Identify the form technology before changing it. how to classify AcroForm, static XFA, dynamic XFA, and hybrid forms / whether unsupported dynamic behavior blocks processing or creates a warning

  • how to classify AcroForm, static XFA, dynamic XFA, and hybrid forms
  • whether unsupported dynamic behavior blocks processing or creates a warning
  • appearance refresh policy for changed values and calculated fields
  • retention of original form data after a flattened archive copy is produced

実装フロー

Refresh visible appearances before flattening. The order below keeps the workflow reviewable for Delphi and C++Builder teams.

  1. inspect the document catalog and form dictionaries before loading values
  2. classify the form model and choose a profile that matches the business goal
  3. apply values, refresh appearances, and validate required fields
  4. flatten only the fields approved by policy and verify remaining interactivity
  5. save the classification and flattening result in the support report

検証エビデンス

Flattening evidence for auditors and support. Keep these fields with the output or support record.

  • form model classification, field count, XFA presence, and unsupported feature list
  • appearance refresh status for every field changed by the workflow
  • flattened field count, remaining interactive field count, and output hash
  • side-by-side viewer result for at least one customer-like form

Flattening is a finalization step

Flattening should happen only after the workflow knows which form model owns the value, which appearance is authoritative, and whether the resulting PDF must remain interactive or become a static record.

Regression files worth keeping

Keep more than successful samples. A useful XFA, AcroForm, and flattening decisions regression set contains normal files, boundary files, and intentional failure files so the behavior is stable across releases.

  • dynamic XFA forms may depend on behavior outside normal AcroForm processing
  • hidden fields can contain values that should not appear in a flattened copy
  • flattening invalid values can make correction impossible for downstream users
  • different viewers may choose different appearances when streams are stale
  • inspect the document catalog and form dictionaries before loading values
  • classify the form model and choose a profile that matches the business goal

XFA, AcroForm, and flattening decisions に関する技術レビューの注意点

これらのレビュー項目を使って、機能がデモ段階を超え、リリース、サポート、顧客エスカレーションの場で説明できることを確認します

  • 判断: how to classify AcroForm, static XFA, dynamic XFA, and hybrid forms. 実装上の焦点: classify the form model and choose a profile that matches the business goal. 受け入れ証拠: flattened field count, remaining interactive field count, and output hash. 回帰の引き金: different viewers may choose different appearances when streams are stale
  • 判断: whether unsupported dynamic behavior blocks processing or creates a warning. 実装上の焦点: apply values, refresh appearances, and validate required fields. 受け入れ証拠: side-by-side viewer result for at least one customer-like form. 回帰の引き金: dynamic XFA forms may depend on behavior outside normal AcroForm processing
  • 判断: appearance refresh policy for changed values and calculated fields. 実装上の焦点: flatten only the fields approved by policy and verify remaining interactivity. 受け入れ証拠: form model classification, field count, XFA presence, and unsupported feature list. 回帰の引き金: hidden fields can contain values that should not appear in a flattened copy
  • 判断: retention of original form data after a flattened archive copy is produced. 実装上の焦点: save the classification and flattening result in the support report. 受け入れ証拠: appearance refresh status for every field changed by the workflow. 回帰の引き金: flattening invalid values can make correction impossible for downstream users
  • 判断: how to classify AcroForm, static XFA, dynamic XFA, and hybrid forms. 実装上の焦点: inspect the document catalog and form dictionaries before loading values. 受け入れ証拠: flattened field count, remaining interactive field count, and output hash. 回帰の引き金: different viewers may choose different appearances when streams are stale

境界ケース

  • dynamic XFA forms may depend on behavior outside normal AcroForm processing
  • hidden fields can contain values that should not appear in a flattened copy
  • flattening invalid values can make correction impossible for downstream users
  • different viewers may choose different appearances when streams are stale

Delphi / C++Builder の補足

HotPDF Component should sit behind a small service boundary that receives files, streams, profiles, and credentials, then returns output paths, warnings, metrics, and validation status. 重要な用語には XFA, AcroForm, flattening, appearance stream, field value, archive copy.

Delphi コード例

次の Delphi スケッチは、このテーマに対する実用的なサービス境界を示します。ポリシー確認、ログ記録、検証を製品呼び出しの狭い部分の外側に置くと、ワークフローをテストしやすくなります。

procedure FlattenIncomingForm(const InputFile, OutputFile: string; const Policy: TFormPolicy);
var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    LoadCustomerForm(Pdf, InputFile);
    NormalizeXfaPackets(Pdf, Policy);
    FlattenVisibleAcroFormFields(Pdf);
    SaveFlattenedCopy(Pdf, OutputFile);
    VerifyNoEditableFields(OutputFile);
  finally
    Pdf.Free;
  end;
end;

本番チェックリスト

  • ワークフローは、空のファイル、通常の顧客ファイル、最悪ケースのファイルで実行します
  • 生成された PDF は、対象のビューアー、検証ツール、プリンター、または downstream アプリケーションで開きます
  • 製品バージョン、プロファイルバージョン、入力ハッシュ、出力パス、経過時間、警告数を記録します
  • パスワード、証明書、一時ファイル、顧客データは明確な保持ルールの下で管理します
  • 顧客ファイルが新しい境界ケースを示したら、回帰用ドキュメントを追加します

製品ドキュメント

HotPDF Component

追加のコード例

XDPBytes := TFile.ReadAllBytes('benefit-claim.xdp');
MappedCount := Pdf.ApplyXFAAsAcroForm(XDPBytes, True);
// Lock the value at field creation: read-only text field
Pdf.CurrentPage.AddTextField('CaseNumber', 'BC-2026-0117',
  Rect(50, 700, 220, 720), 0, [ffReadOnly]);

// Belt and suspenders: restrict form filling document-wide
Pdf.ActivateProtection := True;
Pdf.CryptKeyLength := aes256;
Pdf.OwnerPassword := 'records-owner';
Pdf.ProtectOptions := [prPrint, prInformationCopy, prExtractContent];
// fill permission withheld: prFillAnnotations is absent from the set