Technischer Artikel

PDFium Component XFA Save: Newlines, Emoji und restoreState

Eine leere Kommentare-Box auf einem XFA-Claim-Formular öffnet sich wieder mit einem einzelnen Linefeed. Sichert und öffnet man sie erneut, hält sie zwei. Ein Kundenname, der mit U+1F642, dem leicht lächelnden Gesicht, getippt wurde, kommt als U+F642 zurück, ein Codepunkt aus der Private Use Area, den die meisten Fonts als leeres Rechteck zeichnen. Alle drei Effekte leben im XML, das ein XFA-Sichern ins datasets-Packet schreibt, und ein Save-Pfad, der sie richtig behandelt, muss Layout-Whitespace aus Feldwerten heraushalten, Zeichen außerhalb der BMP als komplette Surrogate-Paare transportieren und einen fehlgeschlagenen Schreibvorgang über das Save-Ergebnis statt über eine beschädigte Datei melden

Welche PDFium-Runtime sichert XFA-Werte?

Nur pdfium.v8.dll sichert XFA-Werte, denn sie ist der einzige PDFium-Component-Build, der sowohl die V8-JavaScript-Engine als auch die XFA-Formular-Runtime trägt. Sobald ein Edit committet ist (das Feld hat den Fokus verloren, oder ClearFormFieldFocus hat den Commit erzwungen), exportiert diese Runtime die Live-XFA-Daten beim Sichern ins datasets-Packet, ohne dass Sie selbst am Packet operieren. Jede Windows-Architektur liefert außerdem eine pdfium.dll mit, gebaut ohne V8 und XFA, die die gespeicherten Packets exakt so zurückschreibt, wie sie sie gelesen hat. Was mit einem Wert passiert, der geschrieben wird, während das Feld noch den Fokus hat, behandelt warum XFA-Feld-Edits beim Sichern verschwinden

Der Delphi-Wrapper versucht, die richtige Bibliothek für Sie zu wählen. Ist EnableV8Engine noch False und wurde noch keine PDFium-Bibliothek geladen, schaut TPdf auf die Datei, die es gleich öffnen will, und findet es XFA-Marker (einen /XFA-Eintrag im AcroForm-Dictionary oder /NeedsRendering true im Katalog), schaltet es EnableV8Engine vor dem Laden ein. Dieser Schalter funktioniert nur einmal pro Prozess. Sitzt bereits eine gewöhnliche pdfium.dll im Prozess, weil das erste Dokument der Sitzung ein schlichtes PDF war, bleibt der Prozess ihr verpflichtet, und TPdf.OnXfaRuntimeMissing feuert, wenn später ein XFA-Dokument ankommt

