FormHandle الخاصية

تكشف الخاصية FormHandle مقبض PDFium الخام FPDF_FORMHANDLE المُنشأ عبر FPDFDOC_InitFormFillEnvironment للمستند المحمَّل حاليًا. وهذا المقبض بوابة طبقة النماذج التفاعلية في PDFium: فهو المعامل الذي تتوقعه كل دالة FORM_* و FPDF_FFL*، وهو يحكم عرض حقول النماذج وتوصيل أحداث الفأرة / لوحة المفاتيح وتتبع التركيز و callbacks الـ JavaScript / XFA (الملف fpdf_formfill.h في PDFium).

يُنشأ المقبض عندما تصبح Active تساوي True ويُدمر عندما تعود Active إلى False أو يُحرَّر المكوّن. تعامل معه بوصفه معتمًا قصير العمر — فلا تخزن القيمة عبر دورة تحميل/تفريغ واحدة، ولا تستدعِ أبدًا FPDFDOC_ExitFormFillEnvironment عليه بنفسك؛ فالمكوّن يملك دورة حياته.

خاصية FormHandle متقدمة ومفيدة لتوجيه أحداث النماذج منخفضة المستوى (توصيل مخصص للفأرة / لوحة المفاتيح، أو تركيز حقول برمجي، أو إعادة توليد مظهر برمجي، أو تحديث XFA) عندما لا تكون خصائص FormField / FormFieldAt عالية المستوى دقيقة بما يكفي. ولعرض النماذج يوصّل TPdfView من VCL هذا المقبض بالفعل إلى حلقة الرسم لديها؛ ولا يلزم الاستخدام اليدوي إلا عند تجاوز العارض المزود أو تنفيذ مسار أحداث بديل.

• تُرجع nil عندما لا يكون أي مستند محمَّلًا. تحقق دائمًا قبل استدعاء واجهات تعبئة النماذج في PDFium.
• حالة تعبئة النماذج في PDFium ليست آمنة الخيوط — فاستخدم المقبض فقط من الخيط الذي حمّل المستند.
• عندما يُبنى PDFium دون محرك JavaScript‏ v8، يظل FormHandle عاملاً لعرض الحقول الساكنة والتفاعل الأساسي لكن تظل إجراءات JavaScript على مستوى المستند خاملة.