Wie man mit AcroForm-Feldern in TypeScript arbeitet

Dieses Handbuch zeigt, wie man AcroForm-Felder mit Aspose.PDF FOSS für TypeScript hinzufügt und flacht. Document.Form stellt für jeden Feldtyp — Text, Kontrollkästchen, Radiogruppe, Kombinationsfeld, Listbox und Schaltfläche — eine Add*-Methode bereit, die jeweils einen typisierten Feld-Handle zurückgibt. Es erfordert Node.js 22 oder neuer.

Schritt-für-Schritt-Anleitung

Schritt 1: Paket installieren

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

Verifiziere die Installation, indem du die Document-Klasse in einer neuen TypeScript-Datei importierst — diese Zeile sollte sich ohne Fehler auflösen, sobald das Paket installiert ist:

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

Schritt 2: Erforderliche Klassen importieren

Importieren Sie Document, um die Datei zu öffnen und doc.Form zu erreichen, den Einstiegspunkt für jede unten verwendete Feldmethode:

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

Schritt 3: Textfeld und Kontrollkästchen hinzufügen

Form.AddTextField(init) und Form.AddCheckbox(init) erhalten beide eine page Nummer, ein rect, ein eindeutiges name und Stiloptionen:

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

Schritt 4: Radiogruppe, Kombinationsfeld und Listbox hinzufügen

Form.AddRadioGroup(init) akzeptiert ein einzelnes name, das von jeder Option in seinem options-Array gemeinsam genutzt wird, wobei jede ihr eigenes rect und export-Wert hat. Form.AddComboBox(init) und Form.AddListBox(init) akzeptieren ein options-Array von { export, display }-Paaren; Listboxen unterstützen zusätzlich 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' },
  ],
});

Schritt 5: Push-Button hinzufügen

Form.AddPushButton(init) akzeptiert ein caption und ein action, das beschreibt, was die Schaltfläche beim Klicken tut — zum Beispiel das Senden der Formulardaten an eine URL:

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

Schritt 6: Formularfelder flachlegen

Jeder Feld-Handle, der von einem Add*-Aufruf zurückgegeben wird, verfügt über eine Flatten()-Methode, die den aktuellen Wert in den Inhaltsstream der Seite einbettet und ihn aus dem interaktiven AcroForm entfernt:

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

Häufige Probleme und Lösungen

Ein Feld erscheint nicht auf der vorgesehenen Seite. page im Feld’s init Objekt ist die eigene Seitennummer dieser Seite, nicht ein Array-Index — prüfen Sie es gegen page.Number auf dem Ziel Page.

Radio-Button-Optionen schließen sich nicht gegenseitig aus. Jede Option in Form.AddRadioGroup()’s options Array muss das einzelne Element der Gruppe teilen. name — das Mischen von Feldnamen erzeugt unabhängige Kontrollkästchen statt einer Optionsgruppe.

Der Wert eines abgeflachten Feldes erscheint nicht in der gespeicherten Datei. Speichern Sie das Dokument (doc.WriteTo() / doc.Save()) nach dem Aufruf Flatten() — die Änderung existiert nur im Speicher, bis die Datei wieder zurückgeschrieben wird.

Ein Kombinationsfeld zeigt den Exportwert anstelle des Anzeigetextes. Die Darstellung zeichnet display; der gespeicherte Wert des Feldes (/V) ist export — bestätigen Sie, dass beide für jede Option gesetzt sind, nicht nur für eine.

Häufig gestellte Fragen

Kann ich den aktuellen Wert eines Feldes auslesen, nachdem das Formular ausgefüllt wurde?

Ja — lesen Sie die Value-Eigenschaft des Feld-Handles, oder iterieren Sie doc.Form.Fields, um jedes Feld im Dokument zu prüfen.

Was ist der Unterschied zwischen `Flatten()` bei einem Feld und bei einer Annotation?

Beide betten interaktive Inhalte in den statischen Seiteninhalt ein und entfernen sie aus ihrer jeweiligen Sammlung — eines Feldes Flatten() entfernt es von /AcroForm, während einer Anmerkung Flatten() (abgedeckt im Anmerkungen guide) entfernt es von der Seite /Annots.

Kann eine Listbox mehrere Auswahlmöglichkeiten zulassen?

Ja — setzen Sie multiSelect: true auf das init-Objekt von Form.AddListBox() und übergeben Sie ein Array an value.

Benötigt ein Push-Button eine Aktion, um nützlich zu sein?

Ein action (zum Beispiel { type: 'submit', url, format }) ist das, was den Button bei einem Klick etwas tun lässt; ohne ein solches wird er zwar gerendert, hat aber kein verknüpftes Verhalten.