تعریف فرم Model-Driven

شناسهٔ شِما: model-driven-form@2

نسخهٔ جایگزین‌شده: model-driven-form@1 (model-driven-form-v1.schema.json) همچنان منتشر و ثبت‌شده می‌ماند تا راه‌حلی که از پیش مستقر شده، همچنان در برابر همان شِمایی اعتبارسنجی شود که برایش نوشته شده بود. نسخهٔ ۲ تنها controlProps.lookupView اختیاری را می‌افزاید، پس هر تعریف نسخهٔ ۱ یک تعریف معتبر نسخهٔ ۲ هم هست. شِمای قابل‌خواندن توسط ماشین: model-driven-form.schema.json

بازنمایی مرجع یک فرم در Model-Driven Apps (بخش 6.7) — چیدمانی که برای دیدن و ویرایش یک رکورد به کار می‌رود. به شکل یکسان اعتبارسنجی می‌شود، چه از طراح بیاید، چه از یک فراخوانی API، چه از یک دستیار هوش مصنوعی، و چه از یک وارد کردن راه‌حل.

شکل

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	پیشوند ناشر در ابتدا، با snake-case کوچک.
displayName	string	بله	نام خوانای فرم.
entity	string	بله	نام منطقی موجودیت مالک.
description	string	خیر	خطی که در نوار عنوان فرم، زیر عنوان نمایش داده می‌شود.
icon	string	خیر	آیکونی که در نوار عنوان فرم نمایش داده می‌شود.
sections	array	یکی از دو	یک یا چند بخش عنوان‌دار — چیدمان تخت و قدیمی (پایین‌تر را ببینید).
tabs	array	یکی از دو	چیدمان غنی‌تر مبتنی بر زبانه (پایین‌تر را ببینید).
actions	array	خیر	کنش‌های قابل‌طراحی نوار فرمان.

یک فرم یا sections را حمل می‌کند یا tabs را، و هیچ‌کدام‌نداشتن مجاز نیست. تعریف‌های تازه باید از tabs استفاده کنند؛ sections پذیرفته می‌شود تا فرم‌های موجود کار کنند، و همچون یک زبانه از ردیف‌های تک‌ستونی رفتار می‌شود.

بخش (چیدمان قدیمی sections)

فیلد	نوع	اجباری	یادداشت‌ها
title	string	بله	سرعنوان بخش.
columns	integer	بله	ستون‌های چیدمان، ۱ تا ۴.
fields	array	بله	جای‌گذاری فیلدها (پایین‌تر را ببینید).

زبانه (چیدمان tabs)

فیلد	نوع	اجباری	یادداشت‌ها
id	string	خیر	شناسهٔ پایدار طراح.
title	string	بله	عنوان زبانه.
icon	string	خیر	آیکونی که کنار عنوان زبانه نمایش داده می‌شود.
rows	array	بله	ردیف‌های چیدمانِ تمام‌عرض: { id?, columns: 1–4, sections: [...] }، که هر بخش { id?, title, icon?, span?, fields, timeline? } است.

جای‌گذاری فیلد

فیلد	نوع	اجباری	یادداشت‌ها
field	string	بله	نام منطقی فیلد (باید روی موجودیت تعریف شده باشد).
label	string	خیر	بازنویسی برچسب؛ در صورت حذف، نام نمایشی فیلد به کار می‌رود.
control	string	خیر	نام منطقی یک کنترل سفارشی که به جای ویرایشگر بومی فیلد سوار می‌شود. کنترل باید در محیط نصب شده باشد؛ اگر نباشد، فیلد به ویرایشگر بومی خود بازمی‌گردد.
controlType	string	خیر	کنترل درون‌ساختی که فیلد با آن رسم می‌شود (بخش 6.13.5). یکی از Text، TextArea، Check، Toggle، Date، DateTime، Time، Lookup، Dropdown. آن را حذف کنید تا Player ورودی پیش‌فرض نوع دادهٔ فیلد را برگزیند.
controlProps	object	خیر	ویژگی‌های کنترل انتخاب‌شده (پایین‌تر را ببینید).

تقدم کنترل: یک control سفارشی بر controlType می‌چربد، و آن هم بر پیش‌فرض نوع دادهٔ فیلد. هر دو را حذف کنید تا Player پیش‌فرض را برگزیند.

ویژگی‌های کنترل (controlProps)

فیلد	نوع	خوانده‌شده توسط	یادداشت‌ها
dateFormat	string	Date، DateTime، Time	قالب نمایش. نشانه‌ها: yyyy/yy، MM، dd، HH، mm، ss؛ هر نویسهٔ دیگری عیناً نمایش داده می‌شود.
trueLabel	string	Check، Toggle	برچسبی که برای حالت «بله» نمایش داده می‌شود.
falseLabel	string	Check، Toggle	برچسبی که برای حالت «خیر» نمایش داده می‌شود.
rows	integer	TextArea	شمار ردیف‌های دیده‌شدنی، ۲ تا ۲۰.
lookupEntity	string	Lookup	نام منطقی موجودیتی که جستجوی رکورد در برابر آن رفع می‌شود.
lookupView	string	Lookup	نام منطقی نمایی که ستون‌های نمایش‌داده‌شده در پنل نتایج جستجوی رکورد را فراهم می‌کند. نبودنش به پلتفرم اجازه می‌دهد یکی را رفع کند — viewType در شِمای نما را ببینید.
lookupRowCount	integer	Lookup	چند سطر نامزد در پنل جستجوی رکورد یک‌جا پیشنهاد شود (۱ تا ۵۰۰). نبودنش پیش‌فرض پلتفرم یعنی ۱۰ را به کار می‌برد. سرور هر عددی را که خواسته شود مهار می‌کند — یک انتخابگر گزارش نیست. پس از نسخهٔ ۲ با گشاده‌سازی درجا افزوده شد: هر تعریفی که بدون آن معتبر بوده همچنان معتبر است.
options	array	Dropdown	گزینه‌های ثابت، هرکدام { value, label }، که تنها به همین یک فیلد تعلق دارند. برای هر چیزی که میان فیلدها یا جدول‌ها بازاستفاده می‌شود، یک مجموعه گزینه را ترجیح دهید: یک مجموعه، جزئی مشترک و نسخه‌دار با مقادیر ضدتصادم است، حال آنکه این گزینه‌ها فهرستی خصوصی روی یک فرم‌اند. فیلدی که نوع داده‌اش OptionSet است این را نادیده می‌گیرد و از مجموعهٔ خود برمی‌دارد.

