پرش به مطلب اصلی

مانیفست کنترل سفارشی

شناسهٔ شِما: custom-control-manifest@1 شِمای قابل‌خواندن توسط ماشین: custom-control-manifest.schema.json

توصیف مرجع یک کنترل سفارشی (به سبک PCF، بخش 6.3): همان remote در Module Federation که Model-Driven App Player آن را به‌جای یک ویرایشگر بومی فیلد درون یک فرم یا نما سوار می‌کند. یک مانیفست به شکل یکسان اعتبارسنجی می‌شود، چه از طریق Admin Control Center ثبت شده باشد، چه با یک فراخوانی مستقیم API ارسال شده باشد، چه یک دستیار هوش مصنوعی تولیدش کرده باشد، و چه درون یک وارد کردن راه‌حل حمل شده باشد — قاعدهٔ تک‌مسیرِ اعتبارسنجی (بخش 6.7).

این مانیفست با دست نوشته نمی‌شود. ثبت یک کنترل، بارگذاری بسته‌ای است که @parsware/pack ساخته، و این مانیفست از روی parsware.json همان آرشیو ساخته می‌شود (§۲۸). آنچه در پی می‌آید شکل ذخیره‌شده را توصیف می‌کند، برای خواندن یک راهکار خروجی‌گرفته‌شده یا اعتبارسنجی راهکاری که خودتان تولید کرده‌اید.

شکل​

فیلدنوعاجبارییادداشت‌ها
logicalNamestringبلهپیشوند ناشر در ابتدا، با snake-case کوچک (مثلاً par_signature_pad). از راه ویژگی control یک فیلد فرم به آن فیلد بسته می‌شود.
displayNamestringبلهنام خوانا برای انسان که در پالت فیلدهای طراح فرم نمایش داده می‌شود.
descriptionstring | nullخیرتوصیف کوتاهی که کنار کنترل نمایش داده می‌شود.
scopestringبلهنام scope سراسری کانتینر Module Federation (برای هر remote یکتا)، که از mf-manifest.json بیلد خوانده می‌شود نه رونویسی.
modulestringبلهمسیر ماژول در معرض قرارگرفته که Player بارگذاری می‌کند (مثلاً ./Control). باید با ./ آغاز شود. آن هم از بیلد خوانده می‌شود.
entryFileNamestringخیرفایل ورودی کانتینر درون بسته (مثلاً remoteEntry.js). نشانی سرو از محیط، نام منطقی و همین محاسبه می‌شود — نشانی‌ای برای ذخیره وجود ندارد. در حالت Hosted خالی است.
packageHashstring | nullخیرSHA-256 شانزده‌شانزدهی حروف‌کوچک آرشیو بسته‌ای که کنترل از روی آن ثبت شده. هنگام وارد کردن در برابر بایت‌هایی که در بستهٔ راهکار جابه‌جا شده‌اند بررسی می‌شود، تا آنچه سرو می‌شود همان چیزی باشد که خروجی گرفته شده. در حالت Hosted null است.
remoteEntryUrlstring | nullخیرفقط حالت Hosted: نشانی مطلق http(s) به یک remoteEntry.js که بیرون سرو می‌شود، برای بارگذاری داغ هنگام نوشتن کنترل. ثبت آن جز در محیطی با ردهٔ توسعه پذیرفته نمی‌شود، و یک کنترل Hosted در بستهٔ راهکار جابه‌جا نمی‌شود — کدش از آنِ پلتفرم نیست که آن را حمل کند.
substitutesForstring[]بلهنوع کنترل‌های فیلدی که این کنترل می‌تواند به آن‌ها بسته شود: یک یا چند مورد از Text، MultilineText، Number، Boolean، DateTime، Lookup، File، Image، Custom. باید دست‌کم یک ورودی داشته باشد. پالت فیلد این کنترل را تنها جایی پیشنهاد می‌دهد که نوع کنترل یک فیلد منطبق باشد. این‌ها خانواده‌های نوع داده فیلد هستند — نه نام کنترل‌های آماده‌ای که یک جای‌گذاری فرم انتخاب می‌کند (TextArea، Toggle، Dropdown، …)؛ آن‌ها واژگان دیگری هستند که تنها در چهار نام مشترک‌اند.

