متى تستخدم هذه الدوال؟
استخدم هذه الدالة في قالب مستند مُراجع عندما لا يكفي سياق السجل المقدم. اجعل نطاق البحث صغيراً واختبر في وضع التنفيذ المختار.طريقة الكتابة
استخدم الدالة بصيغةgetRecords({ entityKey: "service_requests", limit: 5 }). لا تكون كل دالة متاحة في كل مكان: دوال التحقق ودوال النموذج ودوال قالب المستند لها عقود سياق مختلفة. لا تفترض أن اقتراح المحرر يعني أن الدالة مدعومة وقت التشغيل.
مرجع الدوال الكامل
getRecords
يبحث عن سجلات أثناء توليد قالب مستند باستخدام كائن استعلام واحد. يقيّد كل استدعاء limit بين 1 و500، ويختلف الوصول بين وضعي المتصل والمدير.
التوقيع: getRecords({ entityKey, q?, filters?, limit?, sorting?, search? })
مثال:
عقد الاستعلام وحدود الوصول
شكل الطلب والنتائج
تتطلبgetRecords كائناً يتضمن entityKey غير فارغ؛ ويجعل تمرير نص أو كائن بلا مفتاح كيان عملية العرض تفشل بدلاً من التخمين. الحد الافتراضي للنتائج هو 100 ويُحصر ضمن المجال الشامل من 1 إلى 500. عند حذف filters تستخدم الدالة قائمة فارغة، وعند حذف q ينتقي KayanOS شكل سجل المستند الاعتيادي، بما فيه data:* وبيانات السجل الثابتة مثل id وlabel وتواريخ الإنشاء والتحديث.
إذا تضمن q المحدد يدوياً data:*، تُسطّح قيم البيانات في الصف الناتج حتى تستطيع كتابة row.request_reference. أما الاستعلام المخصص الذي لا يتضمن data:* فيبقي شكل الاستجابة كما أعاده الاستعلام؛ لا تفترض وجود الحقول على المستوى الأعلى في هذه الحالة. مرر sorting كمصفوفة، لا ككائن منفرد:
search وq عندما تكون الحاجة مفهومة وقابلة للاختبار. ابدأ بكيان واحد ومرشح واحد وحد صغير؛ لا تجعل حلقة القالب استعلاماً واسعاً غير مراجع.
وضع المتصل ووضع المدير
في وضع المتصل، ينفذ البحث بهوية العضو الذي يعرض المستند وتُطبق صلاحيات قراءة ذلك العضو. في وضع المدير، يستخدم البحث مسار بيانات إدارياً؛ يتطلب تشغيل القالب ذاته وصول المنشئ وفعل إدارة معيّناً. لا تجعل وضع المدير خياراً افتراضياً لمجرد أن بحثاً في وضع المتصل لم يُرجع صفوفاً. تقيّد قائمة الكيانات المسموحة غير الفارغة البحث الإداري على مفاتيح الكيانات المذكورة فيها. أما القائمة المحذوفة أو الفارغة فهي وصول إداري واسع وليست قاعدة منع. عند اعتماد الوضع الإداري، عيّن قائمة قصيرة غير فارغة، ثم اختبر أن الاستعلام لكيان خارجها يفشل، واحتفظ بسبب موافقة واضح مع القالب.مثال عملي آمن
لقائمة طلبات خدمة المواطنين المعتمدة داخل خطاب مراجعة، استخدم حلقة صغيرة ومحددة، ثم اختبر المخرج في كل وضع مقصود:قائمة تحقق قبل النشر
- ابدأ بقيمة معروفة وتحقق من النتيجة المتوقعة.
- تعامل صراحةً مع القيم الفارغة وnull والقوائم الفارغة.
- لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
- راجع سياقات وتوافر التعبيرات قبل نسخ تعبير بين ميزتين.
