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

## استخدم التعبير لجعل القاعدة ظاهرة

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

من الاستخدامات المناسبة في المنشئ:

* حساب هدف الخدمة من تاريخ الاستلام والفئة والأولوية؛
* إظهار قسم شرطي فقط عندما يحتاج الطلب إلى معاينة؛
* التحقق من أن المبلغ موجب أو أن المرجع يطابق صيغة مطلوبة؛
* إنشاء سطر مقروء في مستند أو إشعار من حقول منظمة؛
* تلخيص قائمة مرتبطة لمراجع داخلي.

لا تستخدم تعبيراً لإخفاء قرار حرج أو لتجاوز اعتماد أو لوضع سر داخل قالب.

## اختر موضع القاعدة الصحيح

| الحاجة                       | الموضع الأفضل               | مثال                                 |
| ---------------------------- | --------------------------- | ------------------------------------ |
| عرض قيمة مشتقة من حقول       | حقل محسوب                   | رسم تقديري، أيام منقضية، تسمية مركبة |
| منع إدخال غير صالح           | تحقق الحقل                  | مرجع مطلوب، مدى قيمة مسموح           |
| إظهار أو إخفاء قسم           | شرط التخطيط أو النموذج      | إظهار تفاصيل المعاينة عند الحاجة فقط |
| إنشاء نص مقروء               | قالب مستند أو تعبير تسمية   | إقرار خدمة، عنوان حالة               |
| إيجاد بيانات نموذج مسموح بها | تعبير نموذج مع `getRecords` | إظهار تراخيص مؤهلة في نموذج موظف     |

ضع القاعدة قرب القرار الذي تدعمه. هدف الخدمة المحسوب يوضع قرب حقول الطلب، وعبارة المستند في قالب المستند، والبحث الحساس للصلاحيات في سياق النموذج المدعوم فقط.

## أنشئ حقلاً محسوباً خطوة بخطوة

### 1. عرّف النتيجة بلغة واضحة

اكتب لطلب ترخيص: «تاريخ الهدف بعد يومين من الاستلام للطلبات العاجلة وبعد سبعة أيام لبقية الطلبات».

### 2. تحقق من حقول المصدر

تحتاج إلى حقل تاريخ أو تاريخ ووقت مثل `received_at` وحقل مضبوط مثل `priority`. لا تعتمد على العنوان الظاهر إذا كان التعبير يحتاج إلى مفتاح الحقل.

### 3. اكتب أصغر تعبير

```txt theme={null}
$.priority == "urgent" ? addDays($.received_at, 2) : addDays($.received_at, 7)
```

### 4. اختبر السجلات الطبيعية والاستثنائية

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

## أربعة أنماط عملية

### حساب نتيجة رقمية

استخدم حقولاً عادية للمبالغ وحقلاً محسوباً للنتيجة النهائية القابلة للمراجعة.

```txt theme={null}
round(($.base_fee + $.inspection_fee) * $.multiplier, 2)
```

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

### إظهار قسم شرطي

استخدم شرطاً بسيطاً لتجنب سؤال المستخدم عن معلومات لا تخصه.

```txt theme={null}
$.requires_inspection.value == true
```

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

### التحقق من مرجع قبل الحفظ

تعيد تعبيرات التحقق `true` عند الصحة ورسالة محلية عند الخطأ.

```txt theme={null}
v.required() and v.matchRegex("^LIC-[0-9]+$")
```

في سياق تحقق الحقل تمرر قيمة الحقل الحالية تلقائياً عند حذف الوسيط الأول. اختبر مرجعاً صالحاً ومرجعاً فارغاً وقيمة ذات بادئة غير صحيحة.

### إنشاء جملة مستند مع بديل

استخدم قالباً نصياً لإنشاء نص مقروء من دون كشف البيانات المفقودة.

```txt theme={null}
`Request {{ $.serial_id }} is assigned to {{ $.owner.name || "the service team" }}`
```

احتفظ بالبيانات نفسها في الحقول؛ القالب للعرض وليس مصدر الحقيقة.

## اجعل التعبيرات قابلة للصيانة

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

## شخّص النتيجة قبل تغيير التعبير

| العرض                 | افحص أولاً                                              |
| --------------------- | ------------------------------------------------------- |
| قيمة محسوبة فارغة     | هل حقل المصدر متاح في سياق التعبير هذا؟                 |
| نص غير متوقع أو `NaN` | هل يقرأ الرقم كنص أو قيمة فارغة؟                        |
| الشرط لا يظهر أبداً   | هل يستخدم الخيار المضبوط القيمة المخزنة الدقيقة؟        |
| رسالة التحقق لا تظهر  | هل القاعدة مضبوطة كتحقق وهل تعيد `true` أو نتيجة خطأ؟   |
| القالب يخفي اسماً     | هل تعرض العلاقة الخاصية في هذا السياق وهل البديل مقصود؟ |

## الخطوات التالية

* اقرأ [بنية لغة التعبيرات الكاملة](/ar/reference/expressions/language-syntax).
* راجع كل [الدوال المسجلة](/ar/reference/expressions/helpers/math) مع توقيع ومثال.
* استخدم [حقول الكيانات وتخطيطاتها](/ar/build/entity-fields-and-layouts) لاختيار بيانات المصدر قبل كتابة القاعدة.

![منشئ تعبيرات KayanOS](https://kayanos.app/docs-images/ar/build/expressions-in-builder.png)