النماذج: حقول AcroForm التفاعلية والتسطيح

لمحة سريعة

تنشئ وحدة النماذج نماذج تفاعلية لمستندات ⁨PDF⁩. فهي تبني حقول النص ومربعات الاختيار وأزرار الاختيار والقوائم (قائمة/قائمة منسدلة) والأزرار وحقول التوقيع، وتنظمها في تسلسل هرمي ⁨parent/child⁩، وتكتبها ككائنات ⁨PDF⁩ مع تدفقات المظهر، كما يمكنها تسطيح النموذج ليصبح محتوى صفحة ثابتاً.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

نموذج ⁨PDF⁩ التفاعلي هو ⁨AcroForm⁩: تسلسل هرمي للحقول على مستوى المستند، ترتبط فيه الحقول الطرفية بتعليقات الأدوات التوضيحية (⁨widget⁩) على الصفحات. يعرّف ⁨ISO 32000-2⁩ §12.7 هذا النموذج وقواميس حقوله وجذر ⁨AcroForm⁩ والتسلسل الهرمي للحقول. تشفّر هذه الوحدة تلك البنى للمحرّك.

FormFieldManager هو الواجهة الأساسية. يوفّر بُناة textField() وcheckBox() وradioButton() وbutton() وsignatureField()، ويتتبّع الحقول، ويسلسلها باستخدام writeFields(). يصدر تدفق مظهر ⁨Form XObject⁩ واحداً لكل أداة توضيحية (/Subtype /Form، /BBox)، كما يتطلب §8.10. FormField هو كائن قيمة الحقل. يحوّل FormFieldDictionaryBuilder الحقل إلى قاموس ⁨PDF⁩ الخاص به، ويطبّق المدخلات وبتات الأعلام الخاصة بكل نوع من حقول النص ومربعات الاختيار والقوائم والأزرار. المدير وFormField هما @since 1.0.0. باني القاموس هو @since 1.1.0.

FormFieldHierarchy ينشئ شجرة الحقول ⁨parent/child⁩ باستخدام addChild() وgetRootFieldNames() وgetChildren() وgetParent()، إلى جانب زائر walkDepthFirst(). اسم الحقل المؤهّل بالكامل هو المسار المنقوط عبر هذا التسلسل الهرمي، بما يطابق نموذج الحقول المتداخلة في §12.7.

FormFlattener يصيّر النموذج إلى محتوى صفحة ثابت. يُرجع flatten() كائن FlattenResult، وبذلك يمكنك تجميد نموذج معبّأ لأغراض الأرشفة. FieldMDP وFieldMdpAction يصوغان تحويل قفل الحقول. يستطيع المستند الموقَّع قفل مجموعة مسمّاة من الحقول ضد أي تعديل لاحق. FieldMdpAction يحدّد نطاق القفل، ويشير requiresFieldList() إلى الحالات التي تكون فيها قائمة الحقول الصريحة إلزامية. FieldMDP هو @since 2.0.0.

واجهة ⁨API⁩

