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

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

تستخدم الأمثلة مديرية خدمات عامة سورية تتلقى طلب خدمة من مواطن وقد يحتاج إلى معاينة ميدانية أو عدة مواد داعمة. مفاتيح الحقول في الأمثلة للتوضيح فقط. استبدلها بمفاتيح النموذج الفعلية قبل النشر؛ فالعناوين المترجمة ليست مفاتيح للتعبيرات.

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

![إعدادات القسم المتكرر لعمليات المعاينة في KayanOS بنمط تحكم المستخدم لنموذج استقبال طلبات خدمات المواطنين.](https://kayanos.app/docs-images/ar/build/form-fields-and-repeatables.png)

## متى تستخدمه

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

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

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

اختر حقلاً عادياً بدلاً من القيمة المحسوبة عندما يجب على شخص إدخال القيمة أو تصحيحها. الحقل من النوع `calculated_value` قيمة مشتقة يضبطها المنشئ: يفرض عليه النظام أن يكون مخفياً وغير مطلوب وغير قابل للتحرير وغير قابل للتكرار. لذلك ليس مربع إجابة قابل للتحرير. استخدم حقل كيان محسوباً عندما تنتمي النتيجة إلى سجل الكيان بعد جلسة النموذج؛ راجع [الحقول المحسوبة](/ar/build/calculated-fields) لهذه الإمكانية المنفصلة.

## الإعداد

### اختيار أصغر نوع حقل صحيح

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

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

### أمثلة كل حقل ولقطات أداة الإنشاء

تظهر اللقطات الفعلية الآتية النوع المختار من قائمة أنواع الحقول. استخدم المفتاح الثابت في الأمثلة؛ فالعنوان المترجم مخصص للبشر، بينما المفتاح هو ما تقرأه الشروط والقيم الافتراضية.

#### نص

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

![ضبط حقل نص في نموذج KayanOS لاسم مقدم الطلب.](https://kayanos.app/docs-images/ar/build/form-fields/text-settings.png)

#### رقم

استخدم `household_members` لعدد ذي وحدة محددة. اضبط التحقق كعدد صحيح موجب عندما لا يمكن للخدمة الاستمرار بصفر؛ واستخدم المبلغ عندما تمثل القيمة عملة.

![ضبط حقل رقم في نموذج KayanOS لعدد أفراد الأسرة.](https://kayanos.app/docs-images/ar/build/form-fields/number-settings.png)

#### تاريخ

استخدم `requested_visit_date` عندما يحتاج الطلب إلى يوم من دون ساعة محددة. ويمكن لموعد لاحق أن يستخدم تاريخاً ووقتاً منفصلين لتمييز اليوم المطلوب عن الوقت المؤكد.

![ضبط حقل تاريخ في نموذج KayanOS لتاريخ زيارة مطلوب.](https://kayanos.app/docs-images/ar/build/form-fields/date-settings.png)

#### تاريخ ووقت

استخدم `appointment_time` لموعد معاينة أو خدمة مؤكد. اذكر منطقة زمن المكتب في الوصف عندما تعمل فرق مركزية ومحلية في مواقع مختلفة.

![ضبط حقل تاريخ ووقت في نموذج KayanOS لموعد.](https://kayanos.app/docs-images/ar/build/form-fields/date-time-settings.png)

#### وقت

استخدم `preferred_contact_time` لتفضيل متكرر لوقت اليوم. لا تجعله المدخل الوحيد للموعد لأنه لا يحمل تاريخاً تقويمياً.

![ضبط حقل وقت في نموذج KayanOS لوقت اتصال مفضل.](https://kayanos.app/docs-images/ar/build/form-fields/time-settings.png)

#### منطقي

استخدم `requires_site_visit` لقرار واحد لا لبس فيه. يمكن لقسم تابع أن يستخدم الشرط `$.requires_site_visit.value == true` عندما تكون القيمة المنطقية ذات بداية موثقة وقد اختبر كل مسار.

![ضبط حقل منطقي في نموذج KayanOS لقرار زيارة ميدانية.](https://kayanos.app/docs-images/ar/build/form-fields/boolean-settings.png)

#### مبلغ

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

![ضبط حقل مبلغ في نموذج KayanOS لرسم خدمة تقديري.](https://kayanos.app/docs-images/ar/build/form-fields/money-settings.png)

#### نص متعدد الأسطر

استخدم `service_details` لشرح عادي متعدد الأسطر بكلمات مقدم الطلب. افصل الوقائع العملية مثل العنوان والفئة والتاريخ المطلوب إلى حقول مستقلة كي تبقى قابلة للبحث والمراجعة.

![ضبط حقل نص متعدد الأسطر في نموذج KayanOS لتفاصيل خدمة.](https://kayanos.app/docs-images/ar/build/form-fields/textarea-settings.png)

#### نص منسق

استخدم `review_narrative` لسرد يحرره الموظف ويحتاج فعلاً إلى عناوين أو قوائم. لا تعتمد على التنسيق لتمثيل قرار أو حالة أو مالك أو مبلغ مضبوط.

![ضبط محرر نص منسق في نموذج KayanOS لسرد مراجعة.](https://kayanos.app/docs-images/ar/build/form-fields/rich-editor-settings.png)

#### اختيار مفرد

استخدم `service_category` بقيم ثابتة مثل `civil_registration` و`municipal_service` و`site_inspection`. تقارن الشروط القيمة المخزنة مثل `$.service_category.value == "site_inspection"`، لا عنوان الخيار المترجم.

![ضبط حقل اختيار مفرد في نموذج KayanOS لفئة خدمة.](https://kayanos.app/docs-images/ar/build/form-fields/single-select-settings.png)

#### اختيار كيان

استخدم `assigned_case` في مسار الموظفين فقط حيث يعرف الكيان المصدر والمرشح المعتمدان. تحقق من سلوك البحث على مستوى المنظمة ولا تعرض محدد سجلات داخلياً قابلاً للتصفح في نموذج مواطن عام.

![ضبط حقل اختيار كيان في نموذج KayanOS لحالة معينة.](https://kayanos.app/docs-images/ar/build/form-fields/entity-select-settings.png)

#### اختيار جلسة نموذج

استخدم `related_application` عندما يجب على المراجع ربط النموذج بجلسة التقطت سابقاً. قيد النموذج المصدر واختبر غياب النتائج والبحث وحالة الجلسة المختارة قبل النشر.

![ضبط حقل اختيار جلسة نموذج في KayanOS لطلب مرتبط.](https://kayanos.app/docs-images/ar/build/form-fields/form-session-select-settings.png)

#### ملف

استخدم `supporting_evidence` لمستند أو صورة تتبع قاعدة دليل واحدة. فعّل متعدد فقط عندما يكون لكل ملف الغرض والسياسة نفسيهما؛ وإلا ضع الملف وبياناته في قسم مكرر.

![ضبط حقل ملف في نموذج KayanOS لدليل داعم.](https://kayanos.app/docs-images/ar/build/form-fields/file-settings.png)

#### موقع

استخدم `service_location` عندما يؤثر العنوان أو موضع الخريطة في التقديم أو التوجيه أو المعاينة. اشرح الدقة التي تحتاجها الخدمة ولا تطلب إحداثيات عندما تكفي منطقة أو مركز خدمة.

![ضبط حقل موقع في نموذج KayanOS لموقع خدمة.](https://kayanos.app/docs-images/ar/build/form-fields/location-settings.png)

#### قيمة محسوبة

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

![ضبط قيمة محسوبة في نموذج KayanOS لمؤشر جاهزية الزيارة.](https://kayanos.app/docs-images/ar/build/form-fields/calculated-value-settings.png)

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

### ضبط حقلي الاختيار والملف عن قصد

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

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

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

### اضبط وصول المحددات إلى البيانات عمداً

محدد الكيان عملية بحث عن بيانات، وليس مجرد قائمة اختيار مريحة. مستوى الوصول الافتراضي لمحدد الكيان هو `all`، ولذلك تُقرأ خياراته عبر مسار بيانات على مستوى النظام في المنظمة. استخدم `user_permissions` فقط عندما يعمل النموذج لعضو محدد وتحتاج الخدمة فعلاً إلى أن يحترم المحدد وصول ذلك العضو العادي إلى السجلات. اختبر العضو والدور والنطاق الفعليين، وحالة عدم وجود نتائج، وحالة قيمة مختارة، وحالة البحث. يمكن لمرشح الكيان أن يبقي القائمة مركزة — مثل قصرها على حالات المعاينة المفتوحة في المنطقة الحالية — لكنه **لا** يحول بحثاً على مستوى النظام إلى حد تفويض.

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

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

لكل إدخال أيضاً أربعة قرارات للسلوك يمكن ضبطها كمفتاح بسيط أو كتعبير يتحقق منه المنشئ في سياقه:

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

يتحقق المنشئ من هذه التعبيرات في السياق المتاح. اجعل الشرط محدوداً، واذكر الحقل المؤثر في العنوان أو المساعدة عندما يغير ما يراه المواطن. المثال الآتي للتوضيح؛ فهو يظهر قسم المعاينة عندما يكون المفتاح الفعلي `requires_site_visit` صحيحاً:

```jexl theme={null}
$.requires_site_visit.value == true
```

يمكن أن يكون عدد الصفوف الثابت شرطياً كذلك. ينشئ المثال الآتي صفين للمواد عندما تكون القيمة المخزنة الفعلية لنوع الطلب `multi_site`، وصفاً واحداً في غير ذلك. تحقق من قيمة الخيار المنشورة، ولا تنسخ عنوان الخيار المعروض إلى التعبير.

```jexl theme={null}
$.request_type.value == 'multi_site' ? 2 : 1
```

### بناء حقل أو قسم متكرر

افتح إعدادات الحقل أو القسم وفعل التكرار. امنح المكرر عنواناً واضحاً، ثم اختر واحداً من الأنماط الثلاثة. تقبل إعدادات **العدد** و**الحد الأدنى** و**الحد الأقصى** و**عناصر الحلقة** قيمة ثابتة أو تعبيراً يحل في سياق المكرر. أما **العدد الأولي فيجب أن يكون رقماً ثابتاً**: فوقت التشغيل الحالي يحوله بواسطة `Number(...)` ولا يقيمه كتعبير، لذلك لا تضع JEXL في هذا الإعداد. وبالنسبة إلى الصفوف التي يتحكم بها المستخدم، ضع حداً أقصى صريحاً تملكه الخدمة بدلاً من الاعتماد على القيمة الاحتياطية `9999` عند غياب الحد.

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

![إعداد صفوف جدول متكررة يتحكم بها المستخدم في KayanOS بحد أدنى واحد وأقصى ثلاثة وعدد أولي واحد.](https://kayanos.app/docs-images/ar/build/form-repeaters/user-controlled-table-rows.png)

| النمط            | سلوك وقت التشغيل                                                                                                                                                                            | اختره عندما                                                                   | تجنبه عندما                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `fixedCount`     | يصبح العدد المضبوط هو الحد الأدنى والحد الأقصى معاً، ولا يستطيع المستخدم الإضافة أو الحذف.                                                                                                  | يجب أن يعرض كل طلب العدد نفسه من الصفوف، مثل جهتي تحقق مطلوبتين دائماً.       | كان العدد يتوقف على اختيار المستخدم أو بيانات مصدر.           |
| `userControlled` | يضيف المستخدم المثيلات ويحذفها ضمن الحدين الأدنى والأقصى، ويحدد العدد الأولي الصفوف الظاهرة عند الفتح.                                                                                      | يعرف المواطن أو الموظف كم عنصراً يريد تقديمه، مثل مادة داعمة واحدة إلى خمس.   | كان يجب أن تطابق القائمة مصدراً مضبوطاً أو قائمة أخرى تماماً. |
| `loop`           | تقود الصفوف مباشرة المصفوفة التي يعيدها تعبير عناصر الحلقة؛ فعدد الصفوف الفعلي هو طول تلك المصفوفة. تحمل البنية أيضاً قيماً احتياطية للحدين صفر و`9999`، لكنها لا تضع سقفاً لمصفوفة الحلقة. | كان يجب أن تعكس الصفوف بيانات مصفوفة معروفة، مثل مواد معتمدة جهزت في النموذج. | كان على الشخص إضافة الصفوف أو حذفها بحرية.                    |

لمجموعة صفوف ثابتة، تستبدل اللوحة الحدود بعدد واحد. يناسب ذلك فحصي مواد إلزاميين بالضبط، لا عدداً متغيراً من المعاينات.

![إعداد جدول متكرر بعدد ثابت اثنين في KayanOS.](https://kayanos.app/docs-images/ar/build/form-repeaters/fixed-count-table-rows.png)

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

في نمط الحلقة، يجب أن يعيد تعبير عناصر الحلقة المصفوفة التي تقود الصفوف. يفترض المثال الآتي للتوضيح أن حقلاً سابقاً يخزن مصفوفة تحت المفتاح `approved_materials`. يرتبط كل صف بالمادة في تلك المصفوفة بدلاً من اختيار عدد يدوي للصفوف.

```jexl theme={null}
$.approved_materials.value
```

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

![إعداد مكرر حلقي في KayanOS يعرض محرر تعبير عناصر الحلقة.](https://kayanos.app/docs-images/ar/build/form-repeaters/loop-items-expression.png)

عند الحفظ، تحفظ المكررات كمصفوفة من قيم المثيلات. كما يظهر للمستخدم في الجلسة عدد `requestedRepeat` ومجموعة `instances`. أما الصفوف المقادة بالحلقة فيكتب وقت التشغيل عنصر المصدر تحت المفتاح `@loop_item` في كل مثيل محفوظ إلى جانب قيم ذلك الصف. اعتبر قيمة المصدر هذه أثراً للمادة التي أنشأت الصف، لا حقلاً يدخله المستخدم أو يعدله يدوياً.

### قراءة قيم المكرر وعرضها وتصديرها

يوجد شكلان مترابطان يجب فهمهما. أثناء تشغيل النموذج، يكون الحقل العادي كائن حقل مكشوف، ولذلك تقرأ إجابته عبر `.value`. والمكرر نفسه كائن مكشوف أيضاً: استخدم مجموعة `.instances`، ثم استخدم `.value` للحقل المكرر أو `.children.<field_key>.value` لابن داخل قسم مكرر. لا يغير التخطيط الجدولي طريقة العرض، لا شكل القيمة المحفوظة.

استخدم **مكرر حقل** باسم `attachment_references` عندما يحتاج التقديم إلى عدة قيم من النوع نفسه تماماً. اقرأ صفاً معروفاً بفهرسه الصفري:

```jexl theme={null}
$.attachment_references.instances[0].value
```

لعرض كل المراجع المدخلة في حقل محسوب أو كتلة نص أو عنوان إجراء واحد، استخرج قيمة كل صف واجمعها. تكون النتيجة نصاً مقروءاً واحداً مثل `EVD-001, EVD-002`.

```jexl theme={null}
$.attachment_references.instances | getByPath("value") | join(", ")
```

استخدم **مكرر قسم** باسم `inspection_rows` عندما يحمل كل صف إجابات مترابطة. اقرأ حقلاً من أول معاينة كما يأتي:

```jexl theme={null}
$.inspection_rows.instances[0].children.inspection_outcome.value
```

يمكنك جمع الصفوف ذات النتيجة المضبوطة فقط، ثم عرض كل النتائج أو التواريخ كقائمة. تعمل هذه التعبيرات على مثيلات وقت تشغيل النموذج، لذا يحتاج الحقل الابن إلى `.value` كذلك.

```jexl theme={null}
$.inspection_rows.instances[.children.inspection_outcome.value == "unsafe"]
```

```jexl theme={null}
$.inspection_rows.instances | getByPath("children.inspection_outcome.value") | join(", ")
```

```jexl theme={null}
$.inspection_rows.instances | getByPath("children.visit_date.value") | join(", ")
```

لا تستخدم نص العرض كسجل النظام. عند الحفظ، يخزن `saved_state` قيم العمل كمصفوفات وكائنات مباشرة؛ ولا يخزن المغلفات الخاصة بوقت التشغيل `.instances` أو `.children`. يحفظ مكرر الحقل مصفوفة بسيطة، بينما يحفظ مكرر القسم أو الجدول كائناً واحداً لكل صف. ويحتفظ الصف المقاد بالحلقة أيضاً بعنصر مصدره تحت `@loop_item` كي يستطيع المراجع تتبع كيفية إنشاء الصف.

```json theme={null}
{
  "attachment_references": ["EVD-001", "EVD-002"],
  "inspection_rows": [
    {
      "visit_date": "2026-07-20",
      "inspection_outcome": "unsafe",
      "inspection_notes": "Repair the entrance ramp before approval."
    },
    {
      "visit_date": "2026-07-23",
      "inspection_outcome": "safe",
      "inspection_notes": "Corrective work verified."
    }
  ],
  "material_rows": [
    {
      "material": "Accessibility ramp",
      "quantity": 1,
      "@loop_item": { "material_code": "RAMP-01" }
    }
  ]
}
```

يفيد هذا الفرق عند تصميم قالب مستند أو حمولة أتمتة أو تحديث كيان بعد الإرسال: استخدم هناك المصفوفات وكائنات الصفوف المحفوظة مباشرة. أما `.instances` و`.children` و`.value` فتستخدم فقط داخل سياق تعبير النموذج الحي. وإذا احتاجت عملية لاحقة إلى قائمة جاهزة للعرض، فاستخدم تحويل `getByPath("path")` المسجل عمداً بدلاً من تسطيح البيانات المقدمة وفقدان حدود الصفوف.

### التخطيط الجدولي والصفوف المتداخلة

يمكن للقسم المتكرر أن يستخدم تخطيط `section` أو تخطيط `table`. يعطي تخطيط القسم كل مثيل كتلة مستقلة، وهو أسهل للسرد الطويل أو الملفات أو المحتوى الشرطي. يعرض تخطيط الجدول الحقول والإجراءات وكتل النص الأبناء كأعمدة، وهو أنسب للصفوف المقارنة الصغيرة مثل المادة والكمية والوحدة ونتيجة التحقق.

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

![إعداد تخطيط جدول في KayanOS لصفوف معاينة قابلة للمقارنة.](https://kayanos.app/docs-images/ar/build/form-repeaters/table-layout-settings.png)

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

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

## مثال عملي

تتلقى مديرية خدمات عامة سورية طلبات لخدمة محلية. يسجل موظف الاستقبال فئة الخدمة، ثم يسجل المعاينات الميدانية عند الحاجة. يريد مالك الخدمة أن يقارن الموظفون نتائج المعاينات بسرعة، مع بقاء كل ملاحظة وملف وموقع تابعاً للزيارة التي تخصه.

أنشئ أولاً الحقول غير المتكررة: `request_type` كحقل اختيار، و`requires_site_visit` كحقل منطقي، و`citizen_contact_reference` كنص، و`requested_service_date` كتاريخ. استخدم قيم اختيار مضبوطة لـ `request_type` لأن الشروط اللاحقة تعتمد عليها. أضف قسماً اسمه `inspection_rows` بعنوان واضح مثل «المعاينات الميدانية». واجعل شرط ظهوره هو التعبير الأول في هذا الدليل. ضع داخله `visit_date` كتاريخ، و`visit_location` كموقع، و`inspection_outcome` كاختيار، و`inspection_notes` كنص متعدد الأسطر، و`evidence_file` كملف. إذا كانت ملفات كل معاينة تتبع القاعدة نفسها، فعّل متعدد في `evidence_file`؛ وإذا كان على الموظف تصنيف كل ملف أو تقييمه بصورة مستقلة فأضف قسم أدلة مكرراً محدوداً مع بيانات الملف الوصفية.

اختر `userControlled` للقسم `inspection_rows`. ضع حداً أدنى معتمداً مقداره `1` فقط عندما تكون الزيارة مطلوبة دائماً، وعدداً أولياً `1` ليظهر الصف الأول المتوقع، وحداً أقصى متواضعاً مثل `3` عندما تسمح السياسة بثلاث زيارات مسجلة كحد أقصى لكل طلب. يستطيع المستخدم إضافة الزيارة الثانية أو الثالثة ضمن هذا النطاق فقط. لا تستخدم العدد الثابت عندما يختلف عدد الزيارات، ولا نمط الحلقة عندما يجب أن يقرر الموظف الحاجة إلى زيارة إضافية.

أنشئ قسماً ثانياً باسم `material_rows` للتحقق من المواد. إذا كان يجب دائماً عرض فحصين مطلوبين للمواد، استخدم `fixedCount` بالعدد `2`. وإذا استلم المكتب مصفوفة معتمدة مسبقاً لمتطلبات المواد، استخدم `loop` واجعل `repeatable_loop_items` يشير إلى تلك المصفوفة. اشرح في عنوان صف الحلقة أنه مشتق من قائمة المواد المعتمدة؛ فالقيمة المحفوظة `@loop_item` تجعل العلاقة قابلة للمراجعة بعد الحفظ.

استخدم التخطيط الجدولي لـ `material_rows` فقط إذا كانت أبناؤه قصيرة: نوع المادة والكمية والوحدة وحالة التحقق. اختر سلوك الهاتف `hybrid` أولاً واختبره في شاشة ضيقة. وأبق `inspection_rows` كتخطيط قسم لأن الملاحظات وملفات الأدلة تحتاج إلى مساحة وسياق.

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

## الاختبار

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

| الاختبار                     | الإعداد                                                                                                                  | النتيجة المتوقعة                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| نوع الحقل                    | أدخل قيمة مناسبة لكل نوع مضبوط                                                                                           | يقبل الحقل قيمته المقصودة وتبقى النتيجة المحفوظة مفهومة للمراجع.                                                |
| القيمة الافتراضية            | افتح جلسة جديدة دون لمس الحقل                                                                                            | تظهر القيمة المضبوطة، ولا تتغير إلا عندما يحرر المستخدم حقلاً قابلاً للتحرير.                                   |
| شرط المطلوب والظهور والتحرير | اختبر جانبي كل تعبير                                                                                                     | يصبح الحقل مطلوباً أو ظاهراً أو قابلاً للتحرير فقط عندما يتحقق الشرط المضبوط.                                   |
| التحقق                       | أدخل قيمة مسموحة وأخرى مرفوضة                                                                                            | تمنع القيمة المرفوضة الإكمال الصحيح مع مسار تصحيح مفهوم.                                                        |
| نمط ومصدر الاختيار           | اختبر القيم المفردة والمتعددة، ثم الخيارات اليدوية أو المأخوذة من كيان عندما تتاح أو خيارات الشيفرة التي تستخدمها الخدمة | تبقى قيم الخيارات المخزنة ثابتة، ويحفظ الاختيار المتعدد مصفوفة وتختبر الشروط مع صفر واختيار واحد وعدة اختيارات. |
| ملفات متعددة                 | ارفع ملفاً واحداً وعدة ملفات متجانسة بحقل ملف مفعل له متعدد                                                              | يتبع كل ملف قاعدة النوع والحجم المضبوطة من دون إنشاء صف مكرر غير لازم.                                          |
| العدد الثابت                 | اضبط العدد `2`                                                                                                           | تظهر مثيلان تماماً ولا تغير الإضافة أو الحذف العدد.                                                             |
| تحكم المستخدم                | اضبط الحد الأدنى `1` والأقصى `3` والأولي `1`                                                                             | يضيف المستخدم الصفوف ويحذفها ضمن الحدود فقط.                                                                    |
| الحلقة                       | أعد مصفوفة بعنصرين معروفين                                                                                               | تظهر مثيلان مقادان وتحفظ كل خانة مع قيمة `@loop_item` المطابقة.                                                 |
| جدول الهاتف                  | اختبر `hybrid` و`scroll` في شاشة ضيقة                                                                                    | تبقى العناوين والخلايا والإجراءات قابلة للاستخدام من دون إخفاء معلومات أساسية.                                  |
| مراجعة التداخل               | استخدم أكبر أعداد مسموحة في المستويين                                                                                    | يستطيع المراجع تمييز الصفوف ويبقى الأداء مناسباً للاستخدام المعتمد.                                             |

بالنسبة إلى الحد الأقصى المبني على تعبير، اختبر أصغر وأكبر قيمة متوقعة ومدخلاً مفقوداً. يفترض المثال الآتي للتوضيح أن `risk_level` قيمة اختيار فعلية؛ استبدله بمفتاح الخدمة وقيم خياراتها.

```jexl theme={null}
$.risk_level.value == 'high' ? 3 : 1
```

## استكشاف الأخطاء وإصلاحها

| العرض                                | افحص أولاً                                                                                                                      | الاستجابة الآمنة                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| يظهر خطأ في شرط                      | هل يوجد كل مفتاح مشار إليه في سياق النموذج، وهل تطابق قيم الاختيار قيمها المخزنة؟                                               | ابدأ بشرط بسيط، وتحقق منه، ثم أضف اعتماداً واحداً في كل مرة.                                       |
| تبدو القيمة المحسوبة كحقل إدخال      | هل النوع `calculated_value`؟                                                                                                    | عاملها كتكوين مشتق؛ فهي مخفية وغير مطلوبة وغير قابلة للتحرير أو التكرار عمداً.                     |
| لا يمكن إضافة صفوف                   | هل النمط `fixedCount` أو `loop`، أو وصل الحد الأقصى في نمط المستخدم؟                                                            | استخدم تحكم المستخدم فقط عندما تسمح السياسة بالإضافة اليدوية، وضع حداً واضحاً.                     |
| تظهر صفوف كثيرة                      | في نمط الحلقة، هل تعيد عناصر الحلقة عناصر أكثر مما تتوقع؟ وفي نمط تحكم المستخدم، هل العدد الأولي الثابت أو العدد المطلوب مرتفع؟ | افحص المصفوفة المصدر أو إعدادات تحكم المستخدم المحدودة، ولا تحذف الصفوف لإخفاء مشكلة بيانات سابقة. |
| لم يعد صف الحلقة يطابق مصدره         | هل تغيرت المصفوفة المصدر بعد بدء الجلسة؟                                                                                        | راجع `@loop_item` المحفوظ وبيانات المصدر، ثم أعد الفتح أو صحح عبر مسار الجلسة المعتمد.             |
| يصعب استخدام الجدول على الهاتف       | هل الأعمدة كثيرة أو القيم طويلة؟                                                                                                | استخدم تخطيط القسم أو بسّط الأعمدة أو اختر سلوك الهاتف المختبر.                                    |
| تبدو الإجابات المتكررة غامضة للمراجع | هل تكررت حقول مستقلة بدلاً من قسم واحد؟                                                                                         | انقل المدخلات المرتبطة إلى قسم مكرر ليكون لكل مثيل حد واضح.                                        |

## الأذونات وحدود جودة البيانات

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

تأتي جودة البيانات من أنواع حقول واضحة وشروط محدودة وقيم اختيار مضبوطة وقواعد تحقق مراجعَة وحدود صريحة للمكررات. لا تعتمد على حقل مخفي كمخزن سري: فالظهور شرط عرض وليس بديلاً عن التحكم بالوصول أو سياسة الاحتفاظ بالبيانات. تجنب وضع رقم وطني أو بيانات اتصال أو دليل خاص داخل تعبير أو عنوان خيار أو عنوان مكرر. اجمع ما تحتاجه الخدمة فقط، واشرح سبب طلب الملف أو الموقع، واتبع مسار احتفاظ ومراجعة معتمداً للملفات.

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

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

* خطط تسلسل الالتقاط والنشر الكامل في [النماذج](/ar/build/forms).
* اضبط الإجراءات الشرطية وبوابات الإكمال وأدلة التوقيع في [إجراءات النماذج ومنطقها وتواقيعها](/ar/build/form-actions-logic-and-signatures).
* تعلّم صياغة التعبيرات المستخدمة في الشروط والقيم الافتراضية في [صياغة لغة التعبيرات](/ar/reference/expressions/language-syntax).
* راجع الجلسات المحفوظة والعمل اللاحق في [إرسالات النماذج](/ar/build/form-submissions).