Article technique

Sauts de ligne, emoji et restoreState dans la sauvegarde XFA

Une zone Comments vide d'un formulaire XFA de réclamation se rouvre en contenant un saut de ligne. Sauvegardez et rouvrez encore, et la zone en contient deux. Un nom de client saisi avec U+1F642, le visage légèrement souriant, revient en U+F642, un point de code à usage privé que la plupart des polices dessinent comme un rectangle vide. Les trois effets vivent dans le XML qu'une sauvegarde XFA écrit dans le paquet datasets, et un chemin de sauvegarde qui les gère bien doit garder l'espace de mise en page hors des valeurs de champs, transporter les caractères hors du plan de base comme des paires de surrogates complètes, et signaler un échec d'écriture via le résultat de sauvegarde plutôt que via un fichier abîmé

Quel runtime PDFium sauvegarde les valeurs XFA ?

Seul pdfium.v8.dll sauvegarde les valeurs XFA, parce que c'est le seul build de PDFium Component qui embarque à la fois le moteur JavaScript V8 et le runtime de formulaires XFA. Une fois une modification validée (le champ a perdu le focus, ou ClearFormFieldFocus a forcé la validation), ce runtime exporte les données XFA vivantes dans le paquet datasets à la sauvegarde, sans édition de paquets dans votre code. Chaque architecture Windows livre aussi un pdfium.dll, construit sans V8 ni XFA, qui réécrit les paquets stockés exactement comme il les a lus. Ce qu'il advient d'une valeur écrite pendant que le champ a encore le focus est traité dans pourquoi les modifications de champs XFA disparaissent à la sauvegarde

Le wrapper Delphi essaie de choisir la bonne bibliothèque pour vous. Quand EnableV8Engine vaut encore False et qu'aucune bibliothèque PDFium n'a encore été chargée, TPdf examine le fichier qu'il s'apprête à ouvrir et, s'il trouve des marqueurs XFA (une entrée /XFA dans le dictionnaire AcroForm, ou /NeedsRendering true dans le catalog), il active EnableV8Engine avant le chargement. Ce basculement ne fonctionne qu'une fois par processus. Si un pdfium.dll ordinaire est déjà résident parce que le premier document de la session était un PDF simple, le processus reste engagé sur lui, et TPdf.OnXfaRuntimeMissing se déclenche quand un document XFA arrive plus tard

