> ## 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 واضحة وقابلة للاختبار بمرجع دقيق للقيم والمسارات والعوامل والقوالب والتحويلات وحدود التقييم.

## ابدأ بسياق التنفيذ

يعيد التعبير قيمة، ثم تقرر الميزة التي تقيّمه هل تصبح هذه القيمة حقلاً محسوباً أو قرار رؤية أو نتيجة تحقق أو نصاً في نموذج أو رقماً تسلسلياً أو مخرج مستند. لا يعني تشابه الكتابة أن التعبير صالح في كل مكان؛ فمتغيرات الجذر والدوال الخاصة بالسياق تختلف.

قبل كتابة أي تعبير، حدّد هذه الأمور الأربعة:

1. الميزة التي ستقيّمه: قيمة افتراضية للكيان، قاعدة كيان، حقل محسوب، نموذج، إعداد تسلسلي، أو قالب مستند.
2. مفتاح الحقل أو جذر السياق الفعلي، لا التسمية الظاهرة للمستخدم.
3. نوع النتيجة المطلوب: منطقي أو رقم أو نص أو تاريخ أو نتيجة تحقق أو قائمة.
4. السلوك المقصود عند غياب قيمة أو فشل بحث أو حدوث خطأ.

اقرأ [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts) قبل نقل تعبير عامل من ميزة إلى أخرى.

## القيم والمسارات

### القيم الحرفية

| القيمة      | المثال                              | الاستخدام                                             |
| ----------- | ----------------------------------- | ----------------------------------------------------- |
| نص          | `"received"` أو `'received'`        | اكتب قيم الخيارات والنصوص الثابتة بين علامات اقتباس.  |
| رقم         | `1250.5`                            | استخدم حقول الأرقام لمدخلات الحساب ما أمكن.           |
| منطقي       | `true` و`false`                     | للشروط والاختيارات الصريحة.                           |
| قيمة مفقودة | `null` و`undefined`                 | عالجها بوضوح؛ فهي ليست نصاً فارغاً.                   |
| قائمة       | `["normal", "urgent"]`              | مرّر مجموعة محلية إلى دالة أو اختبار انتماء.          |
| كائن        | `{ code: "CSR", priority: "high" }` | استخدمه بحذر للمنطق المحلي، ونمذج بيانات العمل كحقول. |

### قراءة قيمة

يأتي الجذر من السياق. تعرض قواعد الكيان السجل الحالي عادة في `$`، بينما تعرض قوالب المستند السجل في `$record`.

```jexl theme={null}
$.requested_amount
$record.request_id
```

استخدم النقطة للمفاتيح العادية والأقواس للفهرس أو المفتاح غير البسيط:

```jexl theme={null}
$.inspections[0].result
$.metadata["source-system"]
$record.attachments[0]
```

لا تخمّن المفتاح من عنوانه المترجم. يشير التعبير المتين إلى مفتاح الحقل الثابت المضبوط في المنشئ.

### ترشيح قائمة

تستخدم المرشحات النسبية `.` للدلالة على عنصر القائمة الجاري فحصه:

```jexl theme={null}
$.inspections[.result == "pass"]
$.inspections[.result == "pass"].scheduled_at
```

اعتبر النتيجة الفارغة حالة طبيعية، واختبرها قبل جعلها أساس قرار مهم:

```jexl theme={null}
isNotEmpty($.inspections[.result == "pass"])
```

## العوامل وأولوية التنفيذ

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

| الغرض              | البنية               | المثال                                             | المعنى وقت التشغيل                     |
| ------------------ | -------------------- | -------------------------------------------------- | -------------------------------------- |
| قيم أحادية         | `!` و`+` و`-`        | `!$.documents_complete`                            | نفي منطقي أو إشارة/تحويل رقمي          |
| الأس               | `**` و`^`            | `2 ** 3`                                           | كلاهما للأس، وليس `^` عملية بتية       |
| الباقي             | `%`                  | `$.sequence % 2`                                   | ينفذ قبل الضرب والقسمة                 |
| ضرب/قسمة           | `*` و`/` و`//`       | `17 // 5`                                          | `//` قسمة مقربة إلى الأسفل             |
| جمع/طرح            | `+` و`-`             | `$.base_fee + $.inspection_fee`                    | قد يصل `+` النصوص أيضاً                |
| مقارنة صارمة       | `==` و`!=`           | `$.status == "approved"`                           | مقارنة ثنائية صارمة؛ يجب تطابق الأنواع |
| سماحية رقمية       | `~=` و`!~=`          | `$.score ~= 7.5`                                   | ضمن/خارج `0.01`                        |
| مقارنة مرتبة       | `>` و`>=` و`<` و`<=` | `$.requested_days <= 30`                           | قارن قيماً متوافقة النوع               |
| انتماء             | `in`                 | `$.priority in ["high", "urgent"]`                 | يدعم القوائم والقيم المنظمة            |
| و باختصار التنفيذ  | `&&`                 | `$.owner_id && $.due_date`                         | لا يقيّم الجهة اليمنى إلا عند الحاجة   |
| أو باختصار التنفيذ | أو منطقي             | اسم مالك بديل                                      | يعيد أول فرع صالح                      |
| اختيار ثلاثي       | `? :`                | `$.priority == "urgent" ? "same-day" : "standard"` | يختار قيمة واحدة                       |

