تسجيل عنصر تحكم مخصص

الهدف

تثبيت عنصر تحكم مخصص في بيئة عبر رفع حزمته، حتى يمكن تركيبه على حقل في نموذج مدفوع بالنموذج.

هل تبحث عن كيفية بناء عنصر التحكم بدل تثبيته؟ تفترض هذه الصفحة أن عنصر التحكم موجود سلفًا وأنه حُزم. أما كتابته — عقد الخصائص الثابت، وأنواع الحقول التي يحل محلها، وحالات القيمة التي عليه معالجتها، والاختبار والتحزيم — ففي بناء عنصر تحكم مخصص.

المتطلبات المسبقة

• أنت مسجَّل الدخول إلى مركز التحكم الإداري بصفتك مسؤول منصة.
• يوجد ناشر وحلّ يملكه ذلك الناشر.
• البيئة التي تثبّت فيها عنصر التحكم نشطة.
• لديك حزمة عنصر التحكم — ملف .zip الناتج عن تشغيل npm run pack في مشروع عنصر التحكم نفسه. يُكتب عادةً في مجلد package/ داخل ذلك المشروع ويحمل اسم عنصر التحكم، مثل par_signature_pad-1.2.3.zip.

الخطوات

1. اختر البيئة التي يجب تثبيت عنصر التحكم فيها من محدِّد الشريط العلوي.
2. افتح الحلول، ثم افتح الحل الذي ينتمي إليه عنصر التحكم.
3. اختر عناصر التحكم المخصصة في تنقّل الحل (أو بطاقة عناصر التحكم المخصصة في نظرة الحل العامة). تعرض الصفحة عناصر التحكم التي ثبّتها هذا الحل في البيئة المختارة.
4. اختر جديد. تُفتح لوحة على جانب الشاشة.
5. اختر ملف حزمة عنصر التحكم.
6. اختر تسجيل عنصر تحكم مخصص. يظهر عنصر التحكم في قائمة ذلك الحل وتلك البيئة، وفي نظرة الحل العامة تحت عناصر التحكم المخصصة، وفي لوحة حقول مصمم النماذج.

هذا هو النموذج كله. لا شيء آخر لتعبئته، لأن الحزمة تقول كل ذلك أصلًا: الاسم المنطقي والاسم المعروض، ونطاق Module Federation والوحدة المكشوفة اللذان استخدمهما البناء فعليًا، وملف المدخل الذي يُخدم، وأنواع الحقول التي يمكن لعنصر التحكم أن يحل محلها. كان الأولان يُنسخان يدويًا من إعدادات المُجمِّع، وكان الخطأ في أيٍّ منهما يُنتج عرضًا واحدًا — لا يُحمَّل عنصر التحكم — دون ما يدل على أيهما كان خاطئًا.

الرفع مرة أخرى يستبدل البناء المثبَّت. هذه هي الدورة المعتادة أثناء العمل على عنصر تحكم: عدّله، ثم شغّل npm run pack، ثم ارفعه من جديد. لا حاجة لإزالة التسجيل القديم أولًا. يبيّن عمود الإصدار أي بناء مثبَّت، فتتحقق من أن ما يعمل هو ما حزمته آخر مرة.

لإزالة عنصر تحكم، حدّد صفّه واختر إزالة. يزيله ذلك من البيئة ويحذف حزمته المخزّنة؛ ويبقى مرجع المكوّن في الحل، لأن بيئات أخرى قد تكون ما زالت تثبّت عنصر التحكم.

أين تعيش شيفرة عنصر التحكم

تخزّن المنصة بايتات الحزمة وتخدمها من عنوان المنصة نفسها. لا شيء يُجلب من مضيف خارجي، وبالتالي:

• الحل مكتفٍ بذاته — تصديره يحمل شيفرة عنصر التحكم معه، واستيراده إلى بيئة اختبار أو إنتاج يثبّت عنصر تحكم يعمل، لا مؤشرًا إلى حيث بُني؛
• لا يوجد عنوان لإدراجه في قائمة السماح، ولا عنوان يتقادم.

