#سير الأحداث

#مقدمة

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

#كيفية الاستخدام

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

خطوات التكوين هي كما يلي:

1. انقر على أيقونة "البرق" في الزاوية العلوية اليمنى لكتلة الجدول الأيسر لفتح واجهة تكوين سير الأحداث.
2. انقر على "إضافة سير أحداث (Add event flow)"، واختر "النقر على صف" في "حدث التشغيل"، مما يعني التشغيل عند النقر على صف الجدول.
3. قم بتكوين "توقيت التنفيذ"، والذي يُستخدم للتحكم في ترتيب سير الأحداث هذا بالنسبة لعمليات النظام المدمجة. بشكل عام، يمكن الإبقاء على الإعداد الافتراضي؛ إذا كنت ترغب في عرض تنبيه/انتقال بعد تنفيذ المنطق المدمج، يمكنك اختيار "بعد كل السير". لمزيد من التوضيح، راجع قسم توقيت التنفيذ أدناه.
4. يُستخدم "شرط التشغيل (Trigger condition)" لتكوين الشروط، حيث يتم تشغيل سير الأحداث فقط عند استيفاء الشروط. هنا لا نحتاج لتكوينه، فسيتم تشغيل سير الأحداث بمجرد النقر على الصف.
5. مرر الماوس فوق "إضافة خطوة (Add step)" لإضافة بعض خطوات العمليات. نختار "تعيين نطاق البيانات (Set data scope)" لتعيين نطاق بيانات الجدول الأيمن.
6. انسخ معرف UID للجدول الأيمن، وأدخله في مربع إدخال "معرف UID للكتلة المستهدفة (Target block UID)". ستظهر واجهة تكوين الشروط فورًا بالأسفل، حيث يمكنك تكوين نطاق بيانات الجدول الأيمن.
7. لنقم بتكوين شرط كما هو موضح في الصورة أدناه:
8. بعد تكوين نطاق البيانات، يجب تحديث الكتلة لعرض نتائج التصفية. بعد ذلك، لنقم بتكوين تحديث كتلة الجدول الأيمن. أضف خطوة "تحديث الكتل المستهدفة (Refresh target blocks)"، ثم أدخل معرف UID للجدول الأيمن.
9. أخيرًا، انقر على زر الحفظ في الزاوية السفلية اليمنى لإكمال التكوين.

#تفاصيل الأحداث

#قبل العرض

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

#النقر على صف (Row click)

حدث حصري لكتلة الجدول. يتم تشغيله عند النقر على صف الجدول. عند التشغيل، سيتم إضافة Clicked row record إلى السياق، والذي يمكن استخدامه كمتغير في الشروط والخطوات.

#تغيير قيم النموذج (Form values change)

حدث حصري لكتلة النموذج. يتم تشغيله عند تغيير قيمة حقل في النموذج. يمكن الحصول على قيم النموذج عبر متغير "Current form" في الشروط والخطوات.

#النقر (Click)

حدث حصري للأزرار. يتم تشغيله عند النقر على الزر.

#توقيت التنفيذ

في إعدادات سير الأحداث، هناك مفهومان يسهل الخلط بينهما:

• حدث التشغيل: متى يبدأ التنفيذ (مثل: قبل العرض، النقر على صف، النقر، تغيير قيم النموذج، إلخ).
• توقيت التنفيذ: بعد وقوع نفس حدث التشغيل، أين سيتم إدراج سير الأحداث المخصص الخاص بك للتنفيذ بالنسبة إلى العمليات المدمجة.

#ما هي "العمليات المدمجة / الخطوات المدمجة"؟

تأتي العديد من الصفحات أو الكتل أو العمليات مع مجموعة من عمليات المعالجة المدمجة في النظام (مثل: الإرسال، فتح نافذة منبثقة، طلب البيانات، إلخ). عندما تضيف سير أحداث مخصص لنفس الحدث (مثل "النقر")، يُستخدم "توقيت التنفيذ" لتحديد:

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

#كيف نفهم خيارات توقيت التنفيذ في واجهة المستخدم؟