لصيغة بديلة، اكتب عامل «أو» المنطقي في كتلة تعبير بدلاً من وضع حرفي الأنبوب داخل خلية جدول Markdown:

```jexl theme={null}
$.owner_name || "Unassigned"
```

تستخدم الدالة `eq(left, right)` مساواة مرنة مقصودة، بينما لا يستخدم العامل الثنائي `==` ذلك. فضّل `==` لقيم الخيارات المخزنة، ولا تستخدم `eq` إلا إذا كان تحويل النوع جزءاً مقصوداً من السياسة.

### العوامل النصية `and` و`or` و`xor`

توجد العوامل النصية لتعبيرات التحقق، لكن سلوك رسائل التحقق فيها يختلف بين بيئة المنشئ المشتركة وبيئة قالب المستند. لذلك لا تعتمد عليها كطريقة متنقلة لتجميع أخطاء موجهة للمستخدم. للمنطق المنطقي أو القيمي العادي استخدم `&&` و`||`. ولتحقق الحقول استخدم [دوال التحقق](/ar/reference/expressions/helpers/validations) في سياق التحقق الفعلي واختبر الرسالة المعادة.

## الدوال وتحويلات الأنبوب

تتوفر لمعظم الدوال العامة صيغتان متكافئتان. تستقبل الدالة جميع الوسائط صراحة:

```jexl theme={null}
round($.requested_amount, 2)
```

أما التحويل فيستقبل القيمة إلى يسار `|` كوسيط أول:

```jexl theme={null}
$.requested_amount | round(2)
```

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

راجع المرجع الكامل بحسب المهمة:

* [دوال الرياضيات](/ar/reference/expressions/helpers/math) و[دوال النصوص](/ar/reference/expressions/helpers/string) و[دوال التاريخ والوقت](/ar/reference/expressions/helpers/date) و[دوال القوائم](/ar/reference/expressions/helpers/array)
* [دوال المقارنة والشروط](/ar/reference/expressions/helpers/operators) و[دوال التحويل العامة](/ar/reference/expressions/helpers/common)
* [دوال التحقق](/ar/reference/expressions/helpers/validations) و[البدائل القديمة](/ar/reference/expressions/helpers/aliases)
* [دوال النماذج ومرشحات البحث](/ar/reference/expressions/helpers/forms) و[الدوال التسلسلية](/ar/reference/expressions/helpers/serial) و[بحث قالب المستند](/ar/reference/expressions/helpers/document-templates)
* [دوال المشاريع](/ar/reference/expressions/helpers/project) و[دوال التخطيط](/ar/reference/expressions/helpers/planning)

## القوالب والقوائم والكائنات

تجمع القوالب بين العلامتين المائلتين نصاً ثابتاً وقيماً مقيمة. ضع التعبير داخل `{{` و`}}`:

```jexl theme={null}
`Request {{ $.request_id }} is assigned to {{ $.owner_name || "the service team" }}`
```

تتحول القيمة `null` أو `undefined` داخل القالب إلى نص فارغ. هذا يمنع ظهور كلمة `undefined` لكنه قد يخفي بيانات مفقودة؛ أضف بديلاً صريحاً لكل جملة عامة أو رسمية.

يمكنك إنشاء قائمة أو كائن صغيرين لمنطق محلي:

```jexl theme={null}
$.priority in ["high", "urgent"]
{ request_id: $.request_id, status: $.status }
```

ويمكن لبنية النشر الجمع بين قيمة منظمة وعنصر جديد:

```jexl theme={null}
[...$.selected_categories, "other"]
```