L'ordre de recherche par défaut est l'autre moitié du problème. Sans répertoire dans LibraryName, le loader commence par un dossier DLLs\Win32 ou DLLs\Win64 sous le dossier de l'application ou l'un de ses parents, si bien qu'un pdfium.v8.dll plus ancien peut être trouvé en premier. Un LibraryName qui contient un répertoire épingle exactement ce fichier, et s'il manque, le chargement échoue

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // Un répertoire dans LibraryName épingle ce fichier exact ;
  // un fichier manquant fait échouer LoadLibrary au lieu de chercher ailleurs
{$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;  // échouez au démarrage, pas à la première sauvegarde XFA
end;

Après ouverture d'un document, TPdf.XFA dit que le fichier contient du XFA, et TPdf.XfaRuntimeAvailable dit que la bibliothèque chargée a réellement pu démarrer le moteur XFA pour ce document. Formulaires statiques et dynamiques se distinguent via TPdf.FormType, qui renvoie ftXfaFull pour un formulaire dynamique et ftXfaForeground pour un statique. Le sondage au niveau des paquets sur une machine sans le runtime V8 fait l'objet de la détection des formulaires XFA et l'extraction des paquets XFA en Delphi

Pourquoi des champs XFA sauvegardés gagnent-ils des sauts de ligne supplémentaires ?

Des champs XFA sauvegardés gagnent des sauts de ligne quand le writer imprime son XML joliment avec un saut de ligne après chaque balise ouvrante. Deux writers participent à une sauvegarde XFA, le writer XML générique d'éléments et le sérialiseur du paquet de formulaire, et tous deux formatent habituellement leur sortie ainsi. Dans la plupart des documents XML cet espace est cosmétique. Dans les données XFA c'est la valeur : quand le paquet datasets est analysé à nouveau, chaque caractère entre <Comments> et </Comments> appartient au champ, saut de ligne compris

Schéma du cycle de sauvegarde XFA de PDFium Component où le writer ajoute un saut de ligne après les balises ouvrantes, l'analyseur de la réouverture lit le LF entre les balises Comments comme valeur du champ, et chaque sauvegarde supplémentaire ajoute un autre saut de ligne à moins que le writer ne retire que l'espace qu'il a lui-même synthétisé
Un cycle sauvegarde-réouverture plante le premier saut de ligne et chaque tour supplémentaire en ajoute un autre, voilà pourquoi la dérive ne montre sa pleine forme qu'à la seconde génération

Un champ vide se rouvre donc en contenant un LF unique. Chaque sauvegarde supplémentaire formate autour du LF déjà présent, si bien qu'un champ que personne ne touche grandit d'une ligne par tour de revue

Trimmer les valeurs au chargement ressemble à une réparation bon marché, et cela corromprait de vraies données. Les gens saisissent des espaces de tête, des espaces de fin et des retours à la ligne délibérés dans les champs XFA ; un bloc d'adresse doit garder sa structure de lignes, et un code de référence à largeur fixe doit survivre octet pour octet. Les writers XFA de PDFium Component retirent à la place uniquement l'espace que le sérialiseur synthétise lui-même autour des balises. Les valeurs utilisateur, les nœuds texte déjà présents dans le fichier et les sections CDATA passent inchangés, si bien que " indented" reste indenté et un champ volontairement vide reste vide

Emoji, paires de surrogates et wchar_t 16 bits

Un emoji revient sous la forme d'un autre caractère quand un chemin de décodage stocke une valeur scalaire Unicode complète dans un seul wchar_t, qui sur Windows fait 16 bits de large. Deux endroits d'un chargement XFA sont exposés : le décodeur du flux UTF-8, et l'analyseur des références de caractères numériques telles que &#x1F642;. U+1F642 demande 17 bits. Serrez-le dans 16 et le bit de poids haut tombe, laissant U+F642 dans la Private Use Area

Un sérialiseur de formulaire peut échouer dans la direction opposée. En filtrant les caractères un wchar_t à la fois, il voit deux unités de code de surrogate, D83D et DE42, chacune invalide seule, et les abandonne toutes les deux. L'emoji disparaît du paquet de formulaire, sans caractère de remplacement laissé derrière

Schéma de gestion des surrogates de PDFium Component où U+1F642 arrive comme la paire UTF-16 D83D DE42 et deux chemins naïfs peuvent le corrompre : les décodeurs wchar_t 16 bits tronquent le scalaire en U+F642 dans la zone à usage privé, tandis qu'un sérialiseur qui filtre les surrogates solitaires abandonne l'emoji entièrement
Le wchar_t Windows fait 16 bits de large, donc un scalaire qui demande une paire de surrogates perd sa moitié haute ou disparaît du paquet tant que les deux chemins ne gardent pas les paires ensemble

Dans PDFium Component, le décodeur consomme chaque valeur scalaire complètement et émet une paire de surrogates correcte, y compris quand le tampon de sortie n'a de place que pour une unité de plus et quand une séquence UTF-8 de quatre octets est coupée entre deux blocs de lecture. En sortie, l'exporteur de formulaire garde les paires de surrogates valides ensemble, et les références de caractères numériques se décodent aussi en paires correctes

Des données de test Latin-1 ne touchent aucun de ces chemins. Un test d'aller-retour pour un formulaire XFA demande au moins un caractère au-dessus de U+FFFF dans un champ texte, et vérifier dans les octets sauvegardés la séquence UTF-8 de quatre octets F0 9F 99 82 est plus parlant que regarder le champ rendu

XFA à flux unique et résultat de sauvegarde

Un document XFA à flux unique ne garde ses modifications que si le chemin de sauvegarde peut réécrire un flux XDP sur place, et toute entrée qu'il ne peut pas réécrire doit faire échouer la sauvegarde. ISO 32000-1 §12.7.8 permet à l'entrée /XFA du dictionnaire de formulaire interactif d'être un tableau qui alterne noms de paquets et flux, ou un flux unique contenant tout le document XDP. Un chemin de sauvegarde écrit uniquement pour les tableaux refuse les flux uniques, et si l'appelant ignore ce résultat, le PDF est écrit avec les données de formulaire à leurs anciennes valeurs

Le runtime V8 de PDFium Component gère un sous-ensemble défini des flux uniques en trois étapes. Il exporte les deux paquets vivants, datasets et form, vers une zone de montage et les valide. Ce n'est qu'alors qu'il remplace les paquets correspondants à l'intérieur de l'XDP d'origine, en gardant les autres paquets et les déclarations d'espaces de noms racine. Si le montage échoue, le flux XFA persistant n'est jamais touché et le document garde sa marque de modification, si bien qu'une sauvegarde ultérieure peut réessayer

Pipeline de sauvegarde XFA à flux unique de PDFium Component où les paquets vivants datasets et form sont exportés vers le montage, validés, puis remplacés à l'intérieur de l'XDP d'origine avec les commentaires préservés via des marqueurs, tandis que les échecs de montage et des entrées comme les DTD ou XMLDSig refusent explicitement la sauvegarde
L'export monté est validé avant que quoi que ce soit ne soit remplacé, donc une sauvegarde échouée laisse le flux XFA persistant intact et le document garde sa marque de modification

Les commentaires XML et les instructions de traitement demandent un soin supplémentaire, parce que l'analyseur utilisé pour la réécriture les abandonne. Chacun est échangé contre un marqueur unique avant l'analyse et remis ensuite, et le flux n'est écrit que si chaque marqueur apparaît exactement une fois, si bien que les commentaires hors des paquets vivants gardent leur texte et leur ordre

Certaines entrées sont refusées d'emblée, et chaque refus vous arrive comme une sauvegarde échouée :

  • Commentaires ou instructions de traitement à l'intérieur des paquets vivants datasets ou form, puisqu'il n'y a aucun moyen de projeter leurs positions d'origine dans du contenu fraîchement exporté
  • Déclarations DTD et signatures XMLDSig, puisque réécrire l'XDP ne peut pas garder une signature XML valide
  • UTF-8 ou UTF-16 invalide, balises incomplètes, références de caractères invalides, entités inconnues et instructions de traitement malformées, qui sont rejetées au lieu d'être réparées à la volée

Refuser est le meilleur compromis ici. Une sauvegarde qui renvoie False peut être retentée, journalisée ou remise à une personne, tandis qu'un XDP discrètement normalisé peut casser une signature ou un importeur en aval des semaines plus tard, loin du code qui l'a modifié. Ce que le chemin à flux unique préserve, c'est le modèle de contenu XML, écrit en UTF-8 ; la disposition des octets d'origine et la déclaration d'encodage du flux source ne sont pas transportées

Le dernier bloc tamponné

Le dernier piège se situe sous le XFA, dans le writer PDF générique. Un file writer qui tamponne la sortie en blocs de taille fixe doit pousser le dernier bloc partiel à la fin. Si cela arrive dans du code de nettoyage après que le document writer a déjà annoncé le succès, un disque plein ou une erreur d'E/S sur le dernier bloc n'atteint jamais l'appelant, et le fichier sur disque est court. Dans les deux runtimes de PDFium Component, le flush final fait partie du résultat de sauvegarde, et la marque de modification XFA n'est effacée qu'une fois l'écriture réellement réussie

Le côté Delphi ajoute une couche de plus. TPdf.SaveAs écrit dans un fichier temporaire à côté de la cible et ne le déplace sur la cible que lorsque la sauvegarde du flux renvoie True. Un résultat False laisse le fichier précédent exactement tel qu'il était, et un échec du remplacement final lève une erreur OS au lieu de revenir en silence

Pourquoi un formulaire XFA dynamique se rouvre-t-il avec moins de pages ?

Un formulaire XFA dynamique se rouvre avec moins de pages quand son sous-formulaire racine ne déclare pas restoreState="auto", et cette décision appartient à l'auteur du formulaire. Dans XFA 3.3, restoreState sur le sous-formulaire racine vaut manual par défaut. Sous manual, le processeur XFA ne restaure qu'un état limité depuis le paquet de formulaire sauvegardé et laisse le reste aux scripts du formulaire. Les valeurs de champs et les nombres d'instances des sous-formulaires répétés reviennent ; les propriétés géométriques fixées à l'exécution, non

Supposez un formulaire de trois pages dont le script porte un sous-formulaire à h="450pt" pendant que l'utilisateur le remplit. Le paquet de formulaire sauvegardé contient la nouvelle hauteur, les valeurs de champs et les nombres d'instances. À la réouverture, la mise en page est reconstruite depuis les hauteurs du template, le sous-formulaire rétrécit, et le contenu se redistribue sur deux pages. C'est le comportement que la spécification XFA demande quand le template n'a jamais demandé de restauration automatique. Le déclarer sur le sous-formulaire racine change la réouverture :

<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">
      <!-- champs ; les scripts peuvent changer h ou ajouter des instances à l’exécution -->
    </subform>
  </subform>
</template>

Si vous ne possédez pas le template, laissez-le tel quel : un formulaire construit pour le mode manual attend que ses propres scripts d'initialisation reconstruisent l'état, et changer le mode dessous d'eux modifie ce autour de quoi ces scripts ont été écrits. La repagination à chaud pendant que l'utilisateur tape est un autre mécanisme, décrit dans comment PDFium Component suit les nombres de pages XFA dynamiques et les champs déplacés

Vérifier un aller-retour XFA depuis Delphi

Une sauvegarde XFA se vérifie en rouvrant le fichier sauvegardé dans une instance TPdf fraîche et en relisant les données stockées, car un True de SaveAs dit seulement que le fichier a été écrit. TPdf.GetXfaDatasets renvoie le paquet datasets tel qu'il est stocké dans le document, pas le modèle de données vivant, donc le lire avant la sauvegarde montre les valeurs du dernier chargement. Après une réouverture, il montre exactement ce qui a été écrit. Un document à flux unique n'a pas de paquets nommés séparément : PDFium rapporte tout l'XDP comme un paquet de nom vide, si bien que GetXfaPacketByName('datasets') et GetXfaDatasets renvoient tous deux un tableau vide, et le code ci-dessous retombe sur le flux complet de 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;          // disposition en tableau de paquets
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // flux unique : un paquet sans nom
      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);  // la sortie XDP sauvegardée est en UTF-8
  finally
    Pdf.Free;
  end;