Die Default-Suchreihenfolge ist die andere Hälfte des Problems. Ohne ein Verzeichnis in LibraryName startet der Loader mit einem DLLs\Win32- oder DLLs\Win64-Ordner unter dem Anwendungsordner oder einem seiner Eltern, also kann eine ältere pdfium.v8.dll zuerst gefunden werden. Ein LibraryName mit Verzeichnis nagelt exakt diese Datei fest, und fehlt sie, schlägt das Laden fehl

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // Ein Verzeichnis in LibraryName nagelt genau diese Datei fest;
  // fehlt die Datei, schlägt LoadLibrary fehl, statt woanders zu suchen
{$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;  // beim Start scheitern, nicht beim ersten XFA-Sichern
end;

Nach dem Öffnen eines Dokuments sagt TPdf.XFA, dass die Datei XFA enthält, und TPdf.XfaRuntimeAvailable, dass die geladene Bibliothek die XFA-Engine für dieses Dokument tatsächlich starten konnte. Statische und dynamische Formulare werden über TPdf.FormType auseinandergehalten, das für ein dynamisches Formular ftXfaFull und für ein statisches ftXfaForeground zurückgibt. Packet-Sondieren auf einer Maschine ohne die V8-Runtime ist das Thema von dem Erkennen von XFA-Formularen und dem Extrahieren von XFA-Packets in Delphi

Warum bekommen gesicherte XFA-Felder zusätzliche Linefeeds?

Gesicherte XFA-Felder bekommen Linefeeds, wenn der Writer sein XML mit einem Zeilenumbruch nach jedem Start-Tag hübsch druckt. An einem XFA-Sichern sind zwei Writer beteiligt, der generische XML-Element-Writer und der Form-Packet-Serializer, und beide formatieren ihre Ausgabe gewohnheitsmäßig so. In den meisten XML-Dokumenten ist dieser Whitespace kosmetisch. In XFA-Daten ist er der Wert: Wird das datasets-Packet erneut geparst, gehört jedes Zeichen zwischen <Comments> und </Comments> zum Feld, Linefeed eingeschlossen

PDFium-Component-XFA-Save-Zyklus-Diagramm, in dem der Writer nach Start-Tags einen Zeilenumbruch ergänzt, der wieder geöffnete Parser den LF zwischen den Comments-Tags als Feldwert liest, und jeder weitere Save einen weiteren Linefeed anhängt, sofern der Writer nicht nur den Whitespace entfernt, den er selbst synthetisiert hat
Ein Save-Reopen-Zyklus pflanzt den ersten Linefeed, und jede weitere Runde ergänzt einen, deshalb zeigt das Driften seine volle Gestalt erst in der zweiten Generation

Ein leeres Feld öffnet sich also wieder mit einem einzelnen LF. Jeder weitere Save formatiert um den bereits vorhandenen LF herum, also wächst ein Feld, das niemand angefasst hat, um eine Zeile pro Review-Runde

Werte beim Laden zu trimmen sieht nach einer billigen Reparatur aus, und sie würde echte Daten korrumpieren. Leute tippen führende Leerzeichen, abschließende Leerzeichen und absichtliche Zeilenumbrüche in XFA-Felder; ein Adressblock muss seine Zeilenstruktur behalten, und ein Festbreiten-Referenzcode muss Byte für Byte überleben. Die XFA-Writer in PDFium Component entfernen stattdessen nur den Whitespace, den der Serializer selbst um Tags herum synthetisiert. Nutzerwerte, Textknoten, die bereits in der Datei standen, und CDATA-Sektionen laufen unverändert durch, also bleibt " indented" eingerückt und ein absichtlich leeres Feld bleibt leer

Emoji, Surrogate-Paare und ein 16-Bit-wchar_t

Ein Emoji kommt als anderes Zeichen zurück, wenn ein Dekodierpfad einen vollständigen Unicode-Skalarwert in einem einzelnen wchar_t speichert, das auf Windows 16 Bits breit ist. Zwei Stellen eines XFA-Ladens sind dem ausgesetzt: der UTF-8-Stream-Decoder und der Parser für numerische Zeichenreferenzen wie &#x1F642;. U+1F642 braucht 17 Bits. Presst man es in 16, fällt das oberste Bit weg, und U+F642 bleibt in der Private Use Area zurück

Ein Form-Serializer kann in die andere Richtung scheitern. Filtert er Zeichen je ein wchar_t auf einmal, sieht er zwei Surrogate-Code-Einheiten, D83D und DE42, die jeweils für sich ungültig sind, und wirft beide weg. Das Emoji verschwindet aus dem Form-Packet, ohne dass ein Ersatzzeichen zurückbleibt

PDFium-Component-Diagramm der Surrogate-Behandlung, in dem U+1F642 als UTF-16-Paar D83D DE42 ankommt und zwei naive Pfade es korrumpieren können: 16-Bit-wchar_t-Decoder schneiden den Skalar auf U+F642 in der Private Use Area ab, während ein Serializer, der einzelne Surrogate filtert, das Emoji komplett verwirft
Windows-wchar_t ist 16 Bits breit, ein Skalar, der ein Surrogate-Paar braucht, verliert also entweder seine hohe Hälfte oder verschwindet aus dem Packet, sofern nicht beide Pfade Paare zusammenhalten

In PDFium Component konsumiert der Decoder jeden Skalarwert vollständig und emittiert ein ordentliches Surrogate-Paar, auch wenn der Ausgabepuffer nur noch für eine Einheit Platz hat und wenn eine vier Byte lange UTF-8-Sequenz über zwei Leseblöcke gespalten ist. Auf dem Weg raus hält der Form-Exporter gültige Surrogate-Paare zusammen, und numerische Zeichenreferenzen dekodieren ebenfalls zu korrekten Paaren

Latein-1-Testdaten berühren keinen dieser Pfade. Ein Roundtrip-Test für ein XFA-Formular braucht mindestens ein Zeichen über U+FFFF in einem Textfeld, und die gespeicherten Bytes auf die vier Byte lange UTF-8-Sequenz F0 9F 99 82 zu prüfen sagt mehr als ein Blick auf das gerenderte Feld

Single-Stream-XFA und das Save-Ergebnis

Ein Single-Stream-XFA-Dokument behält seine Edits nur, wenn der Save-Pfad einen XDP-Stream in place umschreiben kann, und jede Eingabe, die er nicht umschreiben kann, muss das Sichern scheitern lassen. ISO 32000-1 §12.7.8 erlaubt dem /XFA-Eintrag des interaktiven Formular-Dictionarys entweder ein Array, das Packet-Namen und Streams abwechselt, oder einen einzelnen Stream, der das ganze XDP-Dokument hält. Ein nur für Arrays geschriebener Save-Pfad weist Single Streams ab, und wenn der Aufrufer das Ergebnis ignoriert, wird das PDF mit den Formulardaten auf ihren alten Werten geschrieben

Die V8-Runtime in PDFium Component handhabt eine definierte Single-Stream-Teilmenge in drei Schritten. Sie exportiert beide Live-Packets, datasets und form, in einen Staging-Bereich und validiert sie. Erst dann ersetzt sie die passenden Packets innerhalb des ursprünglichen XDP und behält die übrigen Packets und die Root-Namespace-Deklarationen. Scheitert das Staging, wird der persistente XFA-Stream nie angefasst und das Dokument behält seine Änderungsmarkierung, sodass ein späteres Sichern es wieder versuchen kann

PDFium-Component-Pipeline des Single-Stream-XFA-Saves, in dem die Live-Packets datasets und form zum Staging exportiert, validiert und dann innerhalb des ursprünglichen XDP ersetzt werden, mit durch Marker bewahrten Kommentaren, während Staging-Fehlschläge und Eingaben wie DTDs oder XMLDSig das Sichern explizit verweigern
Der gestagte Export wird validiert, bevor irgendetwas ersetzt wird, ein gescheitertes Sichern lässt den persistenten XFA-Stream also unangetastet, und das Dokument behält seine Änderungsmarkierung

XML-Kommentare und Processing Instructions brauchen besondere Pflege, weil der Parser, der für das Umschreiben benutzt wird, sie fallen lässt. Jeder wird vor dem Parsen gegen einen eindeutigen Marker getauscht und danach zurückgesetzt, und der Stream wird nur geschrieben, wenn jeder Marker exakt einmal auftaucht, also behalten Kommentare außerhalb der Live-Packets ihren Text und ihre Reihenfolge

Manche Eingaben werden rundheraus abgewiesen, und jede Ablehnung erreicht Sie als gescheitertes Sichern:

  • Kommentare oder Processing Instructions innerhalb der Live-Packets datasets oder form, denn ihre ursprünglichen Positionen lassen sich nicht in frisch exportierten Inhalt übertragen
  • DTD-Deklarationen und XMLDSig-Signaturen, denn das Umschreiben des XDP kann eine XML-Signatur nicht gültig halten
  • Ungültiges UTF-8 oder UTF-16, unvollständige Tags, ungültige Zeichenreferenzen, unbekannte Entities und malformed Processing Instructions, die abgewiesen statt stillschweigend repariert werden

Abweisen ist hier der bessere Trade. Ein Sichern, das False zurückgibt, kann wiederholt, geloggt oder an einen Menschen gereicht werden, während ein stillschweigend normalisiertes XDP Wochen später eine Signatur oder einen Downstream-Importer brechen kann, weit entfernt vom Code, der es geändert hat. Was der Single-Stream-Pfad bewahrt, ist das XML-Inhaltsmodell, geschrieben als UTF-8; das ursprüngliche Byte-Layout und die Encoding-Deklaration des Quell-Streams werden nicht übernommen

Der letzte gepufferte Block

Die letzte Falle sitzt unterhalb von XFA, im generischen PDF-Writer. Ein Datei-Writer, der die Ausgabe in Blöcken fester Größe puffert, muss am Ende den letzten Teilblock hinausdrücken. Passiert das in Aufräum-Code, nachdem der Dokument-Writer bereits Erfolg gemeldet hat, erreicht eine volle Platte oder ein I/O-Fehler auf dem letzten Block nie den Aufrufer, und die Datei auf der Platte ist zu kurz. In beiden PDFium-Component-Runtimes gehört der finale Flush zum Save-Ergebnis, und die XFA-Änderungsmarkierung wird erst geräumt, wenn das Schreiben wirklich erfolgreich war

Die Delphi-Seite legt eine weitere Schicht drauf. TPdf.SaveAs schreibt in eine temporäre Datei neben dem Ziel und verschiebt sie nur dann über das Ziel, wenn das Stream-Sichern True zurückgibt. Ein False-Ergebnis lässt die vorherige Datei exakt, wie sie war, und ein Fehlschlag des finalen Ersetzens wirft einen OS-Fehler, statt still zurückzukehren

Warum öffnet ein dynamisches XFA-Formular mit weniger Seiten wieder?

Ein dynamisches XFA-Formular öffnet mit weniger Seiten wieder, wenn seine Root-Subform kein restoreState="auto" deklariert, und diese Entscheidung gehört zum Formular-Authoring. In XFA 3.3 defaultet restoreState auf der Root-Subform zu manual. Unter manual stellt der XFA-Prozessor nur begrenzten Zustand aus dem gespeicherten Form-Packet wieder her und überlässt den Rest den eigenen Skripten des Formulars. Gespeicherte Feldwerte und die Instanzzahlen wiederholter Subforms kommen zurück; geometrische Properties, die zur Laufzeit gesetzt wurden, nicht

Nehmen wir ein dreiseitiges Formular, dessen Skript eine Subform auf h="450pt" aufbläht, während der Nutzer es ausfüllt. Das gespeicherte Form-Packet hält die neue Höhe, die Feldwerte und die Instanzzahlen. Beim Wiederöffnen wird das Layout aus den Vorlagen-Höhen neu gebaut, die Subform schrumpft zurück, und der Inhalt fließt auf zwei Seiten um. Das ist das Verhalten, das die XFA-Spezifikation verlangt, wenn die Vorlage nie um automatische Wiederherstellung gebeten hat. Sie auf der Root-Subform zu deklarieren ändert das Wiederöffnen:

<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">
      <!-- Felder; Skripte dürfen h ändern oder Instanzen zur Laufzeit ergänzen -->
    </subform>
  </subform>
</template>

Gehört Ihnen die Vorlage nicht, lassen Sie die Finger davon: Ein Formular, das für den manual-Modus gebaut ist, erwartet, dass seine eigenen Initialisierungs-Skripte den Zustand neu aufbauen, und den Modus unter ihnen umzuschalten ändert, worum herum diese Skripte geschrieben wurden. Live-Repagination während der Nutzer tippt ist ein eigener Mechanismus, beschrieben in wie PDFium Component dynamische XFA-Seitenzahlen und umgezogene Felder verfolgt

Wie man einen XFA-Roundtrip aus Delphi prüft

Ein XFA-Sichern wird verifiziert, indem man die gesicherte Datei in einer frischen TPdf-Instanz wieder öffnet und die gespeicherten Daten zurückliest, denn ein True von SaveAs sagt nur, dass die Datei geschrieben wurde. TPdf.GetXfaDatasets liefert das datasets-Packet so, wie es im Dokument gespeichert ist, nicht das Live-Datenmodell, also zeigt ein Lesen vor dem Sichern die Werte des letzten Ladens. Nach dem Wiederöffnen zeigt es exakt das Geschriebene. Ein Single-Stream-Dokument hat keine separat benannten Packets: PDFium meldet das ganze XDP als ein Packet mit leerem Namen, also liefern GetXfaPacketByName('datasets') und GetXfaDatasets beide ein leeres Array, und der Code unten fällt auf den kompletten Stream aus GetXfaFormPackets zurück

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;          // Packet-Array-Layout
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // Single Stream: ein unbenanntes Packet
      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);  // Die gespeicherte XDP-Ausgabe ist UTF-8
  finally
    Pdf.Free;
  end;
