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

# دالة البحث في قالب المستند

> عقد البحث عن السجلات الخاص بقالب المستند، بما في ذلك وسيط الكائن والفرق بين تشغيل المتصل والمدير.

## متى تستخدم هذه الدوال؟

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

## طريقة الكتابة

استخدم الدالة بصيغة `getRecords({ entityKey: "service_requests", limit: 5 })`. لا تكون كل دالة متاحة في كل مكان: دوال التحقق ودوال النموذج ودوال قالب المستند لها عقود سياق مختلفة. لا تفترض أن اقتراح المحرر يعني أن الدالة مدعومة وقت التشغيل.

## مرجع الدوال الكامل

### `getRecords`

يبحث عن سجلات أثناء توليد قالب مستند باستخدام كائن استعلام واحد. يقيّد كل استدعاء `limit` بين 1 و500، ويختلف الوصول بين وضعي المتصل والمدير.

**التوقيع:** `getRecords({ entityKey, q?, filters?, limit?, sorting?, search? })`

**مثال:**

```txt theme={null}
getRecords({ entityKey: "service_requests", filters: [["status", "eq", "approved"]], limit: 20 })
```

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

**ملاحظة:** استخدمها كاستدعاء دالة؛ لا تستخدمها كتحويل.

## عقد الاستعلام وحدود الوصول

### شكل الطلب والنتائج

تتطلب `getRecords` كائناً يتضمن `entityKey` غير فارغ؛ ويجعل تمرير نص أو كائن بلا مفتاح كيان عملية العرض تفشل بدلاً من التخمين. الحد الافتراضي للنتائج هو `100` ويُحصر ضمن المجال الشامل من `1` إلى `500`. عند حذف `filters` تستخدم الدالة قائمة فارغة، وعند حذف `q` ينتقي KayanOS شكل سجل المستند الاعتيادي، بما فيه `data:*` وبيانات السجل الثابتة مثل `id` و`label` وتواريخ الإنشاء والتحديث.

إذا تضمن `q` المحدد يدوياً `data:*`، تُسطّح قيم البيانات في الصف الناتج حتى تستطيع كتابة `row.request_reference`. أما الاستعلام المخصص الذي لا يتضمن `data:*` فيبقي شكل الاستجابة كما أعاده الاستعلام؛ لا تفترض وجود الحقول على المستوى الأعلى في هذه الحالة. مرر `sorting` كمصفوفة، لا ككائن منفرد:

```txt theme={null}
getRecords({
  entityKey: "citizen_service_requests",
  filters: [["status", "eq", "approved"]],
  limit: 10,
  sorting: [{ field: "created", direction: "desc" }]
})
```

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

### وضع المتصل ووضع المدير

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

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

### مثال عملي آمن

لقائمة طلبات خدمة المواطنين المعتمدة داخل خطاب مراجعة، استخدم حلقة صغيرة ومحددة، ثم اختبر المخرج في كل وضع مقصود:

```txt theme={null}
{{#each getRecords({
  entityKey: "citizen_service_requests",
  filters: [["status", "eq", "approved"]],
  limit: 5,
  sorting: [{ field: "created", direction: "desc" }]
}) as row}}
{{ row.request_reference }} — {{ row.service_type }}
{{/each}}
```

راجع [سياق تعبير قالب المستند](/ar/reference/expressions/document-template-context) و[وسوم قوالب المستندات والتصيير](/ar/build/document-template-tags-and-rendering) قبل نشر قالب يستخدم بحثاً.

## قائمة تحقق قبل النشر

* ابدأ بقيمة معروفة وتحقق من النتيجة المتوقعة.
* تعامل صراحةً مع القيم الفارغة وnull والقوائم الفارغة.
* لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
* راجع [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts) قبل نسخ تعبير بين ميزتين.

![دالة البحث في قالب المستند في KayanOS](https://kayanos.app/docs-images/ar/reference/expressions-helpers-document-templates.png)