Hoe u met AcroForm-velden werkt in TypeScript

Deze gids laat zien hoe je AcroForm velden kunt toevoegen en platmaken met Aspose.PDF FOSS voor TypeScript. Document.Form biedt één Add*-methode per veldtype — tekst, selectievakje, radiogroep, combobox, lijstvak en drukknop — die elk een getypeerde veldhandle teruggeven. Het vereist Node.js 22 of hoger.

Stap-voor-stap gids

Stap 1: Installeer het pakket

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

Verifieer de installatie door de Document-klasse te importeren in een nieuw TypeScript-bestand — deze regel zou zonder fout moeten resolven zodra het pakket is geïnstalleerd:

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

Stap 2: Importeer vereiste klassen

Importeer Document om het bestand te openen en doc.Form te bereiken, het toegangspunt voor elke veldmethode die hieronder wordt gebruikt:

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

Stap 3: Voeg een Tekstveld en Checkbox toe

Form.AddTextField(init) en Form.AddCheckbox(init) nemen beide een page nummer, een rect, een unieke name, en stijlopties:

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

Stap 4: Voeg een Radiogroep, Combo Box en Lijstvak toe

Form.AddRadioGroup(init) neemt een enkele name die door elke optie in zijn options array wordt gedeeld, elk met zijn eigen rect en export waarde. Form.AddComboBox(init) en Form.AddListBox(init) nemen een options array van { export, display } paren; lijstvakken ondersteunen daarnaast 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' },
  ],
});

Stap 5: Voeg een Push Button toe

Form.AddPushButton(init) neemt een caption en een action die beschrijft wat de knop doet wanneer erop geklikt wordt — bijvoorbeeld het verzenden van de formuliergegevens naar een URL:

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

Stap 6: Formuliervelden platmaken

Elke veldhandle die wordt geretourneerd door een Add*-aanroep heeft een Flatten()-methode die de huidige waarde in de contentstream van de pagina verwerkt en deze verwijdert uit de interactieve AcroForm:

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

Veelvoorkomende problemen en oplossingen

Een veld wordt niet weergegeven op de bedoelde pagina. page in het veld init object is dat paginanummer van die pagina zelf, geen array-index — bevestig het tegen page.Number op het doel Page.

Radioknopopties zijn niet onderling exclusief. Elke optie in Form.AddRadioGroup()’s options array moet de enkele van de groep delen name — het mengen van veldnamen creëert onafhankelijke selectievakjes in plaats van een radiogroep.

De waarde van een afgevlakt veld verschijnt niet in het opgeslagen bestand. Sla het document (doc.WriteTo() / doc.Save()) na het aanroepen Flatten() — de wijziging bestaat alleen in het geheugen totdat het bestand opnieuw wordt weggeschreven.

Een keuzelijst toont de exportwaarde in plaats van de weergavetekst. De weergave tekent display; de opgeslagen waarde van het veld (/V) is export — bevestig dat beide voor elke optie zijn ingesteld, niet slechts één.

Veelgestelde vragen

Kan ik de huidige waarde van een veld lezen nadat het formulier is ingevuld?

Ja — lees de Value-eigenschap van de veldhandle, of itereer doc.Form.Fields om elk veld in het document te inspecteren.

Wat is het verschil tussen `Flatten()` op een veld en op een annotatie?

Zowel interactieve inhoud in statische paginainhoud verwerken als deze uit de respectieve collectie verwijderen — een veld’s Flatten() verwijdert het uit /AcroForm, terwijl een annotatie’s Flatten() (besproken in de Annotaties handleiding) verwijdert het uit de pagina’s /Annots.

Kan een lijstvak meerdere selecties toestaan?

Ja — stel multiSelect: true in op het init-object van Form.AddListBox() en geef een array door aan value.

Heeft een push button een actie nodig om nuttig te zijn?

Een action (bijvoorbeeld { type: 'submit', url, format }) is wat de knop iets laat doen wanneer erop geklikt wordt; zonder een dergelijke is hij wel gerenderd maar heeft hij geen gedrag gekoppeld.