end;

Die Save-Routine committet den ausstehenden Edit, prüft das SaveAs-Ergebnis und vergleicht den wieder geöffneten Wert. TPdf.ClearFormFieldFocus entfernt den Formularfokus, das ist der Moment, in dem PDFium den Edit-Buffer des fokussierten Felds committet. TPdf.SetFocusedFormFieldText kann das fokussierte Feld aus Code füllen, beruht aber auf einem Fokus, der über Widget-Annotationen verfolgt wird, was einer dynamischen XFA-Seite normalerweise fehlt; dort gibt es False zurück, und Text kommt gewöhnlich über Tastatureingabe in TPdfView

// XmlText ist ein Helfer, den Sie selbst ergänzen; er ist nicht Teil von 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
  // Optionales Skript-Fill; False heißt, kein verfolgtes Feld hat Fokus
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // den Edit-Buffer committen
  if not Pdf.SaveAs(FileName) then      // False: die vorherige Datei bleibt an ihrem Platz
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // In einem frischen TPdf wieder öffnen und nach dem exakten Elementtext suchen
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

Der Teilstring-Test ist nur ein Smoke-Test. Ein leeres Element kann als <Tag/> geschrieben werden, Datenelemente können Attribute tragen, und Escaping über & und < hinaus ist Sache des Serializers, also gehören Produktions-Prüfungen in einen echten XML-Parser. Fahren Sie die Routine zweimal hintereinander mit derselben Eingabe, denn das Linefeed-Driften zeigt seine volle Gestalt erst in der zweiten Generation

Host-Anwendungen, die die XFA-Runtime direkt ansteuern, brauchen außerdem das Callback-Layout, das sie erwartet, das Thema von FPDF_FORMFILLINFO Version 2 und dem XFA-ABI in Delphi ist. Beide Windows-Runtimes für Win32 und Win64, der Delphi- und C++Builder-Wrapper und das TPdfView-Viewer-Control kommen mit PDFium Component for Delphi and C++Builder