يتيح البحث الديناميكي (يُسمى أيضاً Search API) لحقل select_one أو select_multiple أو text تحميل خياراته من خدمة ويب بعيدة في وقت التشغيل أثناء كتابة المعدِّد. هذا هو النهج الصحيح عندما تكون قائمة خياراتك كبيرة جداً بحيث لا يمكن تجميعها في ملف CSV، أو يتم تحديثها بشكل متكرر، أو تأتي من قاعدة بيانات مباشرة.

مظهر search-api()

يتم تكوين البحث الديناميكي من خلال عمود appearance باستخدام دالة search-api():

  search-api(method, url, post_body, value_column, display, data_path, save_path)

المعلمات

المعلمةالوصف
methodاستخدم دائماً 'POST'
urlنقطة نهاية API للاستعلام
post_bodyجسم JSON المُرسَل إلى API. استخدم %__input__% كمعلمة بديلة لنص البحث الحالي للمعدِّد
value_columnالمفتاح في كائن الاستجابة لاستخدامه كـ قيمة مخزنة
displayالمفتاح (أو القالب) لاستخدامه كـ تسمية تظهر في القائمة المنسدلة. يدعم معلمات ##key## البديلة وتعبيرات @{func}
data_pathJSONPath لمصفوفة كائنات النتيجة في الاستجابة (مثل $.data, $.hits.hits.*._source)
save_pathاسم يتم تحته حفظ الاستجابة الخام للاستخدام بواسطة حقول أخرى

مثال أساسي

بحث عن منشأة صحية حيث يكتب المعدِّد جزءاً من اسم المنشأة:

typenamelabelappearance
select_onefacilitySelect health facilitysearch-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data')

تتلقى API {"query": "nair"} عندما يكتب المعدِّد “nair” وتُعيد:

  {
  "results": [
    {"id": "HF001", "name": "Nairobi Central Clinic"},
    {"id": "HF002", "name": "Nairobi West Hospital"}
  ]
}

تعرض القائمة المنسدلة Nairobi Central Clinic وNairobi West Hospital؛ القيمة المخزنة هي HF001 أو HF002.

تنسيق العرض المتقدم

استخدام قوالب ##key##

إظهار عدة حقول في التسمية:

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')

يُعرض كـ: Nairobi Central Clinic (Nairobi).

استخدام تعبيرات @{func}

تطبيق منطق شرطي في تسمية العرض:

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
  '@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
  '$.data', 'res')

تعرض النتائج النشطة ✓ Clinic Name؛ غير النشطة ✗ Clinic Name.

ضبط قيمة افتراضية: search-default-api()

استخدم search-default-api() بعد search-api() لتعبئة الحقل مسبقاً بخيار افتراضي محمّل من استدعاء API منفصل (مثلاً عند تعديل سجل موجود):

  appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')

فاصل مخصص لـ select_multiple: search-default-separator()

لحقول select_multiple، حدد كيفية دمج القيم المحددة المتعددة في السلسلة المخزنة:

  appearance: search-api(...) search-default-separator(' || ')

الفاصل الافتراضي هو مسافة.

أنواع الأسئلة المدعومة

نوع السؤالحالة الاستخدام
select_oneتحديد واحد من نتائج البحث
select_multipleتحديدات متعددة من نتائج البحث
textإكمال تلقائي — يكتب المعدِّد بحرية ولكن يمكنه اختيار اقتراح

استخدام بيانات الاستجابة المحفوظة

يخزن save_path كائن استجابة API الكامل تحت الاسم المحدد. يمكن للحقول الأخرى الإشارة إليه بـ pulldata():

typenamelabelcalculation
select_onefacilitySelect facilitysearch-api(..., 'facility_data')
calculatefacility_districtpulldata('facility_data', 'district')
calculatefacility_typepulldata('facility_data', 'type')

أفضل الممارسات

  1. تأكد من أن نقطة نهاية API تستجيب خلال 1–2 ثانية — تجعل واجهات API البطيئة البحث يبدو غير متجاوب.
  2. استخدم %__input__% في post_body حتى تُعيد API فقط النتائج المطابقة، وليس مجموعة البيانات بأكملها.
  3. فهرس حقل البحث على جانب الخادم (مثل Elasticsearch، فهرس نص كامل في قاعدة البيانات) للحصول على استجابات سريعة.
  4. حدّد النتائج بـ 20–50 عنصراً لكل استعلام — إعادة آلاف النتائج تهزم الغرض من البحث.
  5. أدرج شرط الحد الأدنى لطول الإدخال في API لتجنب تشغيل استعلامات واسعة على مدخلات الحرف الواحد.

القيود

  • يتطلب البحث الديناميكي اتصالاً بالشبكة — لا يعمل دون اتصال.
  • يتم حقن معلمة %__input__% كما هي؛ قم بتعقيم المدخلات على جانب الخادم لمنع هجمات الحقن.
  • قد تحتوي تعبيرات العرض @{func} المعقدة على دعم محدود عبر جميع إصدارات عميل rtSurvey.
هل كانت هذه الصفحة مفيدة؟