ویژگی‌هایی که به controlType انتخاب‌شده مربوط نمی‌شوند نادیده گرفته می‌شوند، نه رد — پس عوض کردن کنترل یک فیلد و بازگرداندن آن، پیکربندی‌اش را از دست نمی‌دهد.

هر field ارجاع‌شده باید فیلدی باشد که روی موجودیت تعریف شده است — این قاعده علاوه بر اعتبارسنجی شِما، در زمان ذخیره نیز اعمال می‌شود.

بخش خط زمانی (timeline)

یک بخش در زبانه می‌تواند به‌جای گروهی از فیلدها، یک خط زمانی باشد: رکوردهای جدول‌های دیگر که فیلد جستجوی آن‌ها به رکورد باز اشاره می‌کند، در هم ادغام‌شده و جدیدترین در بالا — مثلاً ایمیل‌ها، تماس‌ها و یادداشت‌های یک مشتری در یک ستون. یک بخش یا این است یا آن: وقتی timeline وجود دارد، fields باید آرایه‌ای خالی باشد.

فیلد	نوع	اجباری	یادداشت‌ها
sources	array (۱ تا ۱۰)	بله	جدول‌هایی که خوانده می‌شوند، هر کدام یک ورودی (پایین‌تر).
pageSize	integer (۵ تا ۱۰۰)	خیر	تعداد موارد پیش از نمایش بیشتر؛ در نبودِ آن ۲۰.

هر منبع:

فیلد	نوع	اجباری	یادداشت‌ها
entity	string	بله	نام منطقی جدول منبع.
regarding	string	بله	فیلد جستجویی روی جدول منبع که به جدول فرم اشاره می‌کند، یا جستجوی چندجدولی که آن را در فهرست خود دارد. خط زمانی ردیف‌هایی را نشان می‌دهد که مقدارشان رکورد باز است.
date	string	بله	یک فیلد تاریخ و زمانِ منبع (از جمله فیلدهای سیستمی مانند created_at_utc). موارد بر اساس آن مرتب می‌شوند، جدیدترین در بالا.
title	string	بله	فیلدی که عنوان هر مورد است.
body	string	خیر	فیلدی که آغاز متن آن زیر هر مورد نمایش داده می‌شود.
type	string	خیر	یک فیلد مجموعهٔ گزینه که ردیف‌های منبع را از هم جدا می‌کند. آیکون و رنگ هر مورد از گزینهٔ آن گرفته می‌شود، فیلتر برای هر گزینه یک دکمه نشان می‌دهد و جدید برای هر گزینه یک ورودیِ ازپیش‌پرشده دارد.
status	string	خیر	فیلدی که کنار تاریخ هر مورد نمایش داده می‌شود.

هنگام ذخیره و هنگام ورود (import)، هر نام با جدول‌های محیط سنجیده می‌شود: جدول منبع باید وجود داشته باشد، regarding باید بتواند به جدول فرم اشاره کند، date باید تاریخ باشد، type باید انتخاب (Choice) باشد و بقیه باید وجود داشته باشند. خط زمانی‌ای که یکی از این‌ها را برآورده نکند رد می‌شود (modelapps.form.timeline_*)، نه اینکه خالی نمایش داده شود. حذف فیلدی که خط زمانی از آن استفاده می‌کند، آن را از خط زمانی برمی‌دارد: بخشِ اختیاری حذف می‌شود، و منبعی که regarding، date یا title خود را از دست بدهد کنار گذاشته می‌شود.

نمونه

{
  "logicalName": "par_invoice_main",
  "displayName": "Main",
  "entity": "par_invoice",
  "description": "The invoice's main form",
  "icon": "Receipt",
  "tabs": [
    {
      "id": "tab-general",
      "title": "General",
      "rows": [
        {
          "id": "row-1",
          "columns": 2,
          "sections": [
            {
              "id": "sec-header",
              "title": "Header",
              "fields": [
                { "field": "par_name" },
                { "field": "par_total", "label": "Amount" },
                {
                  "field": "par_due",
                  "controlType": "Date",
                  "controlProps": { "dateFormat": "dd/MM/yyyy" }
                },
                {
                  "field": "par_paid",
                  "controlType": "Toggle",
                  "controlProps": { "trueLabel": "Paid", "falseLabel": "Unpaid" }
                },
                { "field": "par_signature", "control": "par_signature_pad" }
              ]
            }
          ]
        }
      ]
    }
  ]
}