כיצד לעבוד עם שדות 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: הוסף קבוצת רדיו, תיבת משולבת ותיבת רשימה

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: הוסף כפתור לחיצה

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()’s options המערך חייב לשתף את היחיד של הקבוצה name — ערבוב שמות השדות יוצר תיבות סימון נפרדות במקום קבוצת רדיו.

ערך של שדה משטח אינו מופיע בקובץ השמור. שמור את המסמך (doc.WriteTo() / doc.Save()) לאחר קריאה ל Flatten() — השינוי קיים רק בזיכרון עד שהקובץ נכתב חזרה.

תיבת משולבת מציגה את ערך הייצוא במקום את טקסט התצוגה. המראה מצייר display; הערך השמור של השדה (/V) הוא export — אשרו ששניהם מוגדרים לכל אפשרות, לא רק לאחת.

שאלות נפוצות

האם אני יכול לקרוא את הערך הנוכחי של שדה לאחר שהטופס מולא?

כן — קרא את המאפיין Value של מטפל השדה, או חזור על doc.Form.Fields כדי לבדוק כל שדה במסמך.

מה ההבדל בין `Flatten()` על שדה ועל אנוטציה?

שניים מעבדים תוכן אינטראקטיבי לתוך תוכן דף סטטי ומסירים אותו מהאוסף המתאים שלו — של שדה’s Flatten() מסיר אותו מ /AcroForm, בעוד שלהערה Flatten() (מתואר ב הערות מדריך) מסיר אותו מהדף של /Annots.

האם תיבת רשימה יכולה לאפשר בחירות מרובות?

כן — הגדר multiSelect: true על האובייקט init של Form.AddListBox() והעבר מערך ל-value.

האם push button צריך פעולה כדי להיות שימושי?

action (למשל { type: 'submit', url, format }) הוא מה שגורם לכפתור לבצע פעולה כאשר נלחץ; ללא אחד הוא מוצג אך אין לו התנהגות מחוברת.