Una casella Comments vuota di un form di reclamo XFA si riapre con un line feed dentro. Salvate e riaprite di nuovo e la casella ne ha due. Un nome cliente battuto con U+1F642, la faccina sorridente, torna come U+F642, un code point a uso privato che la maggior parte dei font disegna come un rettangolo vuoto. Tutti e tre gli effetti vivono nell'XML che un salvataggio XFA scrive nel pacchetto datasets, e un percorso di salvataggio che li centra deve tenere il whitespace di layout fuori dai valori dei campi, portare i caratteri del piano supplementare come coppie di surrogate complete, e riferire una scrittura fallita attraverso il risultato del salvataggio invece che attraverso un file danneggiato
Quale runtime PDFium salva i valori XFA?
Solo pdfium.v8.dll salva i valori XFA, perché è l'unica build di PDFium Component che porta sia il motore JavaScript V8 sia il runtime dei form XFA. Una volta che una modifica è stata committata (il campo ha perso il focus, o ClearFormFieldFocus ha forzato il commit), quel runtime esporta i dati XFA vivi nel pacchetto datasets al salvataggio, senza editing di pacchetti nel vostro codice. Ogni architettura Windows spedisce anche pdfium.dll, costruita senza V8 e XFA, che riscrive i pacchetti memorizzati esattamente come li ha letti. Ciò che accade a un valore scritto mentre il campo ha ancora il focus è trattato in perché le modifiche ai campi XFA svaniscono al salvataggio
Il wrapper Delphi cerca di scegliere la libreria giusta per voi. Quando EnableV8Engine è ancora False e nessuna libreria PDFium è stata ancora caricata, TPdf guarda il file che sta per aprire, e se trova marker XFA (una voce /XFA nel dizionario AcroForm, o /NeedsRendering true nel catalogo) attiva EnableV8Engine prima di caricare. Quell'interruttore funziona una sola volta per processo. Se un pdfium.dll ordinario è già residente perché il primo documento della sessione era un PDF semplice, il processo resta legato a quello, e TPdf.OnXfaRuntimeMissing scatta quando arriva più tardi un documento XFA
L'ordine di ricerca predefinito è l'altra metà del problema. Senza una directory in LibraryName, il loader parte da una cartella DLLs\Win32 o DLLs\Win64 sotto la cartella dell'applicazione o di uno dei suoi genitori, così un pdfium.v8.dll più vecchio può essere trovato per primo. Un LibraryName che contiene una directory blocca esattamente quel file, e se manca, il caricamento fallisce
uses
System.SysUtils, PDFium;
procedure SelectXfaRuntime;
begin
// Un percorso di directory in LibraryName blocca questo file esatto;
// se il file manca, LoadLibrary fallisce invece di cercare altrove
{$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; // fallisci all'avvio, non al primo salvataggio XFA
end;
Dopo l'apertura di un documento, TPdf.XFA dice che il file contiene XFA, e TPdf.XfaRuntimeAvailable dice che la libreria caricata può davvero avviare il motore XFA per questo documento. Form statici e dinamici si distinguono tramite TPdf.FormType, che restituisce ftXfaFull per un form dinamico e ftXfaForeground per uno statico. Il probing a livello di pacchetto su una macchina senza il runtime V8 è l'argomento di rilevare i form XFA ed estrarre i pacchetti XFA in Delphi
Perché i campi XFA salvati guadagnano line feed extra?
I campi XFA salvati guadagnano line feed quando il writer pretty-printa il suo XML con una newline dopo ogni start tag. Due writer sono coinvolti in un salvataggio XFA, il writer generico di elementi XML e il serializzatore del pacchetto form, ed entrambi per abitudine formattano l'output così. Nella maggior parte dei documenti XML quel whitespace è cosmetico. Nei dati XFA è il valore: quando il pacchetto datasets viene analizzato di nuovo, ogni carattere fra <Comments> e </Comments> appartiene al campo, newline inclusa
Un campo vuoto quindi si riapre con un singolo LF dentro. Ogni salvataggio ulteriore formatta attorno all'LF già presente, così un campo che nessuno tocca cresce di una riga per ogni giro di revisione
Tagliare i valori al caricamento sembra una riparazione economica, e corromperebbe dati veri. La gente digita spazi iniziali, spazi finali e interruzioni di riga volute nei campi XFA; un blocco indirizzo deve conservare la sua struttura di righe, e un codice di riferimento a larghezza fissa deve sopravvivere byte per byte. I writer XFA di PDFium Component invece scartano solo il whitespace che il serializzatore stesso sintetizza attorno ai tag. I valori utente, i nodi di testo che erano già nel file e le sezioni CDATA passano invariati, così " indented" resta indentato e un campo volutamente vuoto resta vuoto
Emoji, coppie di surrogate e un wchar_t a 16 bit
Una emoji torna come un carattere diverso quando un percorso di decodifica memorizza un valore scalare Unicode completo in un singolo wchar_t, che su Windows è largo 16 bit. Due punti di un caricamento XFA sono esposti a questo: il decoder dello stream UTF-8, e il parser dei riferimenti numerici a caratteri come 🙂. U+1F642 richiede 17 bit. Spremetelo in 16 e il bit alto cade, lasciando U+F642 nella Private Use Area
Un serializzatore di form può fallire nella direzione opposta. Filtrando i caratteri un wchar_t alla volta, vede due code unit surrogate, D83D e DE42, ognuna delle quali è invalida da sola, e butta via entrambe. L'emoji sparisce dal pacchetto form, senza lasciare dietro un carattere di sostituzione
In PDFium Component il decoder consuma ogni valore scalare per intero ed emette una coppia di surrogate corretta, anche quando il buffer di output ha spazio per una sola unità in più e quando una sequenza UTF-8 di quattro byte è spezzata fra due blocchi di lettura. In uscita, l'esportatore del form tiene insieme le coppie di surrogate valide, e anche i riferimenti numerici a caratteri decodificano in coppie corrette
Dati di test Latin-1 non toccano nessuno di questi percorsi. Un test di round trip per un form XFA ha bisogno di almeno un carattere sopra U+FFFF in un campo di testo, e controllare nei byte salvati la sequenza UTF-8 di quattro byte F0 9F 99 82 dice più di quanto guardare il campo renderizzato
XFA a stream singolo e risultato del salvataggio
Un documento XFA a stream singolo conserva le sue modifiche solo se il percorso di salvataggio può riscrivere uno stream XDP sul posto, e qualsiasi input che non sa riscrivere deve far fallire il salvataggio. ISO 32000-1 §12.7.8 permette che la voce /XFA del dizionario del form interattivo sia sia un array che alterna nomi di pacchetto e stream sia un singolo stream che contiene l'intero documento XDP. Un percorso di salvataggio scritto solo per gli array rifiuta gli stream singoli, e se il chiamante ignora quel risultato, il PDF viene scritto con i dati del form ai vecchi valori
Il runtime V8 in PDFium Component gestisce un sottoinsieme definito degli stream singoli in tre passi. Esporta entrambi i pacchetti vivi, datasets e form, in un'area di staging e li valida. Solo allora sostituisce i pacchetti corrispondenti dentro l'XDP originale, conservando gli altri pacchetti e le dichiarazioni di namespace della radice. Se lo staging fallisce, lo stream XFA persistente non viene mai toccato e il documento conserva il suo marchio di modifica, così un salvataggio successivo può riprovarci
I commenti XML e le istruzioni di elaborazione richiedono una cura extra, perché il parser usato per la riscrittura li butta via. Ognuno viene scambiato con un marker unico prima del parsing e rimesso dopo, e lo stream viene scritto solo se ogni marker compare esattamente una volta, così i commenti fuori dai pacchetti vivi conservano testo e ordine
Alcuni input vengono rifiutati senza appello, e ogni rifiuto vi arriva come un salvataggio fallito:
- Commenti o istruzioni di elaborazione dentro i pacchetti vivi
datasetsoform, dato che non c'è modo di mappare le loro posizioni originali in contenuto appena esportato - Dichiarazioni DTD e firme XMLDSig, dato che riscrivere l'XDP non può mantenere valida una firma XML
- UTF-8 o UTF-16 non valido, tag incompleti, riferimenti a caratteri non validi, entità sconosciute e istruzioni di elaborazione malformate, che vengono rifiutati invece di riparati al volo
Rifiutare è il patto migliore qui. Un salvataggio che restituisce False può essere ritentato, loggato o consegnato a una persona, mentre un XDP normalizzato in silenzio potrebbe rompere una firma o un importatore a valle settimane dopo, lontano dal codice che l'ha cambiato. Ciò che il percorso a stream singolo preserva è il modello di contenuto XML, scritto come UTF-8; il layout di byte originale e la dichiarazione di encoding dello stream sorgente non vengono portati dietro
L'ultimo blocco bufferizzato
La trappola finale sta sotto l'XFA, nel writer PDF generico. Un writer di file che bufferizza l'output in blocchi di dimensione fissa deve spingere fuori l'ultimo blocco parziale alla fine. Se questo accade nel codice di pulizia dopo che il writer del documento ha già riferito successo, un disco pieno o un errore di I/O sull'ultimo blocco non arriva mai al chiamante, e il file su disco è corto. In entrambi i runtime di PDFium Component il flush finale fa parte del risultato del salvataggio, e il marchio di modifica XFA viene azzerato solo dopo che la scrittura è davvero riuscita
Il lato Delphi aggiunge un ulteriore strato. TPdf.SaveAs scrive in un file temporaneo accanto al target e lo sposta sul target solo quando il salvataggio dello stream restituisce True. Un risultato False lascia il file precedente esattamente com'era, e un fallimento della sostituzione finale solleva un errore del sistema operativo invece di tornare in silenzio
Perché un form XFA dinamico si riapre con meno pagine?
Un form XFA dinamico si riapre con meno pagine quando il suo subform radice non dichiara restoreState="auto", e quella decisione appartiene all'autore del form. In XFA 3.3, restoreState sul subform radice vale manual per difetto. Sotto manual, il processore XFA ripristina solo uno stato limitato dal pacchetto form salvato e lascia il resto agli script del form stesso. I valori dei campi e i conteggi di istanza dei subform ripetuti tornano; le proprietà geometriche impostate a run time no
Prendete un form di tre pagine il cui script porta un subform a h="450pt" mentre l'utente lo compila. Il pacchetto form salvato contiene la nuova altezza, i valori dei campi e i conteggi di istanza. Alla riapertura, il layout viene ricostruito dalle altezze del template, il subform si restringe, e il contenuto rifluisce su due pagine. È il comportamento che la specifica XFA chiede quando il template non ha mai richiesto il ripristino automatico. Dichiararlo sul subform radice cambia la riapertura:
<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">
<!-- campi; gli script possono cambiare h o aggiungere istanze a run time -->
</subform>
</subform>
</template>
Se il template non è vostro, lasciatelo stare: un form costruito per la modalità manual si aspetta che i suoi script di inizializzazione ricostruiscano lo stato, e cambiare la modalità sotto di loro cambia ciò attorno a cui quegli script erano scritti. La repaginazione live mentre l'utente digita è un meccanismo diverso, descritto in come PDFium Component traccia i conteggi di pagina XFA dinamici e i campi spostati
Verificare un round trip XFA da Delphi
Un salvataggio XFA si verifica riaprendo il file salvato in una istanza TPdf fresca e rileggendo i dati memorizzati, dato che un True da SaveAs dice solo che il file è stato scritto. TPdf.GetXfaDatasets restituisce il pacchetto datasets così com'è memorizzato nel documento, non il modello dati vivo, quindi leggerlo prima del salvataggio mostra i valori dell'ultimo caricamento. Dopo una riapertura mostra esattamente ciò che è stato scritto. Un documento a stream singolo non ha pacchetti con nome separato: PDFium riferisce l'intero XDP come un pacchetto con nome vuoto, così GetXfaPacketByName('datasets') e GetXfaDatasets restituiscono entrambi un array vuoto, e il codice qui sotto ripiega sullo stream completo da GetXfaFormPackets
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; // layout ad array di pacchetti
if Length(Bytes) = 0 then
begin
Packets := Pdf.GetXfaFormPackets; // stream singolo: un pacchetto senza nome
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); // l'output XDP salvato è UTF-8
finally
Pdf.Free;
end;
end;
La routine di salvataggio commetta la modifica in sospeso, controlla il risultato di SaveAs e confronta il valore riaperto. TPdf.ClearFormFieldFocus rimuove il focus del form, che è il momento in cui PDFium committa il buffer di modifica del campo con focus. TPdf.SetFocusedFormFieldText può riempire da codice il campo con focus, ma fa affidamento sul focus tracciato tramite annotazioni widget, che una pagina XFA dinamica di solito non ha; lì restituisce False, e il testo normalmente arriva attraverso l'input da tastiera in TPdfView
// XmlText è un helper che aggiungete voi; non fa parte di PDFium Component
function XmlText(const S: string): string;
begin
Result := StringReplace(S, '&', '&', [rfReplaceAll]);
Result := StringReplace(Result, '<', '<', [rfReplaceAll]);
end;
procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
Expected: string);
var
Saved: string;
begin
// Riempimento scripted opzionale; False significa che nessun campo tracciato ha il focus
if (Pdf.FocusedFormFieldIndex >= 0) and
not Pdf.SetFocusedFormFieldText(Expected) then
raise EPdfError.Create('Could not write the focused field');
Pdf.ClearFormFieldFocus; // committa il buffer di modifica
if not Pdf.SaveAs(FileName) then // False: il file precedente resta al suo posto
raise EPdfError.CreateFmt('Saving %s failed', [FileName]);
// Riaprite in un TPdf fresco e cercate il testo esatto dell'elemento
Saved := ReadSavedXfaData(FileName);
if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
Saved) = 0 then
raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;
Il test di sottostringa è solo uno smoke test. Un elemento vuoto può essere scritto come <Tag/>, gli elementi dati possono portare attributi, e l'escaping oltre & e < sta al serializzatore, quindi i controlli di produzione appartengono a un vero parser XML. Eseguite la routine due volte di fila con lo stesso input, perché la deriva delle newline mostra la sua forma completa solo alla seconda generazione
Le applicazioni host che guidano direttamente il runtime XFA hanno bisogno anche del layout di callback che esso si aspetta, che è l'argomento di FPDF_FORMFILLINFO versione 2 e ABI XFA in Delphi. Entrambi i runtime Windows per Win32 e Win64, il wrapper Delphi e C++Builder e il controllo viewer TPdfView arrivano con PDFium Component for Delphi and C++Builder