end;

La routine de sauvegarde valide la modification en attente, vérifie le résultat de SaveAs et compare la valeur relue après réouverture. TPdf.ClearFormFieldFocus retire le focus du formulaire, et c'est le moment où PDFium valide le tampon d'édition du champ qui a le focus. TPdf.SetFocusedFormFieldText peut remplir le champ focalisé depuis le code, mais il repose sur un focus suivi via les annotations widget, qu'une page XFA dynamique ne possède en général pas ; là, il renvoie False, et le texte arrive normalement par la saisie clavier dans TPdfView

// XmlText est une fonction que vous ajoutez vous-même ; elle ne fait pas partie de 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
  // Remplissage scripté optionnel ; False signifie qu'aucun champ suivi n'a le focus
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // valide le tampon d'édition
  if not Pdf.SaveAs(FileName) then      // False : le fichier précédent reste en place
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // Rouvrez dans un TPdf frais et cherchez le texte d'élément exact
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

Le test de sous-chaîne n'est qu'un test de fumée. Un élément vide peut être écrit <Tag/>, les éléments de données peuvent porter des attributs, et l'échappement au-delà de & et < dépend du sérialiseur, donc les vérifications de production ont leur place dans un vrai analyseur XML. Exécutez la routine deux fois de suite avec la même entrée, parce que la dérive des sauts de ligne ne montre sa pleine forme qu'à la seconde génération

Les applications hôtes qui pilotent le runtime XFA directement ont aussi besoin de la disposition de callbacks qu'il attend, sujet de FPDF_FORMFILLINFO version 2 et l'ABI XFA en Delphi. Les deux runtimes Windows pour Win32 et Win64, le wrapper Delphi et C++Builder et le contrôle visualiseur TPdfView accompagnent PDFium Component for Delphi and C++Builder