ثبت یک کنترل سفارشی
هدف
نصب یک کنترل سفارشی در یک محیط با بارگذاری بستهٔ آن، تا بتوان آن را روی فیلد یک فرم Model-Driven سوار کرد.
دنبال روش ساختن کنترل هستید و نه نصب آن؟ این صفحه فرض می‌گیرد که کنترل از قبل وجود دارد و بسته‌بندی شده است. نوشتن کنترل — قرارداد ثابت propها، اینکه جایگزین چه نوع فیلدهایی می‌شود، حالت‌های مقداری که باید مدیریت کند، آزمون و بسته‌بندی — در ساخت یک کنترل سفارشی آمده است.
پیش‌نیازها
- با نقش مدیر پلتفرم وارد مرکز کنترل مدیریت شده‌اید.
- یک ناشر و یک راهکار متعلق به آن ناشر از قبل وجود دارد.
- محیطی که کنترل را در آن نصب می‌کنید فعال است.
- بستهٔ کنترل را در اختیار دارید — فایل
.zipکه با اجرایnpm run packدر پروژهٔ خودِ کنترل ساخته می‌شود. معمولاً در پوشهٔpackage/همان پروژه نوشته می‌شود و نامش از روی کنترل گرفته می‌شود، مثلاًpar_signature_pad-1.2.3.zip.
گام‌ها
- از انتخابگر نوار بالا، محیطی را که کنترل باید در آن نصب شود انتخاب کنید.
- راهکارها را باز کنید و سپس راهکاری را که کنترل به آن تعلق دارد باز کنید.
- در ناوبری راهکار کنترل‌های سفارشی را انتخاب کنید (یا کارت کنترل‌های سفارشی را در نمای کلی راهکار). این صفحه کنترل‌هایی را نشان می‌دهد که این راهکار پیش‌تر در محیط انتخاب‌شده نصب کرده است.
- جدید را انتخاب کنید. پنلی در کنار صفحه باز می‌شود.
- فایل بستهٔ کنترل را انتخاب کنید.
- ثبت کنترل سفارشی را انتخاب کنید. کنترل در فهرست آن راهکار و محیط، در نمای کلی راهکار زیر کنترل‌های سفارشی، و در پالت فیلدهای طراح فرم ظاهر می‌شود.
فرم همین است و بس. چیز دیگری برای پر کردن نیست، چون بسته همهٔ آن را از پیش می‌داند: نام منطقی و نام نمایشی کنترل، اسکوپ Module Federation و ماژول ارائه‌شده‌ای که ساخت واقعاً از آن استفاده کرده، فایل ورودی برای سرو شدن، و نوع فیلدهایی که کنترل می‌تواند جای آن‌ها بنشیند. دو مورد نخست پیش‌تر با دست از پیکربندی باندلر رونویسی می‌شد و اشتباه در هرکدام یک نشانهٔ واحد داشت — کنترل بارگذاری نمی‌شد — بدون هیچ سرنخی که کدام‌یک غلط بوده است.
بارگذاری دوباره، ساخت نصب‌شده را جایگزین می‌کند. این همان چرخهٔ عادی کار روی یک کنترل
است: تغییرش بدهید، npm run pack را اجرا کنید، دوباره بارگذاری کنید. لازم نیست ابتدا
ثبت قبلی را حذف کنید. ستون نسخه نشان می‌دهد کدام ساخت نصب است، تا بتوانید بررسی کنید
آنچه در حال اجراست همان چیزی است که آخرین بار بسته کرده‌اید.
برای حذف یک کنترل، سطر آن را علامت بزنید و حذف را انتخاب کنید. این کار کنترل را از محیط حذف می‌کند و بستهٔ ذخیره‌شده‌اش را پاک می‌کند؛ ارجاع مؤلفه در راهکار باقی می‌ماند، چون ممکن است محیط‌های دیگر هنوز کنترل را نصب داشته باشند.
کد کنترل کجا نگهداری می‌شود
بایت‌های بسته را پلتفرم ذخیره می‌کند و از نشانی خودِ پلتفرم سرو می‌کند. هیچ چیزی از میزبان بیرونی گرفته نمی‌شود، بنابراین:
- راهکار خودبسنده است — خروجی گرفتن از آن کد کنترل را با خود می‌برد، و وارد کردنش در محیط آزمون یا تولید یک کنترل کارآمد نصب می‌کند، نه اشاره‌ای به جایی که ساخته شده بود؛
- نشانی‌ای برای مجاز کردن وجود ندارد و نشانی‌ای هم نیست که کهنه شود.
کد یک کنترل نیازی به بارگذاری به‌عنوان منابع وب ندارد. منابع وب برای فایل‌های مستقلی است که خودتان می‌نویسید و با نام به آن‌ها ارجاع می‌دهید — یک شیوه‌نامه، یک تصویر، یک اسکریپت — نه برای خروجی ساخت یک کنترل.
پشت صحنه چه می‌گذرد
پیش از ذخیرهٔ هر چیزی، آرشیو بررسی می‌شود: اندازه‌اش، تعداد فایل‌هایش، اندازه‌ای که باز می‌شود، اینکه هیچ فایلی درون آن مسیری بیرون از پوشهٔ خودش را نام نبرد، اینکه هر فایل از نوعی باشد که پلتفرم سرو می‌کند، و اینکه مانیفستش با شمای منتشرشدهٔ بسته بخواند. سپس نام منطقی کنترل در برابر پیشوند ناشرِ مالک بررسی می‌شود.
بسته به‌صورت کامل ذخیره می‌شود و نخستین باری که کنترل واقعاً درخواست شود باز می‌شود. به همین دلیل است که کنترل پس از راه‌اندازی دوبارهٔ پلتفرم همچنان کار می‌کند و روی هر سروری یکسان رفتار می‌کند: بستهٔ ذخیره‌شده نسخهٔ واقعی است و فایل‌های بازشده تنها یک حافظهٔ میانی‌اند که خودش را دوباره می‌سازد.
نصب کنترل در یک محیط، آن را در هیچ محیط دیگری نصب نمی‌کند؛ کنترل هنگام خروجی گرفتن و وارد کردن راهکارش جابه‌جا می‌شود.
عیب‌یابی
- «بسته در ریشهٔ خود 'parsware.json' ندارد.» — فایل بارگذاری‌شده خروجی خام ساخت است نه
یک بسته. آن را با
npm run packدر پروژهٔ کنترل بسازید. - «کنترل سفارشی … باید با پیشوند ناشر …_ شروع شود.» — مقدار
logicalNameدرpackage.jsonکنترل با پیشوند ناشرِ مالک شروع نمی‌شود. آنجا تغییرش دهید و دوباره بسته بسازید. - «بسته … فایل دارد؛ بیشینه … است.» — تقریباً همیشه یعنی پوشهٔ
node_modulesبه آرشیو راه یافته است. خروجی ساخت را بسته کنید، نه کل پروژه را. - «کنترل سفارشی … پیش‌تر توسط راهکار دیگری در این محیط نصب شده است.» — نام منطقی گرفته شده است. کنترل را تغییر نام دهید یا ثبت دیگر را حذف کنید.
- «محیط … فعال نیست.» — تا پایان آماده‌سازی محیط صبر کنید یا محیط دیگری برگزینید.
هنگام نوشتن کنترل
بارگذاری بسته برای هر تغییر، چرخهٔ کندی است. در یک محیط توسعه، جدید گزینهٔ دومی هم
دارد، استفاده از سرور توسعهٔ در حال اجرا: نشانی‌ای را که npm run dev چاپ می‌کند بنویسید و
ثبت کنترل سفارشی را برگزینید. نام کنترل و تنظیمات federation آن از سرور توسعه خوانده
می‌شود و فرم‌ها کنترل را از همان‌جا بارگذاری می‌کنند، پس تغییری که ذخیره می‌کنید دفعهٔ بعد که
فرمی باز شود دیده می‌شود. تا وقتی کنترل این‌گونه ثبت است، ستون نسخه عبارت میزبانی‌شده
(توسعه) را نشان می‌دهد.
- اگر کنترل از پیش نصب شده است، اول آن را بردارید. سرور توسعه با همان نام منطقی کنترل ثبت می‌شود، پس فرمی که کنترل را به آن بسته‌اید همچنان از آن استفاده می‌کند.
- وقتی کارتان تمام شد، بسته را بارگذاری کنید. بسته جای ثبتِ سرور توسعه را می‌گیرد و ستون نسخه دوباره نسخهٔ ساخت را نشان می‌دهد.
این گزینه بیرون از محیط توسعه دیده نمی‌شود: کنترلی که این‌گونه ثبت شود بسته‌ای ندارد، پس کدش با راه‌حل جابه‌جا نمی‌شود. آماده کردن پروژهٔ کنترل برای این کار در ساخت یک کنترل سفارشی آمده است.
سناریوهای مرتبط
- ساخت یک کنترل سفارشی.
- اتصال یک کنترل سفارشی به یک فیلد.
- ثبت یک اپلیکیشن React سفارشی.
- ساخت یک راهکار.