• قبل كل السير (افتراضي): يتم تنفيذه أولاً. مناسب لعمليات "الاعتراض/التحضير" (مثل التحقق، التأكيد المزدوج، تهيئة المتغيرات، إلخ).
• بعد كل السير: يتم تنفيذه بعد اكتمال المنطق المدمج. مناسب لعمليات "الختام/التغذية الراجعة" (مثل رسائل التنبيه، تحديث الكتل الأخرى، الانتقال لصفحة أخرى، إلخ).
• قبل سير محدد / بعد سير محدد: نقطة إدراج أكثر دقة. بعد الاختيار، تحتاج إلى اختيار "العملية المدمجة" المحددة.
• قبل خطوة سير محددة / بعد خطوة سير محددة: أدق نقطة إدراج. بعد الاختيار، تحتاج إلى اختيار كل من "العملية المدمجة" و"خطوة العملية المدمجة".

تنبيه: إذا لم تكن متأكدًا من العملية/الخطوة المدمجة التي يجب اختيارها، فاستخدم الخيارين الأولين ("قبل / بعد") كأولوية.

#تفاصيل الخطوات

#متغير مخصص (Custom variable)

يُستخدم لتخصيص متغير ثم استخدامه في السياق.

#النطاق

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

#متغير النموذج (Form variable)

استخدام قيمة كتلة نموذج معينة كمتغير. التكوين كالتالي:

• Variable title: عنوان المتغير
• Variable identifier: معرف المتغير
• Form UID: معرف UID للنموذج

#متغيرات أخرى

سيتم دعم متغيرات أخرى تباعًا، يرجى الانتظار.

#تعيين نطاق البيانات (Set data scope)

تعيين نطاق بيانات الكتلة المستهدفة. التكوين كالتالي:

• Target block UID: معرف UID للكتلة المستهدفة
• Condition: شرط التصفية

#تحديث الكتل المستهدفة (Refresh target blocks)

تحديث الكتل المستهدفة، يسمح بتكوين كتل متعددة. التكوين كالتالي:

• Target block UID: معرف UID للكتلة المستهدفة

#الانتقال إلى عنوان URL (Navigate to URL)

الانتقال إلى عنوان URL معين. التكوين كالتالي:

• URL: عنوان URL المستهدف، يدعم استخدام المتغيرات
• Search parameters: معلمات الاستعلام في عنوان URL
• Open in new window: إذا تم تحديده، سيتم فتح صفحة متصفح جديدة عند الانتقال

#عرض رسالة (Show message)

عرض معلومات التغذية الراجعة للعمليات على مستوى العالم.

#متى تستخدم

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

#التكوين المحدد

• Message type: نوع الرسالة
• Message content: محتوى الرسالة
• Duration: مدة العرض بالثواني

#عرض إشعار (Show notification)

عرض معلومات تنبيه الإشعارات على مستوى العالم.

#متى تستخدم

عرض معلومات تنبيه الإشعارات في الزوايا الأربع للنظام. تُستخدم غالبًا في الحالات التالية:

• محتوى إشعار معقد.
• إشعارات تفاعلية تعطي المستخدم خطوات العمل التالية.
• دفع النظام التلقائي.

#التكوين المحدد

• Notification type: نوع الإشعار
• Notification title: عنوان الإشعار
• Notification description: وصف الإشعار
• Placement: الموقع، الخيارات المتاحة: أعلى اليسار، أعلى اليمين، أسفل اليسار، أسفل اليمين

#تنفيذ JavaScript (Execute JavaScript)

تنفيذ كود JavaScript.

#مثال

#النموذج: استدعاء واجهة برمجة تطبيقات (API) خارجية لملء الحقول

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

خطوات التكوين:

1. افتح تكوين سير الأحداث في كتلة النموذج وأضف سير أحداث جديد؛
2. اختر "قبل العرض" كحدث تشغيل؛
3. اختر "بعد كل السير" كتوقيت تنفيذ؛
4. أضف خطوة "تنفيذ JavaScript (Execute JavaScript)"، وقم بلصق الكود أدناه وتعديله حسب الحاجة:

const res = await ctx.api.request({
  method: 'get',
  url: 'https://jsonplaceholder.typicode.com/users/2',
  skipNotify: true,
  // Note: ctx.api will include the current NocoBase authentication/custom headers by default
  // Here we override it with an "empty Authorization" to avoid sending the token to a third party
  headers: {
    Authorization: 'Bearer ',
  },
});

const username = res?.data?.username;

// replace it with actual field name
ctx.form.setFieldsValue({ username });