كيفية العمل مع حقول 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.

هل يحتاج زر الدفع إلى إجراء ليكون مفيدًا؟

إن action (على سبيل المثال { type: 'submit', url, format }) هو ما يجعل الزر يقوم بشيء عند النقر؛ بدونه يُظهر الزر لكنه لا يملك أي سلوك مبرمج.