PDF-Formulardaten im Round-Trip: Export und Import mit JavaScript

Wenn ein PDF-Formular ausgefüllt wird, verschmelzen die eingegebenen Werte mit dem visuellen Layout zu einem versiegelten Artefakt. Diese Einträge auf eine andere Vorlage zu übertragen bedeutet, jedes Feld von Hand neu einzugeben. Der Ausweg besteht darin, Formulardaten als portable Ressource zu behandeln: Feldwerte in eine eigenständige Datendatei extrahieren und sie dann wieder in eine leere Kopie des Formulars einzuspeisen, um alle Einträge in einem automatischen Durchlauf zu reproduzieren. Dieser Export-dann-Import-Zyklus ist das, was Spire.PDF für JavaScript durch PdfFormWidget.ExportData und PdfFormWidget.ImportData bietet.

Beide Methoden akzeptieren drei Dateiformate: XML, FDF und XFDF. Das Umschalten zwischen ihnen ist nichts weiter als das Ändern eines DataFormat-Enum-Werts – die Aufrufkonvention bleibt identisch; nur die Struktur der Ausgabedatei auf dem Datenträger ändert sich. Da Spire.PDF für JavaScript vollständig im Browser auf WebAssembly ausgeführt wird, erfolgt der gesamte Round-Trip lokal über ein virtuelles Dateisystem (VFS), ohne dass ein Backend-Server beteiligt ist und ohne dass das Dokument jemals den Client verlässt.

Dieser Artikel führt durch den vollständigen Datenfluss:

• Formulardaten exportieren — Feldwerte aus einem ausgefüllten Formular herausziehen
• Formulardaten importieren — diese Werte zurück in ein leeres Formular einspeisen

Informationen zur Installation und Projekteinrichtung finden Sie unter Spire.PDF für JavaScript in ein React-Projekt integrieren. Die folgenden Beispiele gehen davon aus, dass Spire.PDF installiert und das WebAssembly-Modul initialisiert ist.

Drei Formulardatenformate auf einen Blick

Bevor wir in den Code eintauchen, ist es hilfreich, die drei Formate zu verstehen, mit denen ExportData und ImportData arbeiten. Alle drei tragen die gleiche Nutzlast – eine Reihe von Feldname/Wert-Paaren –, verpacken sie aber auf unterschiedliche Weise. Wenn Sie von Anfang an das richtige auswählen, ersparen Sie sich später Reibung, wenn die Datendatei weitergegeben, überprüft oder in ein anderes Tool eingespeist werden muss.

Alle drei sind verlustfrei in Bezug auf die Feldwerte – beim Exportieren oder Importieren wird nichts verworfen oder transformiert. Die Wahl zwischen ihnen hängt ausschließlich von der Workflow-Eignung ab, worauf wir im Leitfaden zur Formatauswahl unten zurückkommen.

PDF-Formulardaten exportieren

Die erste Hälfte des Round-Trips ist die Extraktion. PdfFormWidget.ExportData nimmt jeden Feldwert im Formular und schreibt ihn in eine einzige Datendatei. Das zweite Argument – ein DataFormat-Enum – steuert, welches Format geschrieben wird. Das dritte Argument ist der Formularname; für ein unbenanntes AcroForm übergeben Sie eine leere Zeichenfolge.

Das folgende Beispiel lädt ein ausgefülltes Kundeninformationsformular, packt sein Formularhandle in ein PdfFormWidget und exportiert die Feldwerte in eine XML-Datei. Die FDF- und XFDF-Varianten sind als auskommentierte Zeilen enthalten – kommentieren Sie eine davon aus, um das Format zu wechseln, ohne etwas anderes zu ändern:

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;

Sobald der Exportaufruf abgeschlossen ist, befindet sich die Datendatei im virtuellen Dateisystem. Der Code liest sie dann aus dem VFS zurück und löst einen Browser-Download aus, damit die Datei gespeichert, weitergegeben oder zusammen mit anderen Formulardaten archiviert werden kann:

PDF-Formulardaten importieren

Die zweite Hälfte des Round-Trips ist die Rehydrierung. PdfFormWidget.ImportData liest eine Datendatei und schreibt jeden Wert anhand des Namens zurück in das passende Formularfeld. Der Parameter DataFormat teilt dem Parser mit, wie der Dateiinhalt zu interpretieren ist – er hat nichts mit der Dateiendung zu tun, daher muss das angegebene Format mit dem tatsächlichen Format der Datei übereinstimmen.

