> ## 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.

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

> أنشئ قواعد نماذج واضحة وقوائم متكررة وفحوص واجهة وعمليات بحث مضبوطة من دون معاملة التعبير كأنه تفويض.

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

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

يوجد الكتالوج الكامل في [دوال النماذج ومرشحات البحث](/ar/reference/expressions/helpers/forms). يشرح هذا الدليل الاستخدام الآمن لهذه الدوال.

![إعدادات حقل نموذج KayanOS لاستقبال طلبات خدمات المواطنين، بما فيها عناصر التحكم في الرؤية والتكرار وتعبير التحقق.](https://kayanos.app/docs-images/ar/reference/expressions-forms-and-lookups.png)

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

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

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

```jexl theme={null}
$values.status == "submitted" && $values.request_amount > 1000
```

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

```jexl theme={null}
$siblings.requires_inspection.value == true
```

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

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

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

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

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

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

```jexl theme={null}
hasVerb("review") && $.service_category.value == "regulated"
```

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

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

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

وهذا يفرض ثلاثة حدود واضحة:

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

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

```jexl theme={null}
getRecords("licenses", f.and(
  f.eq("status", "approved"),
  f.eq("holder_id", $.applicant_id.value)
))
```

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

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

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

```jexl theme={null}
f.and(
  f.eq("status", "approved"),
  f.gte("score", 80),
  f._in("district", ["central", "north"])
)
```

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

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

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

```jexl theme={null}
isWeekday($.appointment_date.value, $.assigned_position_id.value)
```

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

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

```jexl theme={null}
$.requires_inspection.value == true && isNotEmpty($.site_address.value)
```

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

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

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

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

* [النماذج والحقول والقوائم المتكررة](/ar/build/form-fields-and-repeatables)
* [إجراءات النموذج ومنطقه وتوقيعاته](/ar/build/form-actions-logic-and-signatures)
* [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts)