Πώς να εργαστείτε με πεδία AcroForm σε TypeScript

Αυτός ο οδηγός δείχνει πώς να προσθέσετε και να ισοπεδώσετε πεδία AcroForm με το Aspose.PDF FOSS για TypeScript. Το Document.Form εκθέτει μία μέθοδο Add* ανά τύπο πεδίου — κείμενο, πλαίσιο ελέγχου, ομάδα ραδιοφώνου, συνδυαστικό πλαίσιο, πλαίσιο λίστας και κουμπί — η καθεμία επιστρέφει έναν τυποποιημένο χειριστή πεδίου. Απαιτεί Node.js 22 ή νεότερο.

Οδηγός βήμα-βήμα

Βήμα 1: Εγκατάσταση του πακέτου

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

Επαληθεύστε την εγκατάσταση εισάγοντας την κλάση Document σε ένα νέο αρχείο TypeScript — αυτή η γραμμή πρέπει να λυθεί χωρίς σφάλμα μόλις το πακέτο εγκατασταθεί:

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

Βήμα 2: Εισαγωγή των απαιτούμενων κλάσεων

Εισαγάγετε το Document για να ανοίξετε το αρχείο και να φτάσετε στο doc.Form, το σημείο εισόδου για κάθε μέθοδο πεδίου που χρησιμοποιείται παρακάτω:

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

Βήμα 3: Προσθέστε ένα πεδίο κειμένου και ένα πλαίσιο ελέγχου

Form.AddTextField(init) και Form.AddCheckbox(init) δέχονται και οι δύο έναν αριθμό page, ένα rect, ένα μοναδικό name και επιλογές στυλ:

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

Βήμα 4: Προσθέστε μια ομάδα ραδιοπλήκτρων, ένα Combo Box και ένα List Box

Form.AddRadioGroup(init) δέχεται ένα μόνο name που μοιράζεται από κάθε επιλογή στον πίνακα options, καθεμία με τη δική της τιμή rect και export. Form.AddComboBox(init) και Form.AddListBox(init) δέχονται έναν πίνακα options από ζεύγη { export, display }; τα πλαίσια λίστας υποστηρίζουν επιπλέον 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' },
  ],
});

Βήμα 5: Προσθέστε ένα Push Button

Form.AddPushButton(init) δέχεται ένα caption και ένα action που περιγράφει τι κάνει το κουμπί όταν πατηθεί — για παράδειγμα, την αποστολή των δεδομένων της φόρμας σε ένα URL:

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

Βήμα 6: Ισοπεδώστε τα πεδία της φόρμας

Κάθε χειριστήριο πεδίου που επιστρέφεται από μια κλήση Add* διαθέτει μια μέθοδο Flatten() που ενσωματώνει την τρέχουσα τιμή του στη ροή περιεχομένου της σελίδας και την αφαιρεί από το διαδραστικό 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');

Κοινά Προβλήματα και Διορθώσεις

Ένα πεδίο δεν εμφανίζεται στη σελίδα που προορίζεται. page στο πεδίο init το αντικείμενο είναι ο δικός αριθμός σελίδας αυτής της σελίδας, όχι δείκτης πίνακα — επιβεβαιώστε το έναντι page.Number στον προορισμό Page.

Οι επιλογές των κουμπιών ραδιοφώνου δεν είναι αμοιβαία αποκλειστικές. Κάθε επιλογή στο Form.AddRadioGroup()του options ο πίνακας πρέπει να μοιράζεται το μοναδικό της ομάδας name — η ανάμειξη ονομάτων πεδίων δημιουργεί ανεξάρτητα πλαίσια ελέγχου αντί για radio group.

Η τιμή ενός flattened field δεν εμφανίζεται στο αποθηκευμένο αρχείο. Αποθηκεύστε το έγγραφο (doc.WriteTo() / doc.Save()) μετά την κλήση Flatten() — η αλλαγή υπάρχει μόνο στη μνήμη μέχρι το αρχείο να γραφτεί ξανά.

Ένα combo box εμφανίζει την τιμή εξαγωγής αντί για το κείμενο εμφάνισης. Η εμφάνιση σχεδίαζει display; η αποθηκευμένη τιμή του πεδίου (/V) είναι export — επιβεβαιώστε ότι και τα δύο έχουν οριστεί για κάθε επιλογή, όχι μόνο για μία.

Συχνές Ερωτήσεις

Μπορώ να διαβάσω την τρέχουσα τιμή ενός πεδίου μετά τη συμπλήρωση της φόρμας;

Ναι — διαβάστε την ιδιότητα Value του χειριστηρίου πεδίου, ή επαναλάβετε doc.Form.Fields για να εξετάσετε κάθε πεδίο στο έγγραφο.

Ποια είναι η διαφορά μεταξύ `Flatten()` σε ένα πεδίο και σε μια σημείωση;

Και τα δύο ενσωματώνουν διαδραστικό περιεχόμενο στο στατικό περιεχόμενο της σελίδας και το αφαιρούν από τη σχετική συλλογή — ενός πεδίου. Flatten() το αφαιρεί από /AcroForm, ενώ της σημείωσης Flatten() (που καλύπτεται στο Σημειώσεις οδηγός) το αφαιρεί από τη σελίδας /Annots.

Μπορεί ένα πλαίσιο λίστας να επιτρέπει πολλαπλές επιλογές;

Ναι — ορίστε το multiSelect: true στο αντικείμενο init του Form.AddListBox() και περάστε έναν πίνακα στο value.

Χρειάζεται ένα κουμπί push ενέργεια για να είναι χρήσιμο;

Ένα action (για παράδειγμα { type: 'submit', url, format }) είναι αυτό που κάνει το κουμπί να κάνει κάτι όταν γίνει κλικ· χωρίς αυτό εμφανίζεται αλλά δεν έχει συνδεδεμένη συμπεριφορά.