Données de formulaire PDF en aller-retour : exporter et importer avec JavaScript

Lorsqu'un formulaire PDF est rempli, les valeurs saisies se fondent avec la mise en page visuelle pour former un artefact scellé. Migrer ces saisies vers un autre modèle implique de retaper chaque champ à la main. La solution consiste à traiter les données de formulaire comme un actif portable : extraire les valeurs des champs dans un fichier de données autonome, puis les réinjecter dans une copie vierge du formulaire afin de reproduire toutes les saisies en une seule passe automatique. C'est ce cycle exportation-puis-importation que Spire.PDF for JavaScript propose au moyen de PdfFormWidget.ExportData et PdfFormWidget.ImportData.

Les deux méthodes acceptent trois formats de fichier : XML, FDF et XFDF. Passer de l'un à l'autre ne revient qu'à modifier la valeur d'une énumération DataFormat — la convention d'appel reste identique ; seule la structure du fichier de sortie sur le disque change. Comme Spire.PDF for JavaScript s'exécute entièrement dans le navigateur au-dessus de WebAssembly, l'ensemble de l'aller-retour s'effectue localement via un système de fichiers virtuel (VFS), sans serveur dorsal impliqué et sans qu'aucun document ne quitte le client.

Cet article décrit le flux de données complet :

• Exporter les données de formulaire — extraire les valeurs des champs d'un formulaire rempli
• Importer les données de formulaire — réinjecter ces valeurs dans un formulaire vierge

Pour l'installation et la configuration du projet, consultez Intégrer Spire.PDF for JavaScript dans un projet React. Les exemples ci-dessous supposent que Spire.PDF est installé et que le module WebAssembly est initialisé.

Trois formats de données de formulaire en un coup d'œil

Avant de plonger dans le code, il est utile de comprendre les trois formats avec lesquels ExportData et ImportData fonctionnent. Tous les trois transportent la même charge utile — un ensemble de paires nom de champ/valeur — mais ils l'empaquettent de manières différentes. Choisir le bon dès le départ évite bien des frictions par la suite, lorsque le fichier de données doit être partagé, inspecté ou injecté dans un autre outil.

Les trois sont sans perte en ce qui concerne les valeurs des champs — rien n'est supprimé ni transformé lors de l'exportation ou de l'importation. Le choix entre eux relève uniquement de l'adéquation au flux de travail, point sur lequel nous revenons dans le guide de sélection du format ci-dessous.

Exporter les données de formulaire PDF

La première moitié de l'aller-retour est l'extraction. PdfFormWidget.ExportData prend chaque valeur de champ du formulaire et l'écrit dans un unique fichier de données. Le deuxième argument — une énumération DataFormat — détermine le format écrit. Le troisième argument est le nom du formulaire ; pour un AcroForm sans nom, passez une chaîne vide.

L'exemple ci-dessous charge un formulaire d'informations client rempli, encapsule son descripteur de formulaire dans un PdfFormWidget et exporte les valeurs des champs vers un fichier XML. Les variantes FDF et XFDF sont incluses sous forme de lignes mises en commentaire — décommentez l'une d'elles pour changer de format sans toucher à quoi que ce soit d'autre :

function App() {
  const exportFormData = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the PDF file to be exported into the VFS
    const inputFileName = 'CustomerInformationForm.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Create a PdfDocument object and load the PDF document
    const doc = new pdfModule.PdfDocument();
    doc.LoadFromFile(inputFileName);

    // Build a PdfFormWidget from the document's form handle to reach the data export API
    const formWidget = new pdfModule.PdfFormWidget(doc.Form.H);
    
    // This demo exports XML
    const dataFiles = [
      { fileName: 'FormData.xml', format: pdfModule.DataFormat.Xml },
      // { fileName: 'FormData.fdf', format: pdfModule.DataFormat.Fdf },
      // { fileName: 'FormData.xfdf', format: pdfModule.DataFormat.XFdf },
    ];

    for (const item of dataFiles) {
      // The third parameter is the form name; pass an empty string for an unnamed form
      formWidget.ExportData(item.fileName, item.format, '');
    }
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    for (const item of dataFiles) {
      const fileArray = window.dotnetRuntime.Module.FS.readFile(item.fileName);
      const blob = new Blob([fileArray], { type: 'application/octet-stream' });
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = item.fileName;
      a.click();
      URL.revokeObjectURL(url);
    }
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Export Form Data</h1>
      <button onClick={exportFormData}>
        Export
      </button>
    </div>
  );
}

export default App;

Une fois l'appel d'exportation terminé, le fichier de données réside dans le système de fichiers virtuel. Le code le relit ensuite depuis le VFS et déclenche un téléchargement par le navigateur, afin que le fichier puisse être enregistré, partagé ou archivé aux côtés d'autres données de formulaire :

Importer les données de formulaire PDF

La seconde moitié de l'aller-retour est la réhydratation. PdfFormWidget.ImportData lit un fichier de données et réécrit chaque valeur dans le champ de formulaire correspondant, par nom. Le paramètre DataFormat indique à l'analyseur comment interpréter le contenu du fichier — il n'a rien à voir avec l'extension du fichier, le format déclaré doit donc correspondre au format réel du fichier.

