بنية لغة التعبيرات

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

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

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

اقرأ سياقات وتوافر التعبيرات قبل نقل تعبير عامل من ميزة إلى أخرى.

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

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

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

قراءة قيمة

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

$.requested_amount
$record.request_id

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

$.inspections[0].result
$.metadata["source-system"]
$record.attachments[0]

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

ترشيح قائمة

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

$.inspections[.result == "pass"]
$.inspections[.result == "pass"].scheduled_at

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

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:

$.owner_name || "Unassigned"

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

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

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

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

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

round($.requested_amount, 2)

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

$.requested_amount | round(2)

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

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

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

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

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

$.priority in ["high", "urgent"]
{ request_id: $.request_id, status: $.status }

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

[...$.selected_categories, "other"]

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

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

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

v.required() and v.minLength(3)
v.greaterThan($.requested_amount, 0)

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

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

تجنب 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 صراحة دعمه للتعبيرات.

أدلة ذات صلة

لغة التعبيرات

مرجع دوال التعبيرات

المرجع العملي

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

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

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

قراءة قيمة

ترشيح قائمة

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

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

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

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

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

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

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

أدلة ذات صلة

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

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

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

​قراءة قيمة

​ترشيح قائمة

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

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

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

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

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

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

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

​أدلة ذات صلة

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

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

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

قراءة قيمة

ترشيح قائمة

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

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

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

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

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

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

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

أدلة ذات صلة