Wenn ein dynamisches XFA-Formular in einem Delphi-Viewer Seiten ergänzt oder entfernt, meldet PDFium Component die neue Gesamtzahl über TPdf.PageCount und TPdf.OnXfaPageCountChanged, gelesen aus dem abgeschlossenen Layout, denn das native Seiten-Event trägt ein Hinzugefügt/Entfernt-Delta statt einer Gesamtzahl. Die Windows-V8-Bibliotheken bewegen außerdem Eingabe-Trefferbereiche mit umgezogenen Feldern mit, und TPdfView lädt die Seiten-Handles neu, nachdem der Layout-Callback zurückgekehrt ist. Stellen Sie sich ein Spesenformular vor: Zweimal auf Add Row klicken, und das Formular wächst auf zwei Seiten. Ein Viewer, dem das Event-Argument vertraut, meldet stolz 1 von 1, und einer, der die Pre-Layout-Widget-Geometrie behält, schickt Tastenschläge für ein Feld, das auf Seite 2 gewandert ist, irgendwo unsichtbar. Nichts davon zeigt sich an den Formularen fester Länge, mit denen jeder zuerst testet, und die Gründe dafür sind es wert zu kennen, wenn Sie einen Formular-Viewer einbetten
Was passiert, wenn ein dynamisches XFA-Formular neu paginiert?
Ein dynamisches XFA-Formular hat keine feste Seitenliste, seine Seitenzahl ist also eine Ausgabe des Layouts und kann sich bei jeder Datenänderung des Nutzers ändern. XFA 3.3 beschreibt das Formular als Baum aus Subforms; eine wiederholte Subform wird von einem instanceManager gesteuert, und ein Skript wie _Row.addInstance() klont eine weitere Zeile. Der Layout-Prozessor flutet den Inhalt dann erneut in die Seitenbereiche, was eine Seite ergänzen, eine Seite streichen oder bestehende Felder auf eine andere Seite schieben kann. ISO 32000-1 §12.7.8 definiert nur, wie die XFA-Pakete im PDF reisen; alles, was danach passiert, gehört zur XFA-Engine, die in PDFium Component PDFiums eigenes XFA-Layout im Host-Prozess ist. Ein Delphi-Viewer hat es also mit einem Dokument zu tun, dessen Seitenzahl, Seitengrößen und Widget-Positionen allesamt lebendiger Zustand sind. Drei Dinge gehen schief, wenn der Host etwas anderes annimmt:
- Die Seitenzahl, die der Host für Navigation, Scroll-Bereiche und Seiten-Spinner cacht, veraltet — oder schlimmer, sie wird mit der falschen Zahl aktualisiert
- Felder, die umziehen, zeigen ihren Rand an der neuen Position, während Editor und Maus-Trefferbereich an den alten Koordinaten bleiben
- Der Viewer hält ein Seiten-Handle, das das Layout ersetzt hat, Klicks und Paints gehen also an eine Seite, die es in diesem Formular nicht mehr gibt
Zeilenedits über Sichern und Wiederöffnen hinweg zu persistieren ist ein eigenes Problem mit eigenen Regeln; dieser Artikel bleibt bei dem, was zur Laufzeit im Viewer passiert
Welche PDFium-Runtime braucht dynamisches XFA?
Dynamisches XFA in PDFium Component verlangt den V8/XFA-Build der nativen Bibliothek, gewählt über die globale Variable EnableV8Engine in der Unit PDFium, bevor das erste Dokument lädt. Der Prozess legt sich beim ersten Laden der Bibliothek durch irgendein TPdf auf eine DLL fest, und ein schlichter PDFium-Build kann die XFA-Engine gar nicht fahren. Beim Öffnen eines Dokuments schaut TPdf zwar nach XFA-Markern in der Datei und wechselt automatisch zum V8-Build, aber nur, solange in diesem Prozess noch keine schlichte Bibliothek geladen wurde. Läuft die Festlegung bereits in die falsche Richtung, feuert TPdf.OnXfaRuntimeMissing einmal, damit der Host dem Nutzer einen Neustart nahelegen kann. Das Flag beim Start explizit zu setzen nimmt der Sache jede Rätselrei. Die FPDF_FORMFILLINFO-Callback-Struktur, die die XFA-Events trägt, muss ebenfalls zur DLL passen; der Hintergrund steht in FPDF_FORMFILLINFO Version 2 und dem XFA-Callback-ABI, und das Erkennen von XFA-Formularen und das Lesen ihrer Pakete behandelt, wie man die Formulartypen auseinanderhält, bevor man einen Viewer öffnet
uses
PDFium;
procedure TClaimForm.FormCreate(Sender: TObject);
begin
// Entscheiden, bevor das erste TPdf die native Bibliothek lädt:
// der Prozess kann nicht später von pdfium.dll auf pdfium.v8.dll wechseln
EnableV8Engine := True;
FPdf := TPdf.Create(nil);
FPdf.OnXfaRuntimeMissing := PdfXfaRuntimeMissing;
FPdf.OnXfaPageCountChanged := PdfXfaPageCountChanged;
FPdf.FileName := 'C:\Forms\expense-claim.pdf';
FPdf.Active := True;
PdfView1.Pdf := FPdf;
PdfView1.OnPageChange := PdfViewPageChange;
PdfView1.Active := True;
UpdatePageRange(FPdf.PageCount);
end;
procedure TClaimForm.PdfXfaRuntimeMissing(Sender: TObject);
begin
StatusBar1.SimpleText :=
'This XFA form needs the V8 runtime; restart the application to enable it';
end;
Warum meldet PageCount 1 für ein zweiseitiges Formular?
Ein Wrapper, der das page_count-Argument des nativen Seiten-Events als Dokument-Gesamtzahl speichert, liegt falsch, denn dieses Argument ist tatsächlich die absolute Differenz zwischen neuer und alter Seitenzahl. PDFium wirft FFI_PageEvent nach einem abgeschlossenen Layout-Durchlauf mit dem Event-Typ Seite hinzugefügt oder Seite entfernt; intern aktualisiert es zuerst seine gespeicherte Seitenzahl und reicht dann abs(new - old) durch. Beim ersten Layout ist die alte Zahl null, das Delta gleicht also der Gesamtzahl, und eine dreiseitige statische Referenzdatei meldet erwartungsgemäß drei Seiten. Genau deshalb enthüllen Formulare fester Länge den Fehler nie. Sobald ein dynamisches Formular zum ersten Mal von einer auf zwei Seiten wächst, ist das Delta 1, und so ein Wrapper meldet eine Seitenzahl von 1. Eine Zeile aus einem dreiseitigen Formular zu entfernen produziert dieselbe Art Unsinn in die andere Richtung
Das Delta auf den alten Wert aufzuaddieren ist auch keine sichere Reparatur. Die Reihenfolge von Initialisierungs- und Layout-Callbacks bedeutet, dass der Wrapper seiner früheren Zahl nicht immer als Basis vertrauen kann, eine laufende Summe kann also driften. Der Callback von PDFium Component ignoriert das Argument daher als Zählwert und ruft FPDF_GetPageCount am Dokument auf, was die Gesamtzahl aus dem gerade abgeschlossenen Layout liest. Dann räumt er die gecachten Seiten-Szenen weg, speichert diese Gesamtzahl als XFA-Seitenzahl-Override hinter TPdf.PageCount und wirft erst danach OnXfaPageCountChanged. Läuft Ihr Handler, ziehen NewCount und FPdf.PageCount an einem Strang
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
// NewCount ist die Gesamtzahl des abgeschlossenen Layouts, nie ein Delta.
// Das läuft in PDFiums Layout-Callback: nur Host-UI-Zustand aktualisieren,
// das Dokument hier weder schließen noch Seiten neu laden
UpdatePageRange(NewCount);
end;
procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
// Feuert nach jedem Seiten-Reload, eingeschlossen das verzögerte XFA-Refresh
PageSpin.Value := PdfView1.PageNumber;
end;
procedure TClaimForm.UpdatePageRange(Count: Integer);
begin
PageSpin.MinValue := 1;
PageSpin.MaxValue := Count;
PageLabel.Caption := Format('of %d', [Count]);
end;
Das Event feuert nur für Full-XFA-Formulare, deren Layout sich zur Laufzeit ändert. Static XFA- und AcroForm-Dokumente werfen es nie, ein Viewer, der beides handhabt, kann denselben Handler also drangelassen haben. Unassigned zu lassen ist ebenfalls sicher; der Override hinter TPdf.PageCount greift ohnehin, und das Event existiert, damit der Host auffrischen kann, was er gecacht hat
Warum bleibt das Eingabefeld auf der alten Seite, wenn ein Feld umzieht?
Der Rand zieht um und der Editor nicht, wenn der native XFA-Notifier ein Rechteck mit sich selbst vergleicht. Wenn das Layout die Geometrie eines bereits geladenen Widgets ändert, soll PDFium das neue Rechteck bemerken und PerformLayout am Widget aufrufen, was den Texteditor und seinen Trefferbereich neu positioniert. Eine Prüfung, die GetWidgetRect() mit RecacheWidgetRect() vergleicht, kann niemals feuern: Beide Funktionen liefern eine const-Referenz auf dasselbe Member, und der Recache überschreibt dieses Member in place, der Vergleich sieht also stets zwei identische Werte, und geladene Widgets überspringen ihr Relayout
Das Symptom zeigt sich, wenn eine Subform-Höhe sich so ändert, dass bestehende Felder auf die nächste Seite hinüberrutschen: Der Feldrand wird an seiner neuen Position gezeichnet, während der getippte Text und der Maus-Trefferbereich an der alten Y-Koordinate bleiben. Ein explizites Relayout hilft nicht, ein Neuladen der Seite auch nicht, denn das Widget glaubt weiterhin, seine Geometrie sei aktuell. Die Windows-V8-Bibliotheken, die mit PDFium Component ausgeliefert werden, kopieren das alte Rechteck by value, bevor sie neu cachen, und vergleichen diese Kopie, umgezogene Widgets relayouten also, und der editierte Wert erscheint exakt dort, wo der Rand ist. Die Prüfung wohnt im nativen Code und reist mit den DLLs, liefern Sie also pdfium.v8.dll zusammen mit den Pascal-Units aus. Um es selbst zu testen, editieren Sie zuerst eine überlebende Zeile auf einen Nicht-Default-Wert und suchen Sie dann diesen Wert an der neuen Position des Felds, denn eine mit Default-Werten neu gebaute Zeile hätte sonst wie ein Erfolg ausgesehen
Wie lädt TPdfView Seiten neu, ohne PDFium ein Handle unterm Hintern wegzuziehen?
TPdfView schiebt den Seiten-Reload, der auf eine XFA-Layout-Änderung folgt, auf, bis der native Aufrufstapel abgebaut ist. Das Seiten-Event feuert meist, während PDFium noch Eingaben verarbeitet: Der Nutzer klickte auf einen Add-Row-Button, der Klick fuhr ein Skript, das Skript änderte die Instanzzahl, und das Layout schloss innerhalb desselben nativen Aufrufs ab. Das Seiten-Handle in diesem Moment zu schließen und neu zu öffnen würde ein Objekt freigeben, das der Aufrufer noch benutzt. Ein Viewer, der sich in diesem Moment nur selbst invalidiert, hält ein Seiten-Handle, das auf den Pre-Layout-Zustand zeigt, und war der Nutzer gerade auf der letzten Seite, als sie verschwand, liegt die gewählte Seitenzahl außerhalb des Bereichs
Das verzögerte Refresh arbeitet in ein paar kleinen Schritten, und sie erklären das Verhalten, das Sie als Host sehen:
- Der Seiten-Event-Callback markiert die View als mit einem ausstehenden XFA-Layout-Refresh und posted eine private Fenster-Nachricht; wiederholte Events, bevor die Nachricht ankommt, verschmelzen zu einem Refresh
- Eine View ohne Fenster-Handle hält das Pending-Flag und posted die Nachricht aus
CreateWnd, während ein Dokumentwechsel, das Deaktivieren oder Zerstören der View das Flag löscht - Kommt die Nachricht an, räumt die View die Textauswahl, das Such-Highlight und den Fokussiertes-Feld-Index weg, denn alle drei bezogen sich auf das alte Layout
- Die gewählte Seite wird auf das neue
PageCountgeklemmt; eine geänderte Seitenzahl läuft durch den normalen Seitenwechsel, sonst wird die aktuelle Seite neu geladen, und der Fit-Modus wird erneut angewandt - Lässt das Layout gar keine Seiten zurück, entlädt die View ihr altes Seiten-Handle, statt eine Seite zu zeichnen, die es nicht mehr gibt
Dieselbe Beschränkung gilt für Ihren eigenen Code. OnXfaPageCountChanged läuft innerhalb dieses nativen Layout-Callbacks, behandeln Sie es also wie eine Benachrichtigung: Labels, Spinner-Bereiche und Toolbar-Zustand dort aktualisieren, alles Schwerere, etwa das Schließen des Dokuments oder das Öffnen eines anderen, über eine gepostete Nachricht in die Warteschlange stellen, damit es nach der Rückkehr des Callbacks läuft. TPdfView.OnPageChange sagt Ihnen dann, wann die View die Seite tatsächlich neu geladen hat, und PdfView1.PageNumber an diesem Punkt zu lesen liefert den geklemmten Wert. Tab-Durchlauf und die FormType-Prüfungen, die ein Formular-Viewer beim Öffnen fährt, behandelt PDF-Formularfeld-Navigation mit PDFium Component
Wie behandelt der Viewer Full-XFA-Seiten ohne Text-Ebene?
Full-XFA-Seiten haben keine PDF-Textseite, alles, was auf so einer Seite eine anfordert, scheitert also mit einem Cannot open text page-Fehler. Die Standard-Textauswahl und die Link-Erkennung eines Viewers fragen beide diese Ebene: Mit TPdfView.AllowUserTextSelection auf seinem Default True fragt das Hovern die Text-Ebene nach einem Zeichen unter der Maus, und ein Mouse-up-Klick fährt eine automatische URL-Sonde über den Seitentext. In TPdfView liefern beide internen Pfade kein Ergebnis, wenn TPdf.FormType gleich ftXfaFull ist und die XFA-Runtime verfügbar ist, die Default-Einstellungen funktionieren also, und die Feldeingabe bleibt verfügbar
AllowUserTextSelection für Full-XFA-Dokumente auszuschalten ist eine vernünftige UI-Entscheidung, denn es gibt keinen Seitentext zu selektieren, und Zieh-Gesten sollten keinen Auswahl-Modus starten
procedure TClaimForm.ConfigureViewerForForm;
begin
// FormType liest das geöffnete Dokument, also nach FPdf.Active := True aufrufen
if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
begin
// Auf Full-XFA-Seiten gibt es keine PDF-Text-Ebene; Felder bleiben editierbar
PdfView1.AllowUserTextSelection := False;
StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
[FPdf.PageCount]);
end
else
PdfView1.AllowUserTextSelection := True;
end;
Das Tippen über eine Auswahl braucht seine eigene Behandlung. Der native XFA-Texteditor ersetzt keine Auswahl, wenn er ein Zeichen erhält: FORM_OnChar fügt am Caret ein, und Backspace löscht ein einzelnes Zeichen, Tastenschläge einfach durchzureichen würde also alten und neuen Text nebeneinander stellen. PDFium Component merkt sich, dass der Klick auf einem XFA-Textfeld gelandet ist, und routet getippte Zeichen, Backspace und Delete durch FORM_ReplaceSelection, wann immer eine Auswahl existiert und das Dokument Fill-Forms- oder Modify-Berechtigung gewährt. Ob ein read-only XFA-Feld sich ändern darf, entscheidet der native Editor, ein im Formular als read-only markiertes Feld behält also seinen Wert, selbst in einem Dokument, das sonst das Ausfüllen erlaubt. TPdfView.AllowFormEvents auf False zu setzen stoppt dieses Tastatur-Routing ebenfalls, ein read-only Viewer bleibt so read-only
Kurzreferenz: dynamisches XFA in einem Delphi-Viewer
| Symptom | Ursache | Zuständig |
|---|---|---|
| Die Seitenzahl zeigt 1, nachdem das Formular auf zwei Seiten gewachsen ist | Das native Seiten-Event durchreicht ein Hinzugefügt/Entfernt-Delta, keine Gesamtzahl | TPdf.PageCount liest das abgeschlossene Layout |
| Der Feldrand zieht um, getippter Text und Trefferbereich bleiben zurück | Geladenes Widget überspringt das Relayout nach einem Selbstvergleich | Copy-by-Value-Prüfung in den Windows-V8-Bibliotheken |
| Der Viewer zeichnet auf den Pre-Layout-Seitenzustand oder routet Eingaben dorthin | Seiten-Handle nach der Repagination nicht neu geladen | Verzögertes Refresh in TPdfView |
| Ein Klick in ein Feld fordert eine Textseite an, die nicht existiert | Textauswahl und URL-Sonde auf Seiten ohne Text-Ebene | Text-Pfade liefern auf ftXfaFull-Seiten kein Ergebnis |
| Tippen über einen selektierten Wert hängt an statt zu ersetzen | Der native XFA-Editor fügt am Caret ein | Tastenschläge geroutet durch FORM_ReplaceSelection |
EnableV8EngineaufTruesetzen, bevor irgendein Dokument lädt, undOnXfaRuntimeMissingfür den Fall behandeln, dass die schlichte Bibliothek zuerst geladen wurde- Die Gesamtzahl aus
TPdf.PageCountoder demNewCount-Parameter vonOnXfaPageCountChangedlesen; niemals selbst Seitenzahlen addieren oder subtrahieren - Den
OnXfaPageCountChanged-Handler leicht halten, denn er läuft innerhalb des nativen Layout-Callbacks - Den aktuellen Seitenindikator in
TPdfView.OnPageChangesynchronisieren, der nach dem verzögerten Reload feuert, der die Seitenzahl einklemmt - Die Windows-V8-DLLs zusammen mit den Units ausliefern; die Widget-Relayout-Prüfung wohnt im nativen Code
- Mit einem Formular testen, das seine Seitenzahl tatsächlich ändert und ein editiertes Feld über einen Seitenumbruch schiebt, denn Referenzdateien fester Länge verstecken jedes Problem auf dieser Liste
Dynamisches XFA macht aus Seitenzahl und Feldgeometrie lebendige Werte, und ein Viewer bleibt nur dann korrekt, wenn er sie aus dem abgeschlossenen Layout nimmt und Seiten zu einem sicheren Moment neu lädt. PDFium Component handhabt beides innerhalb von TPdf und TPdfView, der Host muss nur noch zuhören. Details und Downloads finden Sie auf der PDFium Component for Delphi product page