Articolo tecnico

Salvataggio XFA in PDFium Component: newline e restoreState

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

Diagramma del ciclo di salvataggio XFA di PDFium Component in cui il writer aggiunge una newline dopo gli start tag, il parser alla riapertura legge l'LF fra i tag Comments come valore del campo, e ogni salvataggio ulteriore aggiunge un altro line feed a meno che il writer non rimuova solo il whitespace che ha sintetizzato lui
Un ciclo salva-riapri pianta il primo line feed e ogni giro successivo ne aggiunge un altro, ed è per questo che la deriva mostra la sua forma completa solo alla seconda generazione

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 &#x1F642;. 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

Diagramma della gestione dei surrogate in PDFium Component in cui U+1F642 arriva come coppia UTF-16 D83D DE42 e due percorsi ingenui possono corromperla: i decoder wchar_t a 16 bit troncano lo scalare a U+F642 nella private use area, mentre un serializzatore che filtra le surrogate singole fa sparire del tutto l'emoji
Il wchar_t di Windows è largo 16 bit, quindi uno scalare che richiede una coppia di surrogate o perde la sua metà alta o sparisce dal pacchetto, a meno che entrambi i percorsi non tengano insieme le coppie

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

Pipeline di salvataggio XFA a stream singolo di PDFium Component in cui i pacchetti vivi datasets e form vengono esportati in staging, validati, poi sostituiti dentro l'XDP originale con i commenti preservati tramite marker, mentre fallimenti di staging e input come DTD o XMLDSig rifiutano esplicitamente il salvataggio
L'esportazione in staging viene validata prima che qualcosa venga sostituito, così un salvataggio fallito lascia intatto lo stream XFA persistente e il documento conserva il suo marchio di modifica

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 datasets o form, 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, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [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