Forms

Forms

تغطي هذه الصفحة إنشاء وإدارة الحقول التفاعلية AcroForm. Form، التي يتم الوصول إليها عبر doc.Form، هي الواجهة لكل نوع من أنواع الحقول؛ كل طريقة Add*() تنشئ حقلاً مرتبطًا بصفحة ومستطيل ودجت وتعيد مقبضًا مكتوبًا (TextField، CheckboxField، ChoiceField، ButtonField أو RadioField) يشارك الخصائص العامة Field وهي Value، ReadOnly، وRequired.

إنشاء الحقول

Form.AddTextField()، Form.AddCheckbox()، Form.AddComboBox()، وإخوتهم كل منهم يأخذ كائن خيارات يحدد page المستهدف (بدءًا من الصفر)، وrect الودجت، وname الحقل، وتنسيقًا مثل borderColor وbackgroundColor.

const form = doc.Form;
const pageNum = page.Number;

form.AddTextField({
  page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
  borderColor: [0.05, 0.1, 0.3], backgroundColor: [0.9, 0.93, 1], borderWidth: 1,
  font: 'Helvetica', fontSize: 12,
});

form.AddCheckbox({
  page: pageNum, rect: [200, 630, 218, 648], name: 'Subscribe',
  checked: true, borderColor: [0.05, 0.1, 0.3], borderWidth: 1,
});

form.AddComboBox({
  page: pageNum, rect: [200, 550, 350, 570], name: 'Country', value: 'US',
  options: [
    { export: 'US', display: 'United States' },
    { export: 'UK', display: 'United Kingdom' },
    { export: 'DE', display: 'Germany' },
  ],
});

يقوم Page.AddTextField() وPage.AddCheckbox() بإنشاء نفس أنواع الحقول مباشرةً على صفحة، دون تسمية doc.Form أو رقم page في كائن الخيارات.

قراءة وتعديل الحقول

Form.Fields هو مصفوفة تحتوي على كل Field في المستند؛ Form.Get() يبحث عن واحد باستخدام اسمه المؤهل بالكامل. يمكن قراءة أو إعادة تعيين Value لكل حقل، وReadOnly / Required هي خصائص منطقية بسيطة.

const nameField = doc.Form.Get('FullName');
if (nameField) {
  console.log(nameField.Value);
  nameField.Value = 'Bob Sample';
}

تسوية الحقول

كل طريقة Flatten() لنوع الحقل تُدمج مظهره الحالي في المحتوى الثابت للصفحة وتزيله من AcroForm — وهو نفس التأثير الدائم غير التفاعلي الذي يوفّره Annotation.Flatten() للتعليقات التوضيحية.

const tb = form.AddTextField({
  page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten();

نصائح وأفضل الممارسات

• قم بتعديل مقبض الحقل الذي يُرجع مباشرةً من استدعاء Add*()، أو المقابض التي تم البحث عنها حديثًا باستخدام Form.Get() — المرجع القديم لا يرى التغييرات التي أُجريت في أماكن أخرى.
• Form.RemoveField() تقبل إما مقبض Field أو سلسلة اسم الحقل.
• استدعِ Form.GenerateAppearances() بعد تغيير قيم الحقول دفعة واحدة بحيث يبقى مظهر كل حقل على الشاشة متزامنًا مع Value الخاص به.
• تخزن صناديق القوائم المنسدلة وصناديق القوائم قيمة export المختارة في /V؛ نص display هو ما يظهر في المظهر المُولد.

مشكلات شائعة

FAQ

كيف يمكنني قراءة أو تغيير قيمة حقل بعد إنشائه؟

ابحث عنه باستخدام Form.Get('fieldName') (أو استخدم المعرف الذي أرجعته استدعاء Add*()) واقرأ أو عيّن الخاصية Value مباشرةً.

ما أنواع الحقول التي تدعمها واجهة النموذج؟

حقول النص، ومربعات الاختيار، ومجموعات الراديو، وصناديق الجمع، وصناديق القائمة، وأزرار الدفع، عبر Form.AddTextField()، Form.AddCheckbox()، Form.AddRadioGroup()، Form.AddComboBox()، Form.AddListBox()، وForm.AddPushButton().

كيف يمكنني حذف حقل؟

استدعِ Form.RemoveField() إما بمعرف الحقل أو باسمه.

كيف يتم جعل حقل النموذج دائمًا وغير قابل للتعديل؟

استدعِ Flatten() على مقبض الحقل — النمط نفسه المستخدم للتعليقات التوضيحية — الذي يُدمج مظهره الحالي في الصفحة ويزيله من AcroForm.

API Reference ملخص

انظر أيضاً

• Aspose.PDF — Enterprise Documentation