> ## 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 يعرض الجذور والدوال المتاحة لمرجع طلب خدمة مواطن.](https://kayanos.app/docs-images/ar/reference/expressions-contexts.png)

| موضع التنفيذ | متغيرات الجذر الرئيسية | دوال خاصة بالسياق | حد مهم |
| - | - | - | - |
| قيمة افتراضية للكيان | `$record` و`$organizationId` و`$entityKey` و`$now` | الدوال العامة | لا يكون `$` جذر القيمة الافتراضية هنا. |
| شرط/قابلية تعديل/تحقق كيان | `$` و`$value` و`$relations` و`$member` | الدوال العامة ودوال التحقق | يفشل شرط الرؤية وقاعدة التعديل ونتيجة التحقق بطرق مختلفة. |
| حقل محسوب متزامن | `$` و`$value` و`$relations` و`$inverseRelations` و`$statusTemplates` | الدوال العامة | يزال ناتج الحقل الحالي فقط من `$` وقد تستقر التبعيات عبر عدة تمريرات. |
| حقل محسوب في الخلفية | `$` و`$relations` و`$inverseRelations` | الدوال العامة | تُقيّم تبعيات `$.field_key` المكتشفة غير الدائرية أولاً؛ لا يوجد `$value` أو`$statusTemplates`؛ كل حقل مرة واحدة. |
| معرّف كيان تسلسلي | `$` و`$record` وجذور النطاق/التسلسل | `serialPad` و`serialDate` | استخدم تنسيقاً حتمياً فقط. |
| نموذج عادي | `$this` و`$form` و`$` وجذور التكرار و`$value` وجذور العضو/الجلسة | دوال النموذج و`f.*` ودوال يوم العمل | تسهيل الواجهة/البيانات ليس تفويضاً. |
| نموذج غير متصل | جذور النموذج المحلية فقط | لا دوال بيانات أو صلاحيات | تحظر `getRecord` و`getRecords` ودوال الفعل/النطاق. |
| ترقيم نموذج | جذور حالة الحفظ والحقول والبادئ والتسلسل | `serialPad` و`serialDate` | تختلف الجذور عن المعرّفات التسلسلية للكيان. |
| قالب مستند | `$record` و`$inverseRelations` و`$organization` و`$member` و`$now` | `getRecords` الخاص بالقالب | `$relations` كائن محفوظ فارغ حالياً؛ ويختلف عقد البحث ووضع التنفيذ عن النموذج. |
| KayanOS Automations | ليست بيئة تشغيل عامة للتعبير | لا شيء مؤكد هنا | لا تلصق تعبير المنشئ إلا إذا وثق الحقل دعمه صراحة. |

## القيم الافتراضية للكيان

تستخدم القيم الافتراضية `$record` لا `$`. يقيّم الخادم القيمة الافتراضية المضبوطة فقط عندما تكون القيمة المقابلة غائبة أو فارغة.

```jexl theme={null}
$record.service_category == "urgent" ? "priority" : "standard"
```

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

## قواعد الكيان والتحقق

تشترك رؤية الحقل وقابليته للتعديل والتحقق المخصص في `$` و`$value` و`$relations` و`$member`، لكنها تستهلك النتائج بطرق مختلفة.

`$member` هو العضو الذي يحفظ السجل: `{ id }`، حيث `id` معرّف العضو المؤهَّل (`members:<id>`)، وهو الشكل نفسه الذي تخزّنه حقول الأعضاء. ويكون `{ id: null }` عندما لا يحفظ أي عضو، كما في مهام النظام. يقيّمه محرر السجل على أنه العضو المسجّل دخوله، ثم يعيد الخادم التحقق بالعضو الذي أرسل الطلب.

```jexl theme={null}
// لا يعدّل القرار إلا المراجع المعيّن
$.reviewer == $member.id
```

```jexl theme={null}
// الرؤية أو قابلية التعديل
$.requires_inspection == true

// التحقق المخصص
v.greaterThan($value, 0)
```

في حقل `text` أو`long_text` أو`rich_text` متعدد اللغات وغير مصفوفي، تعمل دوال التحقق التي يحذف منها وسيط القيمة—مثل `v.minLength(2)`—على كل نص محلي معبأ. يمنع أول فشل في أي لغة الحفظ في محرر السجل وفي تحقق الخادم. ويبقى `$value` الكائن المحلي الكامل عند الإشارة إليه صراحة في التعبير، لذلك لا تمرر هذا الكائن إلى دالة نصية وتفترض أنه يمثل لغة واحدة. اختبر كل لغة محفوظة وحالة فراغها كلها؛ لا تعوض قيمة إنكليزية صالحة قيمة عربية غير صالحة.