La cible ici est une copie vierge du formulaire d'origine. Le modèle part vide ; lorsque le fichier de données revient, chaque champ est renseigné en une seule passe — aucune ressaisie manuelle, aucune copie champ par champ, aucun besoin de tout saisir une seconde fois :

function App() {
  const importFormData = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the blank form to be filled into the VFS
    const inputFileName = 'BlankCustomerInformationForm.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // This demo refills from the XML data file
    const dataFiles = [
      { fileName: 'FormData.xml', format: pdfModule.DataFormat.Xml, outputFileName: 'ImportedXMLData.pdf' },
      // { fileName: 'FormData.fdf', format: pdfModule.DataFormat.Fdf, outputFileName: 'ImportedFDFData.pdf' },
      // { fileName: 'FormData.xfdf', format: pdfModule.DataFormat.XFdf, outputFileName: 'ImportedXFDFData.pdf' },
    ];

    for (const item of dataFiles) {
      // The data file also has to be loaded into the VFS first
      await window.spire.FetchFileToVFS(item.fileName, "", `${process.env.PUBLIC_URL}/data/`);

      const doc = new pdfModule.PdfDocument();
      doc.LoadFromFile(inputFileName);

      // Read the data file and write the values back into the fields by name
      const formWidget = new pdfModule.PdfFormWidget(doc.Form.H);
      formWidget.ImportData(item.fileName, item.format);

      doc.SaveToFile(item.outputFileName);
      doc.Close();

      // Read the generated file from the VFS and trigger the download
      const fileArray = window.dotnetRuntime.Module.FS.readFile(item.outputFileName);
      const blob = new Blob([fileArray], { type: 'application/pdf' });
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = item.outputFileName;
      a.click();
      URL.revokeObjectURL(url);
    }
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Import Form Data</h1>
      <button onClick={importFormData}>
        Import
      </button>
    </div>
  );
}

export default App;

Une fois l'appel d'importation terminé, le formulaire auparavant vierge est entièrement renseigné et prêt à être enregistré ou affiché. Le résultat est un nouveau PDF dont chaque champ est rempli à partir du fichier de données :

Choisir le bon format de données

Les trois formats contiennent des valeurs de champs identiques, la décision repose donc sur la structure et la prise en charge par les outils plutôt que sur la fidélité des données. Voici comment envisager chacun d'eux dans le contexte d'un aller-retour de données de formulaire :

• FDF produit les fichiers les plus petits. Il commence par %FDF- et utilise une notation textuelle compacte où /T porte le nom du champ et /V la valeur. Cela le rend efficace pour transmettre des données entre programmes de gestion de formulaires, mais son contenu n'est pas facilement lisible par une personne et s'accommode mal des outils de traitement de texte ou des systèmes de gestion de versions.
• XFDF est du XML standard avec un élément <field> par champ. Comme il s'agit de XML bien formé, il peut être comparé, fusionné et inspecté avec des outils textuels ordinaires, ce qui en fait le choix le plus sûr lorsque le fichier de données entre dans un système de gestion de versions, nécessite une relecture humaine ou doit interopérer avec un autre système.
• XML (XML de données de formulaire Adobe) place le nom du champ directement dans le nom de l'élément, offrant la structure la plus simple des trois. Il est idéal lorsque vous voulez simplement une liste lisible de noms de champs et de valeurs, sans formalisme supplémentaire.

En bref : utilisez FDF pour les allers-retours qui restent à l'intérieur d'un même programme ; utilisez XFDF lorsque le fichier franchit les frontières d'un outil ou d'une équipe ; utilisez XML lorsque la lisibilité est la priorité absolue.

FAQ

Certains champs sont encore vides après l'importation

Cause : ImportData effectue la correspondance par nom de champ, les noms du fichier de données doivent donc correspondre exactement aux noms des champs du formulaire — y compris la casse et les espaces. Un champ qui ne correspond pas est ignoré silencieusement ; aucune erreur n'est signalée et aucune valeur de retour n'indique une non-concordance. Seuls les champs dont les noms correspondent reçoivent une valeur.

Solution : Avant l'importation, parcourez la collection de champs du formulaire et affichez les noms réels, puis comparez-les à ceux du fichier de données :

const fields = formWidget.FieldsWidget;
for (let i = 0; i < fields.Count; i++) {
  console.log(fields.get_Item({ index: i }).Name);
}

L'importation lève Xml_MessageWithErrorPosition ou « not a valid FDF file »

Cause : ImportData analyse le fichier selon le format indiqué par le deuxième paramètre et n'inspecte jamais l'extension du fichier. Lorsque le contenu ne correspond pas au format déclaré, l'analyse échoue immédiatement : les fichiers XML signalent Xml_MessageWithErrorPosition, Xml_InvalidRootData, et un fichier non-FDF signale The source is not a valid FDF file because it does not start with "%FDF-".

Solution : Passez le DataFormat qui correspond au contenu réel du fichier, et utilisez le fichier de données exporté d'origine plutôt qu'un fichier qui a été réenregistré dans un autre format.

Voir aussi

• Remplir les champs de formulaire d'un document PDF avec JavaScript
• Créer des champs de formulaire interactifs dans un document PDF avec JavaScript
• Intégrer Spire.PDF for JavaScript dans un projet React