بيان عنصر التحكم المخصص

معرّف المخطط: custom-control-manifest@1 المخطط القابل للقراءة آليًا: custom-control-manifest.schema.json

الوصف المرجعي لـ عنصر تحكم مخصص (على نمط PCF، القسم 6.3): وهو وحدة Module Federation البعيدة التي يركّبها Model-Driven App Player بدلًا من محرّر حقل أصلي داخل نموذج أو عرض. ويجري التحقق من البيان بالطريقة نفسها سواء سُجِّل عبر Admin Control Center، أو أُرسل باستدعاء API مباشر، أو وُلِّد بمساعد ذكاء اصطناعي، أو جاء داخل استيراد حل — وهي قاعدة مسار التحقق الواحد (القسم 6.7).

لا يُكتب هذا البيان يدويًا. تسجيل عنصر التحكم هو رفع الحزمة التي بناها @parsware/pack، ويُؤلَّف هذا البيان من ملف parsware.json داخل ذلك الأرشيف (§28). وما يلي يصف الشكل المخزَّن، لقراءة حلٍّ مُصدَّر أو التحقق من حل ولّدته بنفسك.

الشكل

الحقل	النوع	مطلوب	ملاحظات
logicalName	string	نعم	مسبوق ببادئة الناشر، بصيغة snake_case صغيرة (مثل par_signature_pad). يُربط بحقل في نموذج عبر خاصية control الخاصة بالحقل.
displayName	string	نعم	اسم مقروء يظهر في لوحة الحقول لدى مصمم النماذج.
description	string | null	لا	وصف قصير يظهر إلى جانب عنصر التحكم.
scope	string	نعم	اسم النطاق العام لحاوية Module Federation (فريد لكل وحدة بعيدة)، يُقرأ من mf-manifest.json الخاص بالبناء لا يُنسخ يدويًا.
module	string	نعم	مسار الوحدة المعروضة التي يحمّلها الـ Player (مثل ./Control). يجب أن يبدأ بـ ./. ويُقرأ هو الآخر من البناء.
entryFileName	string	لا	ملف مدخل الحاوية داخل الحزمة (مثل remoteEntry.js). يُحسب عنوان التقديم من البيئة والاسم المنطقي وهذا الحقل — فلا عنوان يُخزَّن. فارغ في وضع الاستضافة.
packageHash	string | null	لا	بصمة SHA-256 بالنظام الست عشري الصغير لأرشيف الحزمة التي سُجِّل منها عنصر التحكم. تُفحص عند الاستيراد مقابل البايتات التي انتقلت في حزمة الحل، فيكون ما يُقدَّم هو ما صُدِّر. قيمتها null في وضع الاستضافة.
remoteEntryUrl	string | null	لا	وضع الاستضافة فقط: عنوان http(s) مطلق لملف remoteEntry.js يُقدَّم خارجيًا، لأجل إعادة التحميل الساخن أثناء الكتابة. يُرفض تسجيله ما لم تكن فئة البيئة تطويرًا، ولا ينتقل عنصر تحكم مستضاف داخل حزمة حل — فشيفرته ليست من شأن المنصة أن تحملها.
substitutesFor	string[]	نعم	أنواع عناصر التحكم للحقول التي يمكن ربط عنصر التحكم هذا بها: واحد أو أكثر من Text، MultilineText، Number، Boolean، DateTime، Lookup، File، Image، Custom. يجب أن تحتوي على مدخلة واحدة على الأقل. ولا تعرض لوحة الحقول عنصر التحكم إلا حيث يطابق نوع عنصر تحكم الحقل. وهذه هي عائلات نوع البيانات التي ينتمي إليها الحقل — وليست أسماء عناصر التحكم المدمجة التي يختارها موضع الحقل في النموذج (TextArea، Toggle، Dropdown، …)، فتلك مفردات أخرى لا تشترك معها إلا في أربعة أسماء.

ما لم يعد موجودًا فيه

