Dieser deutsche Artikel behandelt XFA-zu-AcroForm-Flattening in Delphi mit HotPDF für Teams, die mit Delphi, C++Builder, Lazarus/FPC und losLab-Komponenten arbeiten
Zwei scheinbar ähnliche Formularmodelle
AcroForm ist in ISO 32000-1 §12.7 definiert und speichert jedes Feld als PDF-Objekt mit Widget-Annotationen und Appearance-Stream; die sichtbare Seite ist der tatsächliche PDF-Inhalt, worüber die Formulardaten liegen. XFA verwendet den umgekehrten Weg: Das Formular ist ein XML-Dokument, das als XDP-Paket im AcroForm-Dictionary unter dem XFA-Eintrag liegt, und die sichtbare Seite wird beim Öffnen von der XFA-Layout-Engine generiert. In dynamischen XFA-Formularen ist die PDF-Seite im Dokument nur eine "Please wait"-Platzhalterseite, da der tatsächliche Inhalt nie in PDF-Form existierte
AcroForm, definiert in ISO 32000-1 §12.7, speichert jedes Feld als PDF-Objekt mit Widget-Annotation und Appearance Stream; die sichtbare Seite ist echter PDF-Inhalt, und die Formulardaten liegen darüber. XFA geht den entgegengesetzten Weg: Das Formular ist ein XML-Dokument, ein XDP-Paket im -Eintrag des AcroForm-Dictionary, und die sichtbaren Seiten werden beim Öffnen von einer XFA-Layout-Engine erzeugt. In einem dynamischen XFA-Formular sind die PDF-Seiten in der Datei nichts als der „Please wait“-Platzhalter, weil der eigentliche Inhalt nie als PDF existierte
Die beiden Modelle schließen sich praktisch aus: Ein Dokument wird entweder als XFA oder als AcroForm verarbeitet, und Werkzeuge, die den -Eintrag ignorieren, sehen nur die Platzhalterhülle. ISO 32000-2 hat die Debatte beendet, indem XFA in PDF 2.0 vollständig als veraltet eingestuft wurde. Deshalb ist „in AcroForm konvertieren, solange wir es noch können“ zu einer normalen Eingangsanforderung geworden, nicht zu einer exotischen
Flatten Sie geladene XFA-Dokumente zu nativen Feldern ab
Der Konvertierungseinstiegspunkt von HotPDF arbeitet auf geladenen Dokumenten. analysiert XFA-Templates und Datenpakete, layoutet das Formular und rekonstruiert es als echte AcroForm-Felder auf einer echten PDF-Seite:
var
Pdf: THotPDF;
MappedCount, I: Integer;
Warnings: TStrings;
begin
Pdf := THotPDF.Create(nil);
try
Pdf.LoadFromFile('dynamic_xfa.pdf');
MappedCount := Pdf.FlattenLoadedXFA(True); // True = fields stay editable
Warnings := Pdf.XFAFlattenWarnings;
for I := 0 to Warnings.Count - 1 do
Log('XFA flatten warning: ' + Warnings[I]); // unmapped elements
Pdf.SaveLoadedDocument('native_acroform.pdf');
Log(Format('Mapped %d fields', [MappedCount]));
finally
Pdf.Free;
end;
end;HotPDFs Konvertierungseinstieg arbeitet auf einem geladenen Dokument. FlattenLoadedXFA parst die XFA-Template- und Datenpakete, layoutet das Formular und baut es als echte AcroForm-Felder auf echten PDF-Seiten neu auf:
Behandeln Sie Rückgabewert und Warnliste als Teil der Ausgabe, nicht als Debug-Rauschen. Die Konvertierung ist inhärent verlustbehaftet: XFA-Scripting, berechnete Felder und dynamisches Subform-Verhalten haben kein AcroForm-Äquivalent, und XFAFlattenWarnings zählt genau auf, welche Template-Elemente nicht abgebildet werden konnten. Eine Pipeline, die die konvertierte Datei archiviert, ohne die Warnliste zu archivieren, wird irgendwann vor der Frage stehen, warum das Summenfeld in der Archivkopie leer ist, ohne eine aufgezeichnete Antwort zu besitzen. Der Parameter Editable entscheidet, ob die resultierenden AcroForm-Felder ausfüllbar bleiben; übergeben Sie True, wenn nachgelagert weiter mit dem Formular gearbeitet wird, und False-äquivalente Richtlinien, wenn das Ziel ein fester Datensatz ist
Arbeiten von der XDP-Seite
Manchmal ist die Eingabe kein ausgefülltes PDF, sondern ein von einem Formulargestaltungswerkzeug exportiertes XDP-Paket oder ein vom System eines Partners gesendetes XDP-Paket. überspringt den Ladeschritt und wendet das Paket direkt auf das aktuelle Dokument an:
XDPBytes := TFile.ReadAllBytes('benefit-claim.xdp');
MappedCount := Pdf.ApplyXFAAsAcroForm(XDPBytes, True);Manchmal ist die Eingabe kein ausgefülltes PDF, sondern das XDP-Paket selbst, exportiert aus einem Formularentwurfswerkzeug oder von einem Partnersystem empfangen. ApplyXFAAsAcroForm überspringt den Ladeschritt und wendet das Paket direkt auf das aktuelle Dokument an:
Eine andere Art der Abflachung: Ehrliche Angabe von AcroForm-Inhalten
„Flatten“ hat eine zweite Bedeutung, die immer wieder zu Verwirrung führt: Das Einbrennen des AcroForm-Feld-Appearances in den Seiteninhaltsstrom, sodass keine interaktiven Objekte mehr in der Datei vorhanden sind. HotPDF bietet derzeit keine API für diese Operation an, daher plant man am besten um diese Tatsache herum, anstatt es mitten im Projekt zu entdecken. Die Bibliothek bietet Feldsperrung auf Feldebene während der Erstellung sowie Dokumentenberechtigungen:
// 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„Flatten“ hat eine zweite Bedeutung, die regelmäßig Verwirrung verursacht: AcroForm-Feld-Appearances in den Seiten-Content-Stream einbrennen, sodass keine interaktiven Objekte übrig bleiben. HotPDF bietet dafür derzeit keine API, und es ist besser, diese Tatsache einzuplanen, als sie mitten im Projekt zu entdecken. Was die Bibliothek anbietet, sind Feldsperren bei der Erstellung plus Dokumentberechtigungen:
Archivierungsfolgen: XFA und Konformitätsstandards
Sowohl PDF/A als auch PDF/X lehnen XFA direkt ab. Daher muss eine in die ISO 19005-Archivierung eingehende Pipeline zuerst konvertieren und dann validieren, und zwar in einer festen Reihenfolge: Laden, , Speichern und anschließendes Ausführen des Archivierungserstellungs- oder Validierungsprozesses auf dem AcroForm-Ergebnis. Verwenden Sie veraPDF, um die konvertierte Ausgabe zu validieren, anstatt davon auszugehen, dass Konvertierung gleich Konformität ist; die Konvertierung repariert das Formularmodell, nicht Schriftarten, Farben oder Metadaten. Das Feldverhalten auf der AcroForm-Seite, JavaScript-Trigger, Sendeaktionen und Validierungsskripte haben ihren eigenen Werkzeugkasten, siehe HotPDF-AcroForm-Felder und -Aktionen
FAQ
Warum zeigt mein PDF-Formular nur die Seite "Please wait"?
Es handelt sich um ein dynamisches XFA-Formular, und Ihr Viewer hat keinen XFA-Prozessor. Der sichtbare PDF-Inhalt ist nur eine Platzhalterseite; Sie sollten verwenden, um das Dokument zu konvertieren, um Seiten und Felder zu erhalten, die jeder Viewer rendern kann
Behält FlattenLoadedXFA Berechnungen und Skripte bei?
Nein. XFA-Skripte und dynamische Layoutlogik können nicht in AcroForm konvertiert werden. Bereits vorhandene berechnete Werte in den Formulardaten werden als statische Werte übernommen, und listet jedes Element auf, das nicht zugeordnet werden konnte. Überprüfen Sie diese Liste, bevor Sie der Ausgabe vertrauen
Kann HotPDF Formulare vollständig nicht-interaktiv machen?
Dies kann nicht über ein Ein-Klick-Flatten erreicht werden: Es gibt keine API zur Abflachung von AcroForm-Inhalten. Wenn Manipulationssicherheit erforderlich ist, können -Felder und Berechtigungsbeschränkungen kombiniert werden. Wenn Null Formularobjekte eine harte Anforderung sind, sollte das Dokument neu generiert und die Werte als normaler Text gezeichnet werden
Produktreferenz
Die XFA-Registrierungs-, Konvertierungs- und Formular-APIs in diesem Artikel gehören zur HotPDF-Komponente für Delphi und C++Builder; ihre Dokumentation verfolgt den kontinuierlich wachsenden XFA-Funktionssatz über die letzten Versionen hinweg