Hur man arbetar med AcroForm-fält i TypeScript

Denna guide visar hur man lägger till och plattar till AcroForm fält med Aspose.PDF FOSS för TypeScript. Document.Form exponerar en Add* metod per fälttyp — text, kryssruta, radiogrupp, kombinationsruta, listbox och tryckknapp — som returnerar ett typat fälthandtag. Det kräver Node.js 22 eller senare.

Steg-för-steg-guide

Steg 1: Installera paketet

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

Verifiera installationen genom att importera Document-klassen i en ny TypeScript-fil — den här raden bör lösa sig utan fel när paketet är installerat:

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

Steg 2: Importera nödvändiga klasser

Importera Document för att öppna filen och nå doc.Form, ingångspunkten för varje fältmetod som används nedan:

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

Steg 3: Lägg till ett textfält och en kryssruta

Form.AddTextField(init) och Form.AddCheckbox(init) tar båda ett page nummer, en rect, en unik name och stilalternativ:

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

Steg 4: Lägg till en radiogrupp, en kombinationsruta och en listruta

Form.AddRadioGroup(init) tar ett enda name som delas av varje alternativ i dess options array, var och en med sitt eget rect och export värde. Form.AddComboBox(init) och Form.AddListBox(init) tar en options array av { export, display } par; listrutor stöder dessutom 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' },
  ],
});

Steg 5: Lägg till en tryckknapp

Form.AddPushButton(init) tar ett caption och en action som beskriver vad knappen gör när den klickas — till exempel, att skicka formulärets data till en URL:

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

Steg 6: Platta till formulärfält

Varje fälthandtag som returneras av ett Add*-anrop har en Flatten()-metod som bäddar in dess aktuella värde i sidans innehållsström och tar bort det från den interaktiva 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');

Vanliga problem och lösningar

Ett fält visas inte på den avsedda sidan. page i fältets init objekt är den sidans eget sidnummer, inte ett array-index — bekräfta det mot page.Number på målet Page.

Radioknappsalternativ är inte ömsesidigt uteslutande. Varje alternativ i Form.AddRadioGroup()’s options array måste dela gruppens enda name — att blanda fältnamn skapar separata kryssrutor istället för en radiogrupp.

Värdet för ett plattat fält visas inte i den sparade filen. Spara dokumentet (doc.WriteTo() / doc.Save()) efter att ha anropat Flatten() — förändringen finns endast i minnet tills filen skrivs tillbaka.

En kombinationsruta visar exportvärdet istället för visningstexten. Utseendet ritar display; fältets lagrade värde (/V) är export — bekräfta att båda är inställda för varje alternativ, inte bara ett.

Vanliga frågor

Kan jag läsa ett fälts aktuella värde efter att formuläret har fyllts i?

Ja — läs fälthandtagets Value egenskap, eller iterera doc.Form.Fields för att inspektera varje fält i dokumentet.

Vad är skillnaden mellan `Flatten()` på ett fält och på en annotation?

Både bakar interaktivt innehåll i statiskt sidinnehåll och tar bort det från dess respektive samling — ett fälts Flatten() tar bort det från /AcroForm, medan en annoterings Flatten() (täckt i Annotationer guide) tar bort det från sidans /Annots.

Kan en listbox tillåta flera val?

Ja — sätt multiSelect: true på Form.AddListBox()s init-objekt och skicka en array till value.

Behöver en push button en åtgärd för att vara användbar?

En action (till exempel { type: 'submit', url, format }) är det som får knappen att göra något när den klickas; utan en sådan renderas den men har ingen funktion kopplad.