أبق هذه البنى محلية داخل التعبير. إذا احتاج الموظفون إلى البحث عن قيمة أو اعتمادها أو إعداد تقارير عنها أو تدقيقها، فاحفظها في حقل عادي.

## تعبيرات التحقق ليست شروطاً عادية

تعيد دوال التحقق `true` عند الصحة ونتيجة خطأ محلية عند الفشل. في سياق تحقق الحقل تستطيع دوال مثل `v.required()` تلقي قيمة الحقل الحالية تلقائياً عبر `$value`.

```jexl theme={null}
v.required() and v.minLength(3)
v.greaterThan($.requested_amount, 0)
```

لا تستهلك كيانات KayanOS والنماذج كل قيمة معادة بالطريقة نفسها. فالنموذج، مثلاً، يعد `true` و`null` و`undefined` والنص الفارغ صحيحة، وقد يعالج خطأ التقييم بصورة تختلف عن تحقق الكيان. راجع [دوال التحقق](/ar/reference/expressions/helpers/validations) و[سياقات التعبيرات](/ar/reference/expressions/contexts) قبل نشر قاعدة.

## الحتمية والتواريخ والاستخدام الآمن

تجنب `random` و`shuffle` و`sample` و`sampleSize` في التنسيقات التسلسلية أو الحقول المحسوبة المحفوظة أو القرارات القابلة للتدقيق. ولا تعتمد على الساعة الحية بلا سياسة تحديث: يمكن أن تتغير `now()` و`isToday` و`isTomorrow` و`isYesterday` و`getAge` من دون تعديل للسجل.

لا تستخدم كل دوال التاريخ نموذج منطقة زمنية واحداً. تستخدم بعض دوال التقويم معدلات التاريخ المحلية، بينما تستخدم `dateAdd` ومقارنة الوحدات واستخراج المكونات و`dateFormat` سلوكاً مائلاً إلى UTC. استخدم قيمة مصدر شبيهة بـ ISO، واذكر المنطقة الزمنية المقصودة في وصف الحقل، واختبر القيم حول منتصف الليل وحدود التوقيت الصيفي عند انطباقه.

تستخدم `dateFormat` الرموز `YYYY` و`MM` و`DD` و`HH` و`mm` و`ss` و`SSS`. وهي تختلف عن مفردات `serialDate` الأصغر (`yyyy` و`yy` و`MM` و`dd`).

## الاختبار واستكشاف الأخطاء

| العرض                    | افحص أولاً                                  | الاستجابة الآمنة                                           |
| ------------------------ | ------------------------------------------- | ---------------------------------------------------------- |
| نتيجة فارغة              | هل يتوفر هذا الجذر في الميزة؟               | قارن التعبير بجدول السياق واختبر سجلاً معروف البيانات.     |
| شرط دائماً false         | هل قيم الخيارات وأنواعها مطابقة؟            | استخدم `==` الصارم مع القيمة المخزنة لا التسمية المترجمة.  |
| `NaN` أو نص غير متوقع    | هل يحمل حقل رقم نصاً أو null؟               | افحص المصدر وحوّل أو ارفض الإدخال غير الصالح بوضوح.        |
| تحرك تاريخ يوماً         | هل توجد حدود محلية/UTC؟                     | اختبر قيمة ISO قريبة من منتصف الليل في المنطقة المستهدفة.  |
| المحرر أخضر والتنفيذ فشل | هل استُخدمت دالة خاصة بسياق آخر؟            | اعتبر حالة المحرر ملاحظة نحوية واختبر داخل الميزة الفعلية. |
| البحث لا يعيد شيئاً      | هل هذا بحث نموذج/قالب مع مرشح ووضع معتمدين؟ | افحص النطاق ومفاتيح المرشح والمهلة وسياسة كشف البيانات.    |

لا توفر KayanOS Automations بيئة تشغيل عامة لهذه اللغة في إعدادات المشغلات والإجراءات. استخدم هذا المرجع فقط حيث يذكر حقل منشئ KayanOS صراحة دعمه للتعبيرات.

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

* [التعبيرات في المنشئ](/ar/build/expressions-in-builder)
* [الحقول المحسوبة](/ar/build/calculated-fields)
* [النماذج والحقول والقوائم المتكررة](/ar/build/form-fields-and-repeatables)
* [المعرّفات التسلسلية](/ar/build/serial-ids)
* [قوالب المستندات](/ar/build/document-templates)

![بنية تعبير KayanOS في حقل المنشئ](https://kayanos.app/docs-images/ar/reference/expressions-language-syntax.png)