يعالج الخادم فشل تقييم شرط الرؤية بطريقة تختلف عن فشل قاعدة التعديل أو التحقق. لا تستخدم تعبيراً معطوباً كآلية سياسة، واختبر مسار الرؤية والتعديل والرفض كلّاً على حدة بسجل غير إنتاجي.

## الحقول المحسوبة: المعاينة ليست معالجة الخلفية

قد يعرض مسار الحساب التفاعلي/المتزامن `$value` وعلاقات مباشرة مهيأة وكائن علاقات عكسية فارغاً وقوالب حالات، وقد يكرر الحقول المحسوبة. تبدأ مهمة الخلفية ببيانات المصدر وتضيف التبعيات المحسوبة المحلية المكتشفة بصيغة `$.field_key` بعد تقييمها. تعرض العلاقات المباشرة والعكسية المهيأة فقط، ولا تعرض `$value` أو`$statusTemplates`، وتقيّم كل حقل مرة واحدة. تعمل الدورات والحقول المعتمدة عليها دون مفاتيح محسوبة؛ ولا تنشئ صيغة الأقواس تبعية محلية.

```jexl theme={null}
// قابل للنقل عندما تكون القيمتان حقول سجل عادية غير محسوبة
$.requested_amount * $.fee_rate
```

اختبر التبعيات المحسوبة بعد تحديث الخلفية، وتجنب الدورات، واضبط كل علاقة يحتاجها هذا المسار. راجع [الحقول المحسوبة](/ar/build/calculated-fields) لنموذج التنفيذ الكامل.

## سلوك الخطأ والقيمة الفارغة

| المستهلك | نتيجة النجاح | ما يجب تجنبه |
| - | - | - |
| تحقق حقل الكيان | `true` أو`null` أو`undefined` | إعادة كائن عرض لا يمثل خطأ محلياً. |
| تحقق النموذج | `true` أو`null` أو`undefined` أو`""` | افتراض أن خطأ التقييم سيمنع النموذج دائماً. |
| الرؤية/التعديل | تحويل منطقي | الاعتماد على بديل الخطأ لفرض قاعدة عمل. |
| حقل محسوب | أي قيمة معرّفة | اعتبار خطأ أو فراغ دليلاً على الصفر. |
| إدراج قالب | الشكل النصي للقيمة؛ null/undefined يصبحان فارغين | إخفاء قيمة عامة مفقودة بلا بديل. |

## متغيرات الجذر عقود بيانات لا أسماء مريحة

استخدم الجذر الذي يتيحه السياق فعلاً:

```jexl theme={null}
// قاعدة كيان
$.status == "received"

// قيمة افتراضية للكيان
$record.status == "received"

// قالب مستند
$record.status == "received"
```

لا يصبح التعبير الأول صالحاً تلقائياً كقيمة افتراضية أو قالب مستند. استخدم المحرر للمساعدة النحوية ثم تحقق من النتيجة في الميزة الفعلية.

## قائمة مراجعة

1. حدّد بيئة التنفيذ بدقة من الجدول.
2. تحقق من مفاتيح المصدر وأنواع البيانات بسجل آمن معلوم.
3. اختبر البيانات الفارغة والطبيعية والاستثنائية؛ وللنص المتعدد اللغات في الكيان اختبر كل لغة معبأة مستقلة.
4. للتواريخ اختبر حد المنطقة الزمنية المقصودة.
5. للبحث اختبر أقل بيانات صلاحية ولا تعرض حقولاً غير لازمة.
6. دوّن قرار السياسة خارج التعبير عندما يؤثر في الوصول أو الاعتماد أو التسليم العام.

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

* [بنية لغة التعبيرات](/ar/reference/expressions/language-syntax)
* [تعبيرات النماذج وعمليات البحث](/ar/reference/expressions/forms-and-lookups)
* [تعبيرات المعرّفات والترقيم](/ar/reference/expressions/serial-and-numbering)
* [سياق تعبير قالب المستند](/ar/reference/expressions/document-template-context)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.