تعريف النموذج المبني على البيانات

معرّف المخطط: 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	نعم	أعمدة التخطيط، من 1 إلى 4.
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	عدد الصفوف الظاهرة، من 2 إلى 20.
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	لا	حقل يُعرض بجانب تاريخ كل عنصر.

عند الحفظ وعند الاستيراد يُتحقَّق من كل اسم مقابل جداول البيئة: يجب أن يوجد جدول المصدر، وأن يستطيع 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" }
              ]
            }
          ]
        }
      ]
    }
  ]
}