Come lavorare con i campi AcroForm in TypeScript

Questa guida mostra come aggiungere e appiattire i campi AcroForm con Aspose.PDF FOSS per TypeScript. Document.Form espone un metodo Add* per tipo di campo — testo, casella di controllo, gruppo radio, casella combinata, casella di elenco e pulsante — ciascuno restituisce un handle di campo tipizzato. Richiede Node.js 22 o versioni successive.

Guida passo passo

Passo 1: Installa il pacchetto

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

Verifica l’installazione importando la classe Document in un nuovo file TypeScript — questa riga dovrebbe risolversi senza errori una volta che il pacchetto è installato:

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

Passo 2: Importa le classi richieste

Importa Document per aprire il file e raggiungere doc.Form, il punto di ingresso per ogni metodo di campo utilizzato di seguito:

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

Passo 3: Aggiungi un campo di testo e una casella di controllo

Form.AddTextField(init) e Form.AddCheckbox(init) accettano entrambi un numero page, un rect, un name univoco e opzioni di stile:

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],
});

Passo 4: Aggiungi un gruppo di opzioni radio, una casella combinata e una casella di elenco

Form.AddRadioGroup(init) accetta un singolo name condiviso da ogni opzione nel suo array options, ciascuna con il proprio valore rect e export. Form.AddComboBox(init) e Form.AddListBox(init) accettano un array options di coppie { export, display }; le caselle di elenco supportano inoltre 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' },
  ],
});

Passo 5: Aggiungi un pulsante

Form.AddPushButton(init) accetta un caption e un action che descrive cosa fa il pulsante quando viene cliccato — ad esempio, inviare i dati del modulo a un URL:

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

Passo 6: Appiattire i campi del modulo

Ogni gestore di campo restituito da una chiamata Add* ha un metodo Flatten() che incorpora il valore corrente nello stream di contenuto della pagina e lo rimuove dall’AcroForm interattivo:

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');

Problemi comuni e soluzioni

Un campo non appare nella pagina prevista. page nel campo init l’oggetto è il numero di pagina della pagina stessa, non un indice di array — confermarlo contro page.Number sul target Page.

Le opzioni Radio button non sono mutualmente esclusive. Ogni opzione in Form.AddRadioGroup()’s options l’array deve condividere l’unico del gruppo name — mescolare i nomi dei campi crea caselle di controllo indipendenti invece di un gruppo di pulsanti radio.

Il valore di un campo appiattito non compare nel file salvato. Salva il documento (doc.WriteTo() / doc.Save()) dopo aver chiamato Flatten() — la modifica esiste solo in memoria finché il file non viene riscritto.

Una casella combinata mostra il valore di esportazione invece del testo visualizzato. L’aspetto disegna display; il valore memorizzato del campo (/V) è export — conferma che entrambi siano impostati per ogni opzione, non solo uno.

Domande frequenti

Posso leggere il valore attuale di un campo dopo che il modulo è stato compilato?

Sì — leggi la proprietà Value della maniglia del campo, oppure itera doc.Form.Fields per ispezionare ogni campo nel documento.

Qual è la differenza tra `Flatten()` su un campo e su un’annotazione?

Entrambi incorporano contenuti interattivi nel contenuto della pagina statica e lo rimuovono dalla rispettiva collezione — di un campo’s Flatten() lo rimuove da /AcroForm, mentre quello di un’annotazione’s Flatten() (coperto nella Annotazioni guida) lo rimuove dal page’s /Annots.

Una casella di riepilogo può consentire selezioni multiple?

Sì — imposta multiSelect: true sull’oggetto init di Form.AddListBox() e passa un array a value.

Un pulsante push ha bisogno di un’azione per essere utile?

Un action (ad esempio { type: 'submit', url, format }) è ciò che fa sì che il pulsante faccia qualcosa quando viene cliccato; senza di esso viene renderizzato ma non ha alcun comportamento collegato.