Datos de formulario PDF de ida y vuelta: exportar e importar con JavaScript

Cuando se rellena un formulario PDF, los valores introducidos se fusionan con el diseño visual en un artefacto sellado. Migrar esas entradas a una plantilla diferente significa volver a escribir cada campo a mano. La solución es tratar los datos del formulario como un activo portátil: extraer los valores de los campos en un archivo de datos independiente y luego volver a introducirlos en una copia en blanco del formulario para reproducir todas las entradas en una sola pasada automática. Este ciclo de exportación e importación es lo que Spire.PDF for JavaScript ofrece mediante PdfFormWidget.ExportData y PdfFormWidget.ImportData.

Ambos métodos aceptan tres formatos de archivo: XML, FDF y XFDF. Cambiar entre ellos no es más que cambiar un valor de enumeración DataFormat: la convención de llamada sigue siendo idéntica; solo cambia la estructura en disco del archivo de salida. Dado que Spire.PDF for JavaScript se ejecuta completamente en el navegador sobre WebAssembly, todo el ciclo se ejecuta localmente a través de un sistema de archivos virtual (VFS), sin servidor backend y sin que ningún documento salga del cliente.

Este artículo recorre el flujo de datos completo:

• Exportar datos de formulario — extraer los valores de los campos de un formulario rellenado
• Importar datos de formulario — volver a introducir esos valores en un formulario en blanco

Para la instalación y la configuración del proyecto, consulte Integrar Spire.PDF for JavaScript en un proyecto de React. Los ejemplos siguientes suponen que Spire.PDF está instalado y que el módulo WebAssembly está inicializado.

Tres formatos de datos de formulario de un vistazo

Antes de sumergirse en el código, conviene entender los tres formatos con los que trabajan ExportData e ImportData. Los tres transportan la misma carga útil —un conjunto de pares nombre de campo/valor—, pero la empaquetan de maneras diferentes. Elegir el correcto desde el principio ahorra fricción más adelante, cuando el archivo de datos deba compartirse, inspeccionarse o introducirse en otra herramienta.

Los tres son sin pérdida con respecto a los valores de los campos: nada se descarta ni se transforma durante la exportación o la importación. La elección entre ellos se reduce únicamente a la adecuación al flujo de trabajo, a lo que volvemos en la guía de selección de formato a continuación.

Exportar datos de formulario PDF

La primera mitad del ciclo es la extracción. PdfFormWidget.ExportData toma todos los valores de los campos del formulario y los escribe en un único archivo de datos. El segundo argumento —una enumeración DataFormat— controla qué formato se escribe. El tercer argumento es el nombre del formulario; para un AcroForm sin nombre, pase una cadena vacía.

El ejemplo siguiente carga un formulario de información del cliente ya rellenado, envuelve su controlador de formulario en un PdfFormWidget y exporta los valores de los campos a un archivo XML. Las variantes FDF y XFDF se incluyen como líneas comentadas: descomente cualquiera de ellas para cambiar de formato sin tocar nada más:

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;

Una vez finalizada la llamada de exportación, el archivo de datos reside en el sistema de archivos virtual. A continuación, el código lo vuelve a leer desde el VFS y desencadena una descarga del navegador para que el archivo pueda guardarse, compartirse o archivarse junto con otros datos de formulario:

Importar datos de formulario PDF

La segunda mitad del ciclo es la rehidratación. PdfFormWidget.ImportData lee un archivo de datos y vuelve a escribir cada valor en el campo de formulario correspondiente por nombre. El parámetro DataFormat indica al analizador cómo interpretar el contenido del archivo; no tiene nada que ver con la extensión del archivo, por lo que el formato declarado debe coincidir con el formato real del archivo.

El objetivo aquí es una copia en blanco del formulario original. La plantilla sale vacía; cuando vuelve el archivo de datos, todos los campos se rellenan en una sola pasada: sin reintroducción manual, sin copia campo por campo, sin necesidad de teclear todo una segunda vez:

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;

Una vez completada la llamada de importación, el formulario que antes estaba en blanco queda totalmente rellenado y listo para guardarse o mostrarse. El resultado es un nuevo PDF con todos los campos rellenados a partir del archivo de datos:

Elegir el formato de datos adecuado

Los tres formatos contienen valores de campo idénticos, por lo que la decisión se reduce a la estructura y la compatibilidad con herramientas, más que a la fidelidad de los datos. He aquí cómo pensar en cada uno en el contexto de un ciclo de datos de formulario:

• FDF produce los archivos más pequeños. Comienza con %FDF- y utiliza una notación de texto compacta donde /T contiene el nombre del campo y /V el valor. Esto lo hace eficiente para pasar datos entre programas de gestión de formularios, pero una persona no puede leer fácilmente su contenido y no se lleva bien con herramientas de texto ni sistemas de control de versiones.
• XFDF es XML estándar con un elemento <field> por campo. Como es XML bien formado, se puede comparar, fusionar e inspeccionar con herramientas de texto normales, lo que lo convierte en la opción más segura cuando el archivo de datos entra en control de versiones, necesita revisión humana o debe interoperar con otro sistema.
• XML (XML de datos de formulario de Adobe) coloca el nombre del campo directamente en el nombre del elemento, lo que da la estructura más sencilla de las tres. Es ideal cuando simplemente se desea una lista legible de nombres de campos y valores sin ninguna complicación adicional.

En resumen: use FDF para ciclos que permanecen dentro de un solo programa; use XFDF cuando el archivo cruce fronteras de herramientas o equipos; use XML cuando la legibilidad sea la máxima prioridad.

Preguntas frecuentes

Algunos campos siguen vacíos después de la importación

Causa: ImportData coincide por nombre de campo, por lo que los nombres del archivo de datos deben coincidir exactamente con los nombres de los campos del formulario, incluidos mayúsculas/minúsculas y espacios en blanco. Un campo que no coincide se omite silenciosamente; no hay error ni valor de retorno que indique una discrepancia. Solo los campos cuyos nombres coinciden reciben un valor.

Solución: antes de importar, recorra la colección de campos del formulario e imprima los nombres reales, y luego compárelos con el archivo de datos:

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

La importación lanza Xml_MessageWithErrorPosition o "not a valid FDF file"

Causa: ImportData analiza el archivo según el formato indicado por el segundo parámetro y nunca inspecciona la extensión del archivo. Cuando el contenido no coincide con el formato declarado, el análisis falla de inmediato: los archivos XML informan Xml_MessageWithErrorPosition, Xml_InvalidRootData, y un archivo no FDF informa The source is not a valid FDF file because it does not start with "%FDF-".

Solución: pase el DataFormat que coincida con el contenido real del archivo y utilice el archivo de datos exportado original en lugar de uno que se haya vuelto a guardar en un formato diferente.

Véase también

• Rellenar campos de formulario en un documento PDF con JavaScript
• Crear campos de formulario interactivos en un documento PDF con JavaScript
• Integrar Spire.PDF for JavaScript en un proyecto de React