تعبيرات النماذج وعمليات البحث

متى تستخدم تعبيرات النموذج

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

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

جذور النموذج

الجذر	المعنى
`$this`	العقدة التي تقيّم التعبير حالياً.
`$form`	كائن النموذج المعروض.
`$values`	المتغيرات وإجابات الحقول الخام في شجرة قيم واحدة ومتسقة. استخدم هذا الجذر في التعبيرات الجديدة.
`$`	متغيرات النموذج مباشرةً، مع كائنات الأبناء المكشوفة. اقرأ إجابة الحقل من الخاصية `.value`.
`$parent` و`$siblings` و`$grandparent` و`$uncles`	عقد قريبة في بنية النموذج.
`$repeatables` و`$repeatable_instances`	حاويات التكرار وخريطة الحالة الحالية.
`$index` و`$item`	فهرس عنصر الحلقة الحالي ومصدره، ويعود `$index` إلى `0`.
`$value` و`$defaultValue`	قيمة الحقل الحالية وقيمته الافتراضية المضبوطة.
معرّفات المنظمة/النموذج/الجلسة/البادئ/العضو	معرّفات مؤهلة للنموذج والجلسة والعضو النشط.
`currentUserType`	`"public"` أو`"member"` أو لا قيمة.

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

$values.status == "submitted" && $values.request_amount > 1000

تبقى التعبيرات القديمة مثل $.status و$.request_amount.value مدعومة، ويقترح محرر التعبيرات بدائلها باستخدام $values.

$siblings.requires_inspection.value == true

أنماط القوائم المتكررة

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

`Inspection {{ $index + 1 }}: {{ $item.site_name || "site not supplied" }}`

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

فحوص الواجهة ليست تفويضاً

تستطيع hasVerb وhasVerbOnRecord وhasScope وhasAnyScope تكييف ما يراه العضو في النموذج، لكنها لا تمنح صلاحية. تعيد دوال الفعل true أثناء تقييم الخادم، لذلك لا يمكن أن تكون تعبيراتك التي تستخدمها وسيلة الإنفاذ الوحيدة.

hasVerb("review") && $.service_category.value == "regulated"

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

البحث عن السجلات: اجعله ضيقاً وخاصاً وغير مخوّل

getRecord وgetRecords دالتا بيانات مريحتان للنموذج. قد تعيدان نتيجة فارغة/شبيهة بـ null عندما لا يتوفر سياق النموذج أو تنتهي مهلة البحث. يعمل البحث الخلفي عبر مسار بيانات على مستوى النظام؛ فهو لا يرشح النتيجة وفق صلاحيات السجل أو الحقل العادية للمشارك الحالي أو دوره أو نطاقه. وليس له وسيط يحد عدد نتائج البحث، لذلك قد يحمل المرشح الواسع كل السجلات المطابقة. وهذا يفرض ثلاثة حدود واضحة:

يمكن لـ hasVerb* وhasScope* تغيير العرض فقط؛ ولا يخوّلان إجراءً.
لا يجوز أبداً أن تقرر getRecord وgetRecords ما إذا كان المشارك مخولاً أو مستحقاً للبيانات.
لا يجوز عرض نتيجة البحث لمشارك عام أو غير مخول. ليس الحقل المخفي آلية تحكم بالوصول.

استخدم مرشحاً انتقائياً على كيان وحقول صُممت عمداً لهذا الغرض، وتعامل بأمان مع غياب النتيجة:

getRecords("licenses", f.and(
  f.eq("status", "approved"),
  f.eq("holder_id", $.applicant_id.value)
))

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

بناء المرشحات بـ `f.`

تبني دوال f. كائن مرشح قاعدة بيانات لـgetRecords، ولا ترشح قائمة عشوائية في الذاكرة. النمط الأوضح هو اقتران صغير:

f.and(
  f.eq("status", "approved"),
  f.gte("score", 80),
  f._in("district", ["central", "north"])
)

استخدم f._in عندما تحتاج دالة انتماء مقروءة لا لبس فيها. اختبر مفاتيح الحقول وقيم الخيارات المخزنة بدقة، ولا تنشئ بحثاً واسعاً ثم تخفي النتائج بتعبير لاحق.

أيام العمل ومناوبات الخدمة

يمكن أن تستخدم isWeekend(date, entityId?) وisWeekday(date, entityId?) أيام العمل المضبوطة للمناوبة عند توافر كيان وبيانات خدمة مناسبين. وعند غياب تلك البيانات تعودان إلى السبت/الأحد. اعتبرهما دالتين للنموذج العادي المتصل واختبر جدول المنظمة المستهدفة.

isWeekday($.appointment_date.value, $.assigned_position_id.value)

حدود النموذج غير المتصل

تحظر النماذج غير المتصلة getRecord وgetRecords وhasVerbOnRecord وhasVerb وhasScope وhasAnyScope، كما تقيد ميزات نموذج مدعومة بالبيانات. اجعل تعبيرات النموذج غير المتصل ذاتية الاكتفاء: قيم الحقول والشروط البسيطة والدوال العامة الحتمية.

$.requires_inspection.value == true && isNotEmpty($.site_address.value)

تحقق من النموذج غير المتصل قبل نشره. لا تعتمد على دالة يقترحها المحرر إذا كان مدقق العمل غير المتصل يحظرها.

مصفوفة الاختبار

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

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

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

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

تعبيرات النماذج وعمليات البحث

متى تستخدم تعبيرات النموذج

جذور النموذج

أنماط القوائم المتكررة

فحوص الواجهة ليست تفويضاً

البحث عن السجلات: اجعله ضيقاً وخاصاً وغير مخوّل

بناء المرشحات بـ `f.`

أيام العمل ومناوبات الخدمة

حدود النموذج غير المتصل

مصفوفة الاختبار

أدلة ذات صلة

​متى تستخدم تعبيرات النموذج

​جذور النموذج

​أنماط القوائم المتكررة

​فحوص الواجهة ليست تفويضاً

​البحث عن السجلات: اجعله ضيقاً وخاصاً وغير مخوّل

​بناء المرشحات بـ f.

​أيام العمل ومناوبات الخدمة

​حدود النموذج غير المتصل

​مصفوفة الاختبار

​أدلة ذات صلة

متى تستخدم تعبيرات النموذج

جذور النموذج

أنماط القوائم المتكررة

فحوص الواجهة ليست تفويضاً

البحث عن السجلات: اجعله ضيقاً وخاصاً وغير مخوّل

بناء المرشحات بـ `f.`

أيام العمل ومناوبات الخدمة

حدود النموذج غير المتصل

مصفوفة الاختبار

أدلة ذات صلة