> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# سياق منشئ النماذج

> افهم القيم واختصارات الشجرة ومثيلات التكرار وحدود الاتصال/عدم الاتصال المتاحة لتعبير نموذج KayanOS.

## استخدم هذه الصفحة قبل كتابة تعبير نموذج

يقيّم كل تعبير نموذج في KayanOS ضمن سياق: النموذج وقيمه المحفوظة أو الجارية والعنصر الحالي في شجرة النموذج ومعرفات الجلسة/العضو المختارة. قد يكون التعبير نفسه صالحاً في حقل وفارغاً أو مضللاً في آخر لأن السياق مختلف.

استخدم هذا المرجع للقيم الافتراضية والرؤية وقابلية التحرير والتحقق والقيم المحسوبة ونص الإجراء وتعبيرات منشئ النموذج الأخرى. يصف القيم التي يكشفها منشئ النموذج؛ ولا يمنح وصولاً ولا يحول شرط رؤية إلى تفويض ولا يجعل البحث آمناً لمشارك عام. للصياغة وكتالوج الدوال الكامل، راجع [بنية لغة التعبيرات](/ar/reference/expressions/language-syntax) و[تعبيرات النماذج وعمليات البحث](/ar/reference/expressions/forms-and-lookups).

![سياق منشئ النماذج في KayanOS لنموذج طلب خدمة مواطن.](https://kayanos.app/docs-images/ar/reference/forms-form-builder-context.png)

## حدد أولاً موضع تقييم التعبير

قبل نسخ تعبير، حدد الأجزاء الأربعة لسياقه:

| السؤال                       | سبب أهميته                                                                                            |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| أي عنصر يقيّمه؟              | يملك الحقل `$value` و`$defaultValue`؛ أما الإجراء أو كتلة النص أو التوقيع فلها خصائص عنصر أخرى.       |
| هل العنصر داخل مكرر؟         | تتغير `$index` و`$item` وعلاقات الأب/الإخوة وشكل القيمة المحفوظة.                                     |
| هل النموذج عادي أم غير متصل؟ | تحظر النماذج غير المتصلة عمداً عدة ميزات ودوال معتمدة على البيانات والسياق.                           |
| من يستخدم الجلسة؟            | يؤثر `currentUserType` ومعرفات العضو/العام وملكية الجلسة وسياسة الخادم في ما ينبغي عرضه أو السماح به. |

يعرض المنشئ أشكال سياق ممثلة لمساعدة كتابة التعبير. ليست هذه الأشكال معاينة لبيانات الإنتاج ولا يجوز استخدامها للاستنتاج أن حقلاً أو نتيجة محدد أو سجلاً متاح لكل مشارك وقت التشغيل.

## جذور ومعرفات مستوى النموذج

يكشف السياق المشترك الجذور والمعرفات الثابتة التالية:

| الاسم                           | المعنى                                                                                                                             | مثال استخدام                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `$form`                         | كائن النموذج الحالي: العنوان والوصف وحالة التحرير والمتغيرات وبنية الأبناء.                                                        | استخدمه عندما تعتمد القاعدة فعلاً على خاصية مستوى النموذج.      |
| `$`                             | المتغيرات المعلنة مباشرةً، مع الأبناء العليا المكشوفة للنموذج. كل إدخال حقل هو كائن حقل مكشوف؛ اقرأ الإجابة المحفوظة عبر `.value`. | `$.service_category.value == "regulated"`                       |
| `organizationId`                | معرف المؤسسة النشطة.                                                                                                               | مرره فقط عندما تحتاج دالة صادرة صراحةً إلى سياق المؤسسة.        |
| `formId` / `formVersionId`      | النموذج والإصدار اللذان يقدمان البنية الحالية.                                                                                     | شخّص سلوكاً خاصاً بإصدار؛ لا تعرض المعرفات التقنية لمستخدم عام. |
| `sessionId`                     | معرف جلسة النموذج الحالية عندما يوجد.                                                                                              | اربط سجل اختبار/دعم مضبوطاً.                                    |
| `initiatorId` / `initiatorType` | بادئ الجلسة وهل هو عضو أو مشارك عام.                                                                                               | كَيِّف عبارة غير حساسة، ولا تقرر التفويض أبداً.                 |
| `publicUserId`                  | معرف المشارك العام عند توافره.                                                                                                     | استخدمه فقط في تصميم جلسة عامة معتمد.                           |
| `referenceNumber`               | الرقم المرجعي المكشوف للجلسة عند توافره.                                                                                           | اعرض مرجعاً شبيهاً بالإيصال بعد إرسال مراجع.                    |
| `$form.submissionNumber`        | رقم التقديم نفسه المخصص للعرض، مثل `RC-023`، مكشوفاً صراحةً على كائن النموذج.                                                      | `"رقم الطلب: " + $form.submissionNumber`                        |
| `sessionInScopes`               | رموز النطاق المرتبطة بالجلسة.                                                                                                      | شخّص السياق؛ لا تعتمد على تعبير لإنفاذ قاعدة نطاق.              |
| `currentMemberId`               | معرف العضو المسجل حالياً عند انطباقه.                                                                                              | استخدمه فقط حيث يسمح عقد تعبير/دالة صادر بذلك.                  |
| `currentUserType`               | `member` أو`public` أو لا قيمة.                                                                                                    | قدم فرق عرض آمن بين تجربتي العام والعضو.                        |

استخدم `$form.submissionNumber` عندما ينبغي أن يسمي التعبير رقم التقديم
المخصص للعرض صراحةً. وهو ليس `sessionId` الداخلي، ولا يوجد اسم
`submissionNumber` في جذر السياق.

ليست `$` جذراً سحرياً لقاعدة البيانات. تبدأ بمتغيرات النموذج وتضم أبناء النموذج العلويين المكشوفين في السياق المشترك. المتغير قيمة مباشرة، أما مفتاح الحقل فيحل إلى كائن الحقل المكشوف؛ استخدم `.value` لقراءة الإجابة المحفوظة. يجب الوصول إلى قيمة مكرر متداخل عبر سياق العنصر/الأب المحلي بدلاً من افتراض أنها قيمة عليا.

```jexl theme={null}
$.service_category.value == "regulated" && currentUserType == "member"
```

يمكن أن يظهر ذلك تذكيراً داخلياً قصيراً للعضو، لكنه لا يجوز أن يفوض قراراً منظماً أو يكشف بيانات لمشارك عام.

## العنصر الحالي واختصارات الشجرة

لكل عنصر موضع في شجرة النموذج. يمنح KayanOS العنصر اختصارات محلية حتى لا يحتاج التعبير إلى مسار هش عبر النموذج كله.

| الاختصار                | متاح من                | المعنى                                                                        |
| ----------------------- | ---------------------- | ----------------------------------------------------------------------------- |
| `$this`                 | سياق العنصر الحالي     | العنصر الذي يقيّم التعبير. استخدمه فقط إذا كشفه سطح التعبير المختار.          |
| `$parent`               | عنصر ابن               | القسم أو مثيل المكرر الأب المباشر.                                            |
| `$siblings`             | عنصر له إخوة           | عناصر الأبناء القريبة للأب نفسه.                                              |
| `$grandparent`          | عنصر متداخل            | أب `$parent`.                                                                 |
| `$uncles`               | عنصر متداخل            | الأبناء المنتمون إلى `$grandparent`؛ مفيد فقط عندما تكون البنية مستقرة عمداً. |
| `$repeatables`          | داخل مكرر واحد أو أكثر | حاويات المكرر الموجودة أثناء السير صعوداً من العنصر.                          |
| `$repeatable_instances` | داخل مثيل مكرر         | المثيل الحالي لكل مكرر محيط.                                                  |
| `$index`                | داخل مكرر              | موضع المثيل الحالي؛ عامله كقيمة عرض/فهرسة لا كمعرف أعمال.                     |
| `$item`                 | داخل مكرر بوضع حلقة    | عنصر مصدر الحلقة، ولا يوفر لمجرد وجود مكرر يتحكم فيه المستخدم.                |
| `$value`                | سياق حقل               | قيمة الحقل الحالية.                                                           |
| `$defaultValue`         | سياق حقل               | القيمة الافتراضية المضبوطة قبل أو بجانب إدخال المستخدم.                       |

استخدم قيمة أخ لتطبيق شرط محلي؛ فهذا أوضح وأكثر أماناً من الاعتماد على مسار طويل هش.

```jexl theme={null}
$siblings.requires_inspection.value == true
```

إذا كان يمكن أن يغيب `requires_inspection`، عالج النتيجة صراحةً بدلاً من معاملة الخطأ/الفراغ كاعتماد.

```jexl theme={null}
($siblings.requires_inspection.value || false) == true
```

يحافظ المنشئ أيضاً على مسارات العناصر مثل مسارات الأبناء ومثيلات المكرر لبناء السياق والإكمال التلقائي. عاملها كوسائل تنقل للمنشئ لا كعقد تكامل عام أو بديل لمفتاح الحقل.

## القيم حسب نوع الحقل

يوفر محرر التعبير أشكالاً ممثلة حتى يرى المنشئ السلوك المتوقع للعنصر. تظل القيمة المحفوظة الفعلية مرتبطة بإعداد الحقل وإدخال المستخدم.

| عائلة الحقل           | شكل قيمة التعبير المعتاد                                                   | الاستخدام الحذر                                                  |
| --------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| نص ومساحة نص          | نص                                                                         | نظف/تحقق فقط عندما تتطلب قاعدة الخدمة ذلك؛ القيمة الفارغة شائعة. |
| رقم                   | رقم                                                                        | تحقق من غياب/لا رقمية الإدخال قبل الحساب.                        |
| منطقي                 | `true` أو`false`                                                           | فضل مقارنة صريحة عندما يكون للغياب معنى مختلف.                   |
| تاريخ وتاريخ-وقت ووقت | قيمة تاريخ/وقت                                                             | استخدم دوال التاريخ واختبر المنطقة الزمنية/العرض.                |
| مال                   | مبلغ رقمي مع `currency` المضبوطة                                           | لا تفترض تحويل العملة؛ لا تقارن أو تحسب إلا ضمن عقد عملة مراجع.  |
| اختيار                | قيمة خيار واحدة أو قائمة للاختيار المتعدد                                  | قارن قيم الخيارات المخزنة لا التسميات المرئية فقط.               |
| نص غني                | قيمة نص غني                                                                | لا تعامله كنص عادي موثوق لمخرج عام.                              |
| ملف                   | بيانات ملف مثل مفتاح التخزين والاسم والاسم الأصلي والحجم والنوع            | لا تكشف بيانات الملف أو رابطه لمشارك غير مخول عبر تعبير.         |
| اختيار كيان           | معرف مختار مع شكل سجل ممثل في المنشئ                                       | الإتاحة مرتبطة بالمصدر المضبوط وصلاحيات وقت التشغيل.             |
| اختيار جلسة نموذج     | سجل واحد أو قائمة؛ قد يشكل `saved_state` للجلسة المختارة من النموذج المصدر | احم غياب الجلسة المصدر ولا تعتمد عليه في نموذج غير متصل.         |
| قيمة محسوبة           | سطح قيمة مشتقة                                                             | اجعل الحساب حتمياً ولا تستخدمه كقرار تفويض.                      |

بالنسبة لحقل اختيار متعدد، اختبر سلوك القائمة الفعلي بدلاً من نسخ مقارنة اختيار مفرد:

```jexl theme={null}
contains($.requested_services.value, "inspection")
```

استخدم الدالة فقط عندما تكون مدرجة لسياق النموذج. قد يعرض محرر التعبير دالة عامة يحظرها مدقق عدم الاتصال أو وقت التشغيل.

## كائنات العناصر المكشوفة والقوائم المتداخلة

يطابق الإكمال التلقائي كائنات النموذج العامة التي تستخدمها التعبيرات. يكشف كل عنصر `key` و`path` ومميّز فئته في `type` (مثل `field` أو`section`)؛ ويكشف الحقل نوع الإدخال المحدد في `fieldType`، إضافة إلى `title` و`tooltip` و`value` و`defaultValue` و`editable` و`required` و`validation` و`isValid` و`index`. تضيف حقول الاختيار `selectionType` و`options` وأحد `record` أو`records`. يضيف حقل المال `currency`، ويضيف حقل الملف `multiple` و`accept` و`maxSizeBytes`.

تكشف الأقسام `title` و`description` و`editable` و`children` و`index` و`isValid`. وتكشف المكررات `repeaterTitle` و`minRepeat` و`maxRepeat` و`requestedRepeat` و`actualRepeat` و`instances` و`repeatType` و`isValid`؛ كما تكشف مكررات الأقسام `layoutMode` و`tableResponsiveMode` و`tableColumns`. تكشف الإجراءات `title` و`description` و`clickable` و`loading` و`actionType` و`isValid` و`calls`. ولا تظهر خصائص نوع الإجراء مثل `linkTarget` و`docxFieldKey` إلا عندما يدعمها الإجراء.

تستخدم اقتراحات القوائم عنصراً ممثلاً واحداً حتى تكشف الكتابة بعد محدد قائمة مثل `.signatures[.` أو`.instances[.` خصائص العنصر. هذا العنصر عينة لبيانات الإكمال التلقائي، وليس دليلاً على أن القائمة الحية غير فارغة.

### كائن التوقيع

يكشف عنصر التوقيع حالة التوقيع الحالية والمتجاوزة:

| الخاصية                                                           | الشكل والمعنى                                                                                                        |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `ready` و`activeRequestId` و`revision` و`snapshotHash` و`isValid` | بيانات الجاهزية والتحضير الحالية. قد يغيب `activeRequestId` وقت التشغيل.                                             |
| `snapshotProof`                                                   | بيانات الدليل: `fileUrl` و`fileName` و`fileType` و`fileSizeBytes` و`sha256`؛ وقد تكون null قبل وجود الدليل.          |
| `snapshotItems`                                                   | عناصر اللقطة المحددة، ولكل منها `key` و`type` و`title` و`description` اختياري و`value` اختيارية و`children` متداخلة. |
| `signatures` و`staleSignatures`                                   | قائمتا ملخصات التواقيع. قد تكون القائمة الحالية فارغة؛ وتمثل الملخصات القديمة طلبات متجاوزة.                         |

يكشف كل ملخص توقيع `id` و`requestId` و`ruleKey` و`memberId` و`resolution` و`status` و`notes` و`reason` و`signingCapacity` و`signedAt` و`symbolicSignature` و`symbolicSignatureHash` و`stale`. عامل `signingCapacity` و`symbolicSignature` كحمولتي دليل يمكن أن يتطور تركيبهما الداخلي؛ ولا تكتب قواعد سياسة تعتمد على حقول متداخلة غير موثقة.

```jexl theme={null}
$.approval_signature.signatures[.status == "completed" && .resolution == "approve"]
```

تعني النتيجة الفارغة عدم وجود توقيع حالي مطابق. ولا تعني أن توقيعاً قديماً ما زال حالياً، أو أن المتطلبات السابقة تحققت، أو أن المشارك مخول بالاعتماد.

## المكررات: يتغير السياق لكل مثيل

استخدم مكرراً عندما يحتاج طلب خدمة المواطن عدداً متغيراً من الملاحظات أو المستندات أو صفوف المعاينة. يملك كل مثيل قيمه المحلية. ينبغي أن تستخدم قاعدة داخل صف ملاحظة قيمة/إخوة ذلك الصف لا قيمة على مستوى الطلب تشترك في تسمية عرضاً.

### المكررات التي يتحكم بها المستخدم

في المكرر الذي يتحكم به المستخدم يضيف العضو أو المشارك مثيلات ويحذفها ضمن الحدود المضبوطة. تعرف `$index` موضع المثيل الحالي لعبارة مثل «الملاحظة 2»؛ وليست معرف سجل ثابتاً وقد تتغير إذا أعيد ترتيب الصفوف أو حذفت.

```jexl theme={null}
"Observation " + ($index + 1)
```

تحقق من القيم الفعلية في كل مثيل. لا يجوز لعدد التكرار وحده أن يقرر أهلية الطلب للاعتماد.

### مكررات وضع الحلقة

في مكرر وضع الحلقة تتوفر `$item` لعنصر المصدر و`$index` لموضعه. استخدم بديلاً مراجعاً لخاصية اختيارية.

```jexl theme={null}
"Inspection " + ($index + 1) + ": " + ($item.site_name || "site not supplied")
```

اختبر العنصر الأول وعنصراً لاحقاً وعنصر مصدر فارغاً وغياب عناصر المصدر. لا تفترض وجود `$item` في مكرر يتحكم فيه المستخدم.

### قاعدة محلية بسيطة

في ملاحظة متكررة، اجعل الملاحظة مطلوبة فقط عندما يعلّم الصف الحالي غير آمن:

```jexl theme={null}
$siblings.safety_status.value == "unsafe"
```

اختبر حالات آمن وغير آمن وغائب وصف أول وصف لاحق وصف مضاف حديثاً. يغير تعبير الرؤية أو الإلزام تجربة النموذج؛ وتبقى سياسة الخادم مسؤولة عن قرار الانتقال/الاعتماد النهائي.

## النماذج العادية وغير المتصلة

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

لصيغة معاينة غير متصلة اجعل التعبيرات محلية وحتمية:

```jexl theme={null}
$.requires_inspection.value == true && isNotEmpty($.site_address.value)
```

لا تستخدم بحث النموذج أو دوال الصلاحية أو كياناً/جلسة مختارة شرطاً يجعل الإرسال غير المتصل صالحاً. راجع [النماذج دون اتصال](/ar/build/offline-forms) لسلوك الحزم والملفات المحلية والمزامنة، و[تعبيرات النماذج وعمليات البحث](/ar/reference/expressions/forms-and-lookups) لدوال البحث/الصلاحيات المحظورة.

## توجيه الجلسة إلى دور عند كيان

نطاق الدور الديناميكي عنصر توجيه على مستوى النموذج. يحل دوراً وكياناً عند حفظ جلسة نموذج عادي. اضبط الدور ورمز التوجيه في حقلين منفصلين. على سبيل المثال:

* **مفتاح الدور:** `printing_manager`
* **نوع النطاق:** `locations`
* **رمز التوجيه:** `$.location.value`

يجب أن ينتمي الكيان الذي يعيده رمز التوجيه إلى نوع النطاق. يمكن للرمز استخدام حقول النموذج الأخرى وإرجاع مرجع كيان مؤهل واحد أو مصفوفة مراجع أو `null`. تستمر النماذج الحالية التي تستخدم `roleScope(roleKey, entityId)` في العمل، لكن عناصر التوجيه الجديدة لا تحتاج إلى هذه الدالة.

* تعني `null` «لا يوجد توجيه» وهي نتيجة صالحة.
* يمنع المسار غير الفارغ الحفظ إذا كان الدور أو الكيان غير موجود، أو تابعاً لمؤسسة أخرى، أو لا يطابق نوع النطاق.
* يربط التوجيه الجلسة بدور عند كيان؛ ولا يمنح أفعال العرض في القائمة أو الفتح أو التحديث أو الحذف أو الإجراءات.
* يحتفظ الدور الفارغ بقائمة الجلسات الموجهة إليه. لا يعاد كتابة سجل جلسة أو عضو عند إسناد عضو إلى الدور لاحقاً.
* معاينة المنشئ تشخيصية فقط. يعيد الخادم حل المسار والتحقق منه قبل حفظه.
* لا تدعم النماذج غير المتصلة نطاقات الأدوار الديناميكية.

يستخدم كل فعل نموذج مفعّل في صلاحيات الدور وضع ربط واحداً. يمنح **نطاق الكيان** الفعل لجلسات ذلك النموذج ضمن نطاق الكيان المختار. ويمنحه **الدور عند الكيان** فقط لجلسات ذلك النموذج الموجهة إلى هذا الدور عند ذلك الكيان. عندما يدعم النموذج الوضعين، اختر الوضع المقصود لكل فعل؛ ولا يدمج الوضعان.

## ابنِ واختبر قاعدة تعتمد على السياق

استخدم بروتوكول الاختبار الصغير القابل للتكرار التالي:

1. صغ القرار بلغة عادية: «اعرض تفاصيل المعاينة عندما تكون `requires_inspection` صحيحة في هذا الطلب».
2. ضع القاعدة على الحقل/القسم الذي يملك القرار، لا على عنصر بعيد.
3. استخدم أصغر جذر محلي أو مرجع أخ يعبر عنها.
4. اختبر جلسات عضو وعام إذا كان النموذج يدعم كليهما، وأكد أنهما يريان الفرق غير الحساس المقصود فقط.
5. اختبر الغياب/null وfalse وtrue ومثيل المكرر الأول/اللاحق وجلسة محفوظة/معاد فتحها.
6. اختبر إجراء الخادم أو الإرسال المقابل، وتحقق من بقاء الفاعل غير المخول مرفوضاً حتى إن فرض قيمة على العميل.
7. للنماذج غير المتصلة، شغّل المدقق غير المتصل واختبر إرسالة متزامنة حقيقية قبل النشر.

## أخطاء شائعة

| الخطأ                                 | سبب فشله                                 | النهج الأفضل                                               |
| ------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
| نسخ تعبير قالب أو تسلسلي إلى نموذج    | تختلف الجذور وتوافر الدوال بحسب السياق.  | ابدأ بسياق النموذج واربط بصفحة الدوال الخاصة بالسياق.      |
| استخدام `$item` في مكرر ليس بوضع حلقة | تزود `$item` لسياق مكرر الحلقة فقط.      | استخدم سياق الحقل/الأخ/المثيل الحالي، أو أعد تصميم المكرر. |
| معاملة `$index` كمعرف دائم            | هو موضع لا مفتاح سجل ثابت.               | خزّن/استخدم معرف أعمال معتمداً عند الحاجة.                 |
| إخفاء حقل لحماية بيانات               | رؤية العميل ليست تحكماً بالوصول.         | أنفذ القاعدة في صلاحيات الخادم وتجنب كشف بيانات بحث حساسة. |
| الاعتماد على دالة متصلة دون اتصال     | تحظرها البنية/المدقق غير المتصلان عمداً. | استخدم قيماً محلية ودوال حتمية أو اجعل النموذج عادياً.     |
| افتراض أن شكل عينة المنشئ بيانات حية  | أشكال الإكمال التلقائي ممثلة.            | اختبر جلسة مضبوطة فعلية بقيم حقل مهيأة فعلاً.              |

## أدلة ذات صلة

* [بنية لغة التعبيرات](/ar/reference/expressions/language-syntax)
* [تعبيرات النماذج وعمليات البحث](/ar/reference/expressions/forms-and-lookups)
* [دوال النماذج ومرشحات البحث](/ar/reference/expressions/helpers/forms)
* [النماذج والحقول والقوائم المتكررة](/ar/build/form-fields-and-repeatables)
* [النماذج دون اتصال](/ar/build/offline-forms)
* [الصلاحيات والإتاحة](/ar/reference/permissions-and-availability)