Das Ziel hier ist eine leere Kopie des Originalformulars. Die Vorlage wird leer ausgegeben; wenn die Datendatei zurückkommt, wird jedes Feld in einem einzigen Durchlauf befüllt – keine manuelle Neueingabe, kein Kopieren Feld für Feld, kein erneutes Eingeben aller Daten:

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;

Nach Abschluss des Importaufrufs ist das zuvor leere Formular vollständig befüllt und bereit, gespeichert oder angezeigt zu werden. Das Ergebnis ist ein neues PDF, bei dem jedes Feld aus der Datendatei ausgefüllt ist:

Das richtige Datenformat auswählen

Alle drei Formate enthalten identische Feldwerte, sodass die Entscheidung auf Struktur und Tool-Unterstützung hinausläuft und nicht auf Datentreue. So sollten Sie jedes einzelne im Kontext eines Formulardaten-Round-Trips betrachten:

• FDF erzeugt die kleinsten Dateien. Es beginnt mit %FDF- und verwendet eine kompakte Textnotation, bei der /T den Feldnamen und /V den Wert trägt. Dadurch ist es effizient für die Übergabe von Daten zwischen formularverarbeitenden Programmen, aber der Inhalt ist für Menschen nicht leicht zu lesen und harmoniert nicht gut mit Textwerkzeugen oder Versionskontrollsystemen.
• XFDF ist Standard-XML mit einem <field>-Element pro Feld. Da es sich um wohlgeformtes XML handelt, kann es mit gewöhnlichen Textwerkzeugen verglichen, zusammengeführt und überprüft werden, was es zur sichersten Wahl macht, wenn die Datendatei in die Versionskontrolle eingeht, von Menschen überprüft werden muss oder mit einem anderen System interoperieren soll.
• XML (Adobe Formulardaten-XML) setzt den Feldnamen direkt in den Elementnamen, was die geradlinigste Struktur der drei ergibt. Es ist ideal, wenn Sie einfach eine lesbare Liste von Feldnamen und -werten ohne zusätzlichen Aufwand wünschen.

Kurz gesagt: Verwenden Sie FDF für Round-Trips, die innerhalb eines einzigen Programms bleiben; verwenden Sie XFDF, wenn die Datei Tool- oder Teamgrenzen überschreitet; verwenden Sie XML, wenn Lesbarkeit oberste Priorität hat.

FAQ

Einige Felder sind nach dem Import noch leer

Ursache: ImportData gleicht nach Feldnamen ab, daher müssen die Namen in der Datendatei exakt mit den Feldnamen im Formular übereinstimmen – einschließlich Groß-/Kleinschreibung und Leerzeichen. Ein Feld, das nicht übereinstimmt, wird stillschweigend übersprungen; es gibt keinen Fehler und keinen Rückgabewert, der auf eine Nichtübereinstimmung hinweist. Nur die Felder, deren Namen übereinstimmen, erhalten einen Wert.

Lösung: Bevor Sie importieren, durchlaufen Sie die Feldauflistung des Formulars und geben Sie die tatsächlichen Namen aus, und vergleichen Sie sie dann mit der Datendatei:

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

Import löst Xml_MessageWithErrorPosition oder "not a valid FDF file" aus

Ursache: ImportData analysiert die Datei gemäß dem durch den zweiten Parameter angegebenen Format und prüft niemals die Dateiendung. Wenn der Inhalt nicht mit dem angegebenen Format übereinstimmt, schlägt das Parsen sofort fehl: XML-Dateien melden Xml_MessageWithErrorPosition, Xml_InvalidRootData, und eine Nicht-FDF-Datei meldet The source is not a valid FDF file because it does not start with "%FDF-".

Lösung: Übergeben Sie das DataFormat, das dem tatsächlichen Inhalt der Datei entspricht, und verwenden Sie die ursprüngliche exportierte Datendatei anstelle einer, die in einem anderen Format neu gespeichert wurde.

Siehe auch

• Formularfelder in einem PDF-Dokument mit JavaScript ausfüllen
• Interaktive Formularfelder in einem PDF-Dokument mit JavaScript erstellen
• Spire.PDF für JavaScript in ein React-Projekt integrieren