تعبئة نموذج PDF باستخدام NextPDF Connect (Pro)

لمحة سريعة

املأ حقول نماذج ⁨PDF⁩ التفاعلية عبر ⁨NextPDF Connect⁩ باستخدام ⁨XML Forms Data Format⁩ (⁨XFDF⁩). أداة التوقيع والنماذج هي fill_form. يسجّل مزوّد أدوات ⁨Pro⁩ الأداة new FillFormTool()، واسمها في البروتوكول هو fill_form. fill_form أداة من فئة ⁨Pro.⁩ عند بدء التشغيل، يتحقّق الخادم من وجود حزمة ⁨Pro⁩ عبر class_exists() ولا يسجّل الأداة إلا عند توافر الحزمة. مع ⁨Core⁩ وحده، لا تظهر fill_form في السجلّ.

التثبيت

composer require nextpdf/server
composer require nextpdf/pro

اربط وسيلة نقل، ثم تأكّد من وجود الأداة عبر diagnostic.capabilities (راجع تشخيص البيئة). لا تفترض مجموعة أدوات ثابتة.

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

يربط ⁨XFDF⁩ أسماء الحقول بقيمها عبر عناصر <field>. يجب أن يطابق كل اسم حقل حقلًا من حقول ⁨AcroForm⁩ الموجودة مسبقًا في المستند الهدف. يحتوي قاموس حقول النموذج التفاعلي على كل حقل (⁨ISO 32000-2⁩ §12.7)، وتصبح القيمة المُمرَّرة قيمة الحقل (⁨ISO 32000-2⁩ §12.7). إذا لم يطابق اسمٌ أيّ حقل، فإن الأداة تتخطّاه بدلًا من معاملته كخطأ. وتُبلّغ الأداة عن عدد الحقول التي عبّأتها وعدد الحقول التي تخطّتها.

واجهة ⁨API⁩

الأداة	الفئة	الدور	فئة المخاطر
create_pdf	⁨Core⁩	فتح الجلسة	آمن
fill_form	⁨Pro⁩	تطبيق قيم ⁨XFDF⁩ على حقول ⁨AcroForm⁩	تنبيه
output_pdf	⁨Core⁩	تصيير ⁨PDF⁩ وإرجاعه	موافقة مطلوبة / مراجعة (⁨base64⁩)

أسماء الأدوات هي أسماء البروتوكول في السجلّ. كتالوج الأدوات هو الكتالوج المرجعي. تحدّد الفئة المثبَّتة الأدوات المتاحة، ولا تظهر أدوات ⁨Pro⁩ إلا عند تثبيت حزمة ⁨Pro.⁩

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

1. create_pdf (أو حمّل قالبًا يحتوي مسبقًا على حقول نموذج).
2. fill_form مع xfdf_data الذي يربط أسماء الحقول بقيمها.
3. output_pdf → ⁨base64.⁩

تعرض النتيجة fields_filled، وfields_skipped، وأسماء الحقول المطابِقة.

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

استخدم قالبًا يحتوي على أسماء حقول ⁨AcroForm⁩ تتحكم بها. تحقّق من ⁨XFDF⁩ وفق مخطّط ⁨XFDF⁩ قبل إرساله. افحص fields_skipped وقائمة الأسماء المُعادة لاكتشاف حالات عدم تطابق الأسماء (الأسماء حسّاسة لحالة الأحرف). في عمليات التعبئة الكبيرة، التزم بحدّ حجم ⁨XFDF⁩، وقسّم البيانات عند الحاجة.

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

• ⁨XFDF⁩ مشوَّه. يحدّد خطأ التحليل الموضع المسبّب للمشكلة. هرّب كيانات ⁨XML⁩ وأدرِج xmlns.
• عدم تطابق الاسم. يُتخطّى الحقل غير المطابِق بصمت، ويزداد fields_skipped. الأسماء حسّاسة لحالة الأحرف.
• لا توجد حقول نموذج. ينتج عن مستند بلا ⁨AcroForm⁩ صفر حقول معبّأة.
• ⁨XFDF⁩ كبير جدًا. يرفض الخادم البيانات التي تتجاوز حدّ الحجم. قسّمه أو قلّل المسافات البيضاء.
• غياب ⁨Pro.⁩ مع ⁨Core⁩ وحده، لا تُسجَّل fill_form، ويؤدي استدعاؤها إلى خطأ أداة غير معروفة. تحقّق عبر diagnostic.capabilities أولًا.

الأداء

التعبئة سريعة مقارنةً بالتصيير. يتراوح المُخرَج من بضعة ⁨KB⁩ إلى عشرات ⁨KB⁩، تبعًا لعدد الحقول وما إذا كانت الخطوط مضمّنة. السمة هي structural.

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

تصبح قيم الحقول جزءًا من محتوى المستند. لا تضع أسرارًا في حقول النموذج إذا كنت ستُعيد ⁨PDF⁩ بعد ذلك عبر قناة غير موثوقة. ليس لمسار ⁨base64⁩ أي أثر جانبي على نظام الملفات. يخضع إخراج الملفات لبوّابة تحكّم.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
يُحفظ حقل النموذج في قاموس حقول النموذج التفاعلي.	⁨ISO 32000-2⁩	§12.7
تصبح البيانات المُمرَّرة قيمة الحقل.	⁨ISO 32000-2⁩	§12.7

السياق التجاري

fill_form أداة من فئة ⁨Pro.⁩ لا يسجّلها الخادم إلا عند توافر حزمة ⁨Pro⁩ عند بدء التشغيل (عبر فحص class_exists()). لا تتيحها عمليات نشر ⁨Core.⁩

توافر وسائل النقل

وسيلة النقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم (⁨Pro⁩)	لا تتوفر إلا عند تثبيت ⁨Pro.⁩
⁨REST⁩	نعم (⁨Pro⁩)	مماثل.
⁨gRPC⁩	نعم (⁨Pro⁩)	مماثل.

فئة مخاطر ⁨HITL⁩

تُصنَّف fill_form ضمن فئة تنبيه لأنها تعديل محتوى قابل للعكس. وتُصنَّف output_pdf ضمن موافقة مطلوبة، وتُخفَّض إلى مراجعة في وضع ⁨base64⁩ (فئات مخاطر ⁨HITL⁩).

غلاف ⁨JSON⁩ لبوّابة التأكيد

إخراج ⁨Base64⁩:

{ "allowed": true }

يعيد إخراج الملفات غلاف التحدّي الموصوف في موافقة الإخراج.

انظر أيضًا

• استخراج المحتوى النصّي
• فحص إمكانية الوصول
• كتالوج الأدوات