الصنف	الأعضاء الرئيسيون	الدور
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	باني الحقول والمسلسِل (@since 1.0.0)
FormField	كائن قيمة الحقل	حقل ⁨AcroForm⁩ واحد (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	باني قاموس الحقل (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	شجرة حقول ⁨parent/child⁩ (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	يسطّح النموذج إلى محتوى ثابت (@since 1.0.0)
FieldMDP	toTransformParams()	تحويل قفل الحقول (⁨FieldMDP⁩) (@since 2.0.0)
FieldMdpAction (تعداد)	requiresFieldList()	نطاق قفل الحقول (@since 2.0.0)

شغّل composer docs:generate-api-php -- --module=Form لإنشاء جدول ⁨PHPDoc⁩ الكامل.

مثال برمجي — بداية سريعة

المصدر: examples/30-form-fields.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();

$form->textField(name: 'applicant_name', x: 50, y: 700, w: 200, h: 18);
$form->checkBox(name: 'agree_terms', x: 50, y: 660, size: 12);
$form->radioButton(name: 'plan', x: 50, y: 620, size: 12 /* + option set */);

// The Writer invokes $form->writeFields(...) during document serialization.

مثال برمجي — بيئة الإنتاج

ابنِ مجموعة حقول لمستند موقَّع، ثم اقفل الحقول الموقَّعة باستخدام ⁨FieldMDP.⁩

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FieldMDP;
use NextPDF\Form\FieldMdpAction;
use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();
$form->textField(name: 'contract_value', x: 50, y: 700, w: 160, h: 18);
$form->signatureField(name: 'approver_sig', x: 50, y: 600, w: 200, h: 60);

// Lock only the named fields after signing.
$lock = new FieldMDP(
    action: FieldMdpAction::Include,
    fields: ['contract_value'],
);

$transformParams = $lock->toTransformParams();
// $transformParams is attached to the signature's transform method by the signing layer.

الحالات الحدّية والمزالق

• اسم الحقل هو مسار منقوط مؤهّل بالكامل عبر FormFieldHierarchy. في العارض، يُعدّ الحقلان الطرفيان اللذان يحملان الاسم المؤهّل بالكامل نفسه حقلاً منطقياً واحداً. أنت المسؤول عن ضمان التفرّد.
• يخبرك FieldMdpAction::requiresFieldList() متى تكون قائمة الحقول إلزامية. إجراء Include/Exclude دون القائمة المطلوبة يُنشئ قفلاً غير سليم؛ تحقّق من العَلَم.
• FormFlattener::flatten() يزيل التفاعلية عمداً. النتيجة محتوى ثابت. احتفظ بالمصدر التفاعلي إن كنت ستحتاج إليه لاحقاً.
• تُصدَر تدفقات المظهر لكل أداة توضيحية. قد يُعرَض الحقل الذي لا يملك مظهراً بشكل غير متّسق عبر العارضات؛ دع المدير ينشئ المظهر بدلاً من حذفه.
• signatureField() يُنشئ العنصر النائب للحقل فقط. تنتج طبقة الأمان/التوقيع التوقيع الفعلي؛ وهذه الوحدة لا تفعل ذلك.

الأداء

يتم إنشاء الحقول وتسلسلها بتعقيد ⁨O⁩(⁨n⁩) بالنسبة إلى عدد الحقول، مع تدفق مظهر ⁨Form XObject⁩ واحد لكل أداة توضيحية. تتناسب تكلفة التسطيح مع المحتوى المصيَّر، لا مع عدد الحقول. يظل حِمل العمل المرجعي الافتراضي ضمن ميزانية 1500 ⁨ms⁩ للزمن الكلي / 64 ⁨MB⁩ للذروة. ملف إعادة الإنتاج هو structural: تتباين أرقام الكائنات و/ID في المقطورة بين التشغيلات. يكون المستندان اللذان يحملان النموذج نفسه متساويين بنيوياً، لكنهما غير متطابقين بايتياً.

ملاحظات الأمان

قيم حقول النموذج هي مدخلات مستخدم. تهرّب الوحدة القيم النصية لتسلسل ⁨PDF⁩ باستخدام PdfStringEscaper، بحيث لا يمكن لقيمة الحقل أن تخرج من سلسلة ⁨PDF⁩ الخاصة بها وتحقن بنية. عندما يكون النموذج مشفّراً، يغطّي تشفير ⁨AES-256⁩ للمستند محتوى الحقول. FieldMDP ضابط أمان: فهو يقفل الحقول المسمّاة ضد أي تعديل بعد التوقيع. قفل الحقول الذي لا يطابق مجموعة الحقول الموقَّعة يقوّض ذلك الضابط؛ اضبط نطاق القفل بتروٍّ. تعامل مع أي قيمة مستخرجة من نموذج معبّأ على أنها مدخلات غير موثوقة. راجع نموذج أمان المحرّك في /modules/core/security/.

المطابقة

تتبع بنى النموذج التي تصدرها هذه الوحدة نموذج النماذج التفاعلية في ⁨ISO 32000-2⁩ §12.7: جذر ⁨AcroForm⁩ وقواميس الحقول والتسلسل الهرمي لحقول المستند. تُصدَر المظاهر الخاصة بكل أداة توضيحية ككائنات ⁨Form XObject⁩ وفق §8.10 وتُوثَّق ضمنياً في src/Form/. يمارس tests/Unit/Form/ حقائق التنفيذ هذه. وهي ليست بياناً بالمطابقة الشاملة لتنسيق ⁨PDF 2.0⁩ من طرف إلى طرف. تُتحقَّق المطابقة الكاملة للمستند عبر مجموعات الأوراكل والمجموعات الذهبية في /modules/core/conformance/.

انظر أيضاً

• وحدة التنقل — تعليقات الأدوات التوضيحية التي تقترن بالحقول.
• وحدة الأمان — نموذج الثقة للتوقيع و⁨FieldMDP.⁩
• وحدة إمكانية الوصول — وسم حقول النموذج لأجل ⁨PDF/UA.⁩
• نظرة عامة على المطابقة