Cómo trabajar con campos AcroForm en TypeScript

Esta guía muestra cómo agregar y aplanar campos AcroForm con Aspose.PDF FOSS para TypeScript. Document.Form expone un método Add* por tipo de campo — texto, casilla de verificación, grupo de radio, cuadro combinado, cuadro de lista y botón pulsador — cada uno devolviendo un manejador de campo tipado. Requiere Node.js 22 o posterior.

Guía paso a paso

Paso 1: Instalar el paquete

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Verifique la instalación importando la clase Document en un nuevo archivo TypeScript — esta línea debería resolverse sin errores una vez que el paquete esté instalado:

import { Document } from '@asposefoss/pdf';

Paso 2: Importar clases requeridas

Importa Document para abrir el archivo y alcanzar doc.Form, el punto de entrada para cada método de campo utilizado a continuación:

import { Document } from '@asposefoss/pdf';

Paso 3: Añadir un campo de texto y una casilla de verificación

Form.AddTextField(init) y Form.AddCheckbox(init) ambos aceptan un número page, un rect, un name único, y opciones de estilo:

const doc = Document.OpenFile('form-template.pdf');
const form = doc.Form;
const pageNum = doc.Pages[0].Number;

form.AddTextField({
  page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
  borderColor: [0.1, 0.15, 0.4], font: 'Helvetica', fontSize: 12,
});

form.AddCheckbox({
  page: pageNum, rect: [200, 630, 218, 648], name: 'Subscribe',
  checked: true, borderColor: [0.1, 0.15, 0.4],
});

Paso 4: Añadir un grupo de radio, un cuadro combinado y un cuadro de lista

Form.AddRadioGroup(init) recibe un único name compartido por cada opción en su matriz options, cada una con su propio valor rect y export. Form.AddComboBox(init) y Form.AddListBox(init) reciben una matriz options de pares { export, display }; los cuadros de lista además admiten multiSelect:

form.AddRadioGroup({
  name: 'Plan', selected: 'Pro',
  options: [
    { page: pageNum, rect: [200, 590, 218, 608], export: 'Basic' },
    { page: pageNum, rect: [290, 590, 308, 608], export: 'Pro' },
  ],
});

form.AddComboBox({
  page: pageNum, rect: [200, 550, 350, 570], name: 'Country', value: 'US',
  options: [
    { export: 'US', display: 'United States' },
    { export: 'UK', display: 'United Kingdom' },
  ],
});

form.AddListBox({
  page: pageNum, rect: [200, 410, 350, 510], name: 'Interests',
  multiSelect: true, value: ['pdf'],
  options: [
    { export: 'pdf', display: 'PDF Engineering' },
    { export: 'crypto', display: 'Cryptography' },
  ],
});

Paso 5: Añadir un botón pulsador

Form.AddPushButton(init) recibe un caption y un action que describe lo que hace el botón al hacer clic — por ejemplo, enviar los datos del formulario a una URL:

form.AddPushButton({
  page: pageNum, rect: [200, 320, 320, 388], name: 'Submit',
  caption: 'Submit',
  action: { type: 'submit', url: 'https://example.com/submit', format: 'fdf' },
});

Paso 6: Aplanar los campos del formulario

Cada identificador de campo devuelto por una llamada Add* tiene un método Flatten() que incorpora su valor actual en el flujo de contenido de la página y lo elimina del AcroForm interactivo:

const tb = form.AddTextField({
  page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten(); // -> number; bakes the value, unwires the field from /AcroForm

doc.WriteTo('flattened.pdf');

Problemas comunes y soluciones

Un campo no aparece en la página prevista. page en el campo init el objeto es el número de página propio de esa página, no un índice de matriz — confírmalo contra page.Number en el objetivo Page.

Las opciones de botones de radio no son mutuamente exclusivas. Cada opción en Form.AddRadioGroup()’s options array debe compartir el único del grupo name — mezclar nombres de campo crea casillas de verificación independientes en lugar de un grupo de botones de opción.

El valor de un campo aplanado no aparece en el archivo guardado. Guarde el documento (doc.WriteTo() / doc.Save()) después de llamar Flatten() — el cambio solo existe en la memoria hasta que el archivo se vuelve a escribir.

Un cuadro combinable muestra el valor de exportación en lugar del texto de visualización. La apariencia dibuja display; el valor almacenado del campo (/V) es export — confirma que ambos estén configurados para cada opción, no solo una.

Preguntas frecuentes

¿Puedo leer el valor actual de un campo después de que se haya completado el formulario?

Sí — lea la propiedad Value del manejador del campo, o itere doc.Form.Fields para inspeccionar cada campo en el documento.

¿Cuál es la diferencia entre `Flatten()` en un campo y en una anotación?

Ambos incorporan contenido interactivo en el contenido estático de la página y lo eliminan de su colección respectiva — de un campo. Flatten() lo elimina de /AcroForm, mientras que la de una anotación Flatten() (cubierto en el Anotaciones guía) lo elimina de la página /Annots.

¿Puede un cuadro de lista permitir múltiples selecciones?

Sí — establezca multiSelect: true en el objeto init de Form.AddListBox() y pase una matriz a value.

¿Necesita un botón pulsador una acción para ser útil?

Un action (por ejemplo { type: 'submit', url, format }) es lo que hace que el botón haga algo al hacer clic; sin él, se renderiza pero no tiene ningún comportamiento conectado.