حُذف requestedScopes وdeclaredEntities، وadditionalProperties مضبوط على false، فالبيان الذي ما زال يحمل أيًّا منهما يُرفض بدل أن يُتجاهل بصمت. يعمل عنصر التحكم بصلاحيات الشخص الذي يستخدمه (§24): فمجموعة النطاقات المطلوبة كانت تُقاطع دائمًا مع جلسة المستخدم نفسه، أي أنها تضيّق على مستخدم عنصر التحكم ولا توسّع له أبدًا، أما قائمة الجداول المعلنة فلم يكن يقرأها أي مسار شيفرة. حذفهما يجعل قصة الأمان جملة واحدة بدل مقبضين.

وذهب معهما remoteEntryUrl المطلوب. صارت الحزمة تنتقل وتُقدَّم من عنوان المنصة نفسها، فيُحسب العنوان بدل أن يُخزَّن (§28).

عقد عنصر التحكم

الوحدة المعروضة (./Control) هي مكوّن React واحد ينفّذ العقد الثابت ParswareControlProps المأخوذ من @parsware/runtime-sdk:

interface ParswareControlProps {
  value: unknown;                     // the bound field's current value
  onChange: (next: unknown) => void;  // commit a new value back to the form
  fieldMetadata: FieldMetadata;       // the bound field's type/label/constraints
  context: RuntimeContext;            // the same auth/data/logging context apps get
}

يزوّد الـ Player عنصر التحكم بهذه الخصائص وقت العرض. ولا يصل عنصر التحكم إلى المنصة إلا عبر context (وهو ParswareRuntime) — لا عبر استدعاء مباشر للبوابة أو لخدمة الهوية.

أين يجري التحقق منه

• التسجيل — تتحقق طبقة التطبيق من البيان مقابل custom-control-manifest@1 وتفرض أن يبدأ logicalName ببادئة الناشر المالك قبل تسجيل عنصر التحكم في بيئة.
• استيراد الحل — يُعاد التحقق من كل بيان مضمَّن في حزمة الحل مقابل المخطط نفسه قبل تسجيل عنصر التحكم في البيئة الهدف.

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

يعمل عنصر التحكم المخصص في مجال JavaScript نفسه الذي يعمل فيه الـ Shell (عبر Module Federation، لا داخل iframe — القسم 6.3)، ولذلك يُفرض حدّ الثقة في مكان آخر:

• عنصر التحكم المحزَّم يُقدَّم من عنوان المنصة نفسها، فلا أصل خارجي لإدراجه في قائمة السماح. ولا تزال قائمة سماح الـ CSP تحكم وضع الاستضافة، وهو الشكل الوحيد الذي يمكن للمصمم أن يوجّه حزمته إلى أي مكان — وهو مرفوض خارج بيئة التطوير.
• يُفحص الأرشيف قبل تخزينه: الحجم، وعدد الملفات، والحجم الذي يتمدد إليه، وألا يسمّي أي مدخل مسارًا خارج مجلده، وأن يكون كل ملف من نوع تقدّمه المنصة.
• لا يمكن تحميل عنصر التحكم إلا إذا نشره حل داخل تلك البيئة، وتُفحص بصمة الحزمة عند الاستيراد ومرة أخرى قبل فكّها إلى القرص.
• كل استدعاء بيانات يجريه عبر Runtime SDK يُصرَّح به على الخادم مقابل رمز سياق التطبيق الذي يحمل نطاقات المستخدم نفسه. يستطيع عنصر التحكم أن يفعل بالضبط ما يستطيعه من يستخدمه، ولا يوجد حقل في هذا البيان يغيّر ذلك.

ذات صلة

• بيان حزمة الأداة — ملف parsware.json داخل الأرشيف الذي يُؤلَّف منه هذا البيان.
• بيان التطبيق المخصص — نظيره الخاص بتطبيق React المخصص، الذي لم يعتمد التحزيم بعد.
• تعريف النموذج المبني على البيانات — تشير خاصية control لحقل في نموذج إلى عنصر تحكم عبر logicalName الخاص به.