HotPDF: XFA, AcroForm, and flattening decisions в Delphi

HotPDF — нативная VCL PDF-библиотека для приложений Delphi и C++Builder, которым нужны прямое создание и редактирование PDF, формы, аннотации, шифрование, цифровые подписи, Unicode-шрифты, вывод с учетом стандартов и preflight-отчеты без внешнего PDF-runtime.

Эта статья предназначена для 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.

inspect the document catalog and form dictionaries before loading values
classify the form model and choose a profile that matches the business goal
apply values, refresh appearances, and validate required fields
flatten only the fields approved by policy and verify remaining interactivity
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