آنچه دیگر ندارد​

requestedScopes و declaredEntities حذف شده‌اند، و additionalProperties برابر false است، پس مانیفستی که هنوز هرکدام را داشته باشد رد می‌شود نه اینکه بی‌صدا نادیده گرفته شود. یک کنترل با دسترسی‌های همان کسی اجرا می‌شود که از آن استفاده می‌کند (§۲۴): مجموعهٔ اسکوپ درخواستی همیشه تنها با نشستِ خودِ کاربر اشتراک گرفته می‌شد، پس می‌توانست کاربرِ کنترل را تنگ‌تر کند و هرگز گشوده‌تر نه، و فهرست جدول‌های اعلام‌شده را هیچ مسیر کدی نمی‌خواند. حذف هر دو، داستان امنیت را از دو دستگیره به یک جمله تبدیل می‌کند.

remoteEntryUrl اجباری هم رفته است. بسته اکنون به‌عنوان یک بستهٔ سرو‌شده از نشانی خودِ پلتفرم جابه‌جا می‌شود، پس نشانی محاسبه می‌شود نه ذخیره (§۲۸).

قرارداد کنترل​

ماژول در معرض قرارگرفته (./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 این props را در زمان رندر تأمین می‌کند. یک کنترل تنها از طریق context (یک ParswareRuntime) به پلتفرم می‌رسد — هرگز با فراخوانی مستقیم Gateway یا Identity.

کجا اعتبارسنجی می‌شود​

  • ثبت — لایهٔ Application مانیفست را در برابر custom-control-manifest@1 اعتبارسنجی می‌کند و پیش از ثبت کنترل در یک محیط، الزام می‌کند که logicalName با پیشوند ناشر مالک آغاز شود.
  • وارد کردن راه‌حل — هر مانیفست جاسازی‌شده در یک بستهٔ راه‌حل، پیش از ثبت کنترل در محیط مقصد، دوباره در برابر همان شِما اعتبارسنجی می‌شود.

یادداشت‌های امنیتی​

یک کنترل سفارشی در همان realm جاوااسکریپت پوسته اجرا می‌شود (Module Federation، نه یک iframe — بخش 6.3)، بنابراین مرز اعتماد جای دیگری اعمال می‌شود:

  • یک کنترل بسته‌بندی‌شده از نشانی خودِ پلتفرم سرو می‌شود، پس مبدأ بیرونی‌ای برای مجاز کردن وجود ندارد. فهرست مجاز CSP همچنان حالت Hosted را کنترل می‌کند، که تنها شکلی است که سازنده می‌تواند بسته‌اش را به هر جایی نشانه بگیرد — و بیرون از محیط توسعه پذیرفته نمی‌شود.
  • آرشیو پیش از ذخیره شدن بررسی می‌شود: اندازه، تعداد فایل، اندازه‌ای که باز می‌شود، اینکه هیچ ورودی‌ای مسیری بیرون از پوشهٔ خودش را نام نبرد، و اینکه هر فایل از نوعی باشد که پلتفرم سرو می‌کند.
  • کنترل تنها در صورتی قابل بارگذاری است که یک راهکار آن را در آن محیط مستقر کرده باشد، و درهم‌سازِ بسته هم هنگام وارد کردن و هم پیش از باز شدن روی دیسک بررسی می‌شود.
  • هر فراخوانی داده‌ای که از طریق Runtime SDK انجام می‌دهد، در سمت سرور در برابر App Context Token مجوزدهی می‌شود که اسکوپ‌های خودِ کاربر را حمل می‌کند. یک کنترل دقیقاً همان کاری را می‌تواند بکند که کاربرش می‌تواند، و هیچ فیلدی در این مانیفست این را تغییر نمی‌دهد.

مرتبط​