Cum să lucrați cu câmpurile AcroForm în TypeScript

Acest ghid arată cum să adăugați și să aplatizați câmpurile AcroForm cu Aspose.PDF FOSS pentru TypeScript. Document.Form expune o metodă Add* pentru fiecare tip de câmp — text, casetă de bifare, grup radio, casetă combo, casetă de listă și buton de apăsare — fiecare returnând un identificator de câmp tipizat. Necesită Node.js 22 sau o versiune ulterioară.

Ghid pas cu pas

Pasul 1: Instalați pachetul

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ți instalarea importând clasa Document într-un nou fișier TypeScript — această linie ar trebui să se rezolve fără erori odată ce pachetul este instalat:

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

Pasul 2: Importați clasele necesare

Importă Document pentru a deschide fișierul și a ajunge la doc.Form, punctul de intrare pentru fiecare metodă de câmp utilizată mai jos:

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

Pasul 3: Adaugă un câmp text și o casetă de selectare

Form.AddTextField(init) și Form.AddCheckbox(init) acceptă ambele un număr page, un rect, un name unic și opțiuni de stilizare:

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

Pasul 4: Adaugă un grup radio, o casetă combo și o casetă de listă

Form.AddRadioGroup(init) primește un singur name partajat de fiecare opțiune din matricea sa options, fiecare având propriul său rect și valoare export. Form.AddComboBox(init) și Form.AddListBox(init) primesc o matrice options de perechi { export, display }; casetele de listă susțin în plus 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' },
  ],
});

Pasul 5: Adaugă un buton de tip push

Form.AddPushButton(init) primește un caption și un action care descriu ce face butonul când este apăsat — de exemplu, trimiterea datelor formularului către 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' },
});

Pasul 6: Aplatizează câmpurile formularului

Fiecare identificator de câmp returnat de un apel Add* are o metodă Flatten() care încorporează valoarea curentă în fluxul de conținut al paginii și o elimină din AcroForm interactiv:

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

Probleme comune și soluții

Un câmp nu apare pe pagina dorită. page în câmpul init obiectul este numărul de pagină propriu al acelei pagini, nu un index de tablou — confirmați-l cu page.Number pe țintă Page.

Opțiunile butoanelor radio nu sunt exclusive reciproc. Fiecare opțiune din Form.AddRadioGroup()’s options tablou trebuie să împărtășească singurul al grupului name — combinarea numelor câmpurilor creează casete de selectare independente în loc de un grup radio.

Valoarea unui câmp aplatizat nu apare în fișierul salvat. Salvați documentul (doc.WriteTo() / doc.Save()) după apelare Flatten() — modificarea există doar în memorie până când fișierul este scris înapoi.

O casetă combo afișează valoarea de export în loc de textul afișat. Aspectul desenează display; valoarea stocată a câmpului (/V) este export — confirmă că ambele sunt setate pentru fiecare opțiune, nu doar una.

Întrebări frecvente

Pot să citesc valoarea curentă a unui câmp după ce formularul este completat?

Da — citește proprietatea Value a manipulatorului de câmp, sau iterează doc.Form.Fields pentru a inspecta fiecare câmp din document.

Care este diferența dintre `Flatten()` pe un câmp și pe o adnotare?

Ambele încorporează conținut interactiv în conținutul paginii statice și îl elimină din colecția sa respectivă — al unui câmp Flatten() îl elimină din /AcroForm, în timp ce al unei adnotări Flatten() (acoperit în Anotări ghid) îl elimină din pagina’s /Annots.

Poate o casetă de listă să permită selecții multiple?

Da — setează multiSelect: true pe obiectul init al Form.AddListBox() și transmite un array către value.

Un buton push are nevoie de o acțiune pentru a fi util?

Un action (de exemplu { type: 'submit', url, format }) este ceea ce face butonul să execute ceva când este apăsat; fără el, se afișează, dar nu are niciun comportament asociat.