شيفرة عنصر التحكم لا تحتاج إلى رفعها بوصفها موارد وِب. موارد الوِب مخصصة لملفات مستقلة تكتبها وتشير إليها بالاسم — صفحة أنماط، صورة، سكربت — لا لمخرجات بناء عنصر تحكم.

ما الذي يجري خلف الكواليس

يُفحص الأرشيف قبل تخزين أي شيء: حجمه، وعدد الملفات التي يحملها، والحجم الذي يتمدد إليه، وألا يسمّي أي ملف بداخله مسارًا خارج مجلده، وأن يكون كل ملف من نوع تخدمه المنصة، وأن يطابق بيانه المخطط المنشور للحزمة. ثم يُفحص الاسم المنطقي لعنصر التحكم مقابل بادئة الناشر المالك.

تُخزَّن الحزمة كاملة، وتُفك أول مرة يُطلب فيها عنصر التحكم فعليًا. لهذا يظل عنصر التحكم يعمل بعد إعادة تشغيل المنصة، ويعمل بالطريقة نفسها على كل خادم: الحزمة المخزّنة هي النسخة الحقيقية، والملفات المفكوكة ليست إلا ذاكرة مؤقتة تعيد بناء نفسها.

تثبيت عنصر التحكم في بيئة لا يثبّته في أي بيئة أخرى؛ إنما ينتقل عند تصدير حلّه واستيراده.

استكشاف الأخطاء

• «لا تحتوي الحزمة على 'parsware.json' في جذرها.» — الملف المرفوع مخرجات بناء عادية لا حزمة. ابنِها بـ npm run pack في مشروع عنصر التحكم.
• «يجب أن يبدأ عنصر التحكم المخصص … ببادئة الناشر …_.» — قيمة logicalName في package.json لعنصر التحكم لا تبدأ ببادئة الناشر المالك. غيّرها هناك ثم أعد التحزيم.
• «تحمل الحزمة … ملفًا؛ الحد الأقصى …» — يكاد يكون دائمًا مجلد node_modules وجد طريقه إلى الأرشيف. احزم مخرجات البناء لا المشروع.
• «عنصر التحكم المخصص … مثبَّت في هذه البيئة من حلٍّ آخر.» — الاسم المنطقي مأخوذ. غيّر اسم عنصر التحكم أو أزل التسجيل الآخر.
• «البيئة … ليست نشطة.» — انتظر حتى تنتهي تهيئة البيئة، أو اختر بيئة أخرى.

أثناء كتابة عنصر التحكم

رفع حزمة مع كل تغيير حلقة بطيئة. في بيئة تطوير يعرض جديد خيارًا ثانيًا هو استخدام خادم تطوير قيد التشغيل: اكتب العنوان الذي يطبعه npm run dev واختر تسجيل عنصر تحكم مخصص. يُقرأ اسم عنصر التحكم وإعدادات federation الخاصة به من خادم التطوير، وتحمّل النماذج عنصر التحكم منه، فيظهر أي تغيير تحفظه في المرة التالية التي يُفتح فيها نموذج. ويعرض عمود الإصدار عبارة مستضاف (تطوير) ما دام مسجلًا بهذه الطريقة.

• إذا كان عنصر التحكم مثبتًا من قبل فأزله أولًا. يُسجَّل خادم التطوير باسم عنصر التحكم المنطقي نفسه، فيبقى النموذج الذي ربطته به يستخدمه.
• عندما تنتهي ارفع الحزمة. فهي تحل محل تسجيل خادم التطوير، ويعود عمود الإصدار إلى عرض البناء.

لا يظهر هذا الخيار خارج بيئة التطوير: عنصر التحكم المسجل بهذه الطريقة ليست له حزمة، فلن ينتقل كوده مع الحل. أما إعداد مشروع عنصر التحكم لذلك فتجده في بناء عنصر تحكم مخصص.

سيناريوهات ذات صلة

• بناء عنصر تحكم مخصص.
• ربط عنصر تحكم مخصص بحقل.
• تسجيل تطبيق React مخصص.
• إنشاء حل.