دليل استخدام عقد الحالة

01 · نظرة سريعة

تتضمن أدوات الحالة كائنًا يملك القيمة وعمليات تقرؤها أو تغيّرها:

عقدة الحالة

توجد على مساحة العمل.
تحتفظ بالقيمة (ON/OFF أو العدد أو الطوابع الزمنية أو المستخدمين).
يمكن تشغيل البوابة والعداد ومحدد المعدل في مسار الأحداث العادي.
ذاكرة المستخدمين مركز مشترك تشير إليه عقد أخرى.

إجراء الحالة

توضع لاحقًا في المسار.
تقرأ القيمة المخزّنة أو تغيّرها (الضبط على ON أو إضافة +1 أو التذكر أو السحب أو إعادة الضبط، وغيرها).
يمكن أن توجد في أي مكان من التدفق — اختر فقط اسم العقدة المطابقة.

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

02 · مفتاح تشغيل وإيقاف (بوابة)

المفتاح حارس منطقي. عند ON تمر الرسائل؛ وعند OFF يتوقف التدفق عند هذه العقدة.

الأنسب لـ

فترات انتظار لأوامر الدردشة.
مفاتيح تبديل يدوية (تفعيل التراكبات وتعطيلها).
فترات الصيانة (إيقاف الميزات مؤقتًا أثناء مشاهد سأعود قريبًا).

الإجراءات الأساسية

Set Gate State— التبديل إلى ON أو OFF.
Reset State Node— العودة إلى الافتراضي (عادةً ON).

مثال: فترة انتظار 15 ثانية

!hello ──▶ مفتاح (ON؟) ─▶ إرسال رد ─▶ ضبط البوابة: OFF ─▶ تأخير 15 ثانية ─▶ ضبط البوابة: ON

خطوات الإنشاء

أضف عقدة المفتاح وسمّها “helloCooldown”، مع الحالة الافتراضية ON.
اربط المشغّل → المفتاح → الإجراءات.
بعد الإجراء، أضف ضبط حالة البوابة (Set Gate State) (OFF) مع الإشارة إلى “helloCooldown”.
أضف تأخير (Delay) (15 ثانية).
أضف عقدة أخرى من نوع ضبط حالة البوابة (Set Gate State) (ON) لـ “helloCooldown”.

03 · العداد

تتتبع العدادات الأرقام عبر الرسائل. وتزيد تلقائيًا عندما تمر رسالة عبرها، ويمكنك تعديل القيم يدويًا باستخدام الإجراءات.

زيادة تلقائية: في كل مرة تمر حمولة عبر عقدة العداد، تضيف 1 (إلا إذا أوقفتها مؤقتًا بخيار «Only count when gate is true»).

حالات الاستخدام

كل مشارك رقم N في الدردشة يفعّل جائزة.
تتبع التقدم نحو هدف مجتمعي.
تخزين النقاط المستبدلة عبر الأوامر.

الإجراءات

Increment Counter— إضافة أو طرح مقادير مخصصة.
Set Counter Value— الانتقال إلى رقم محدد.
Reset State Node— العودة إلى قيمة البداية الافتراضية.

مثال: الاحتفال كل 5 رسائل

أي رسالة ─▶ عداد (الاسم: hype5) ─▶ شرط (value % 5 === 0؟) ─▶ تشغيل احتفال

داخل عقدة الشرط، قارن state.hype5.value أو استخدم ببساطة خيار «Trigger when value matches Target» المدمج في خصائص عقدة العداد.

04 · محدد المعدل (Throttle)

يتذكر محدد المعدل الطوابع الزمنية ويرفض الأحداث الجديدة حتى يُراعى المعدل الذي تحدده.

مفيد عندما تحتاج إلى

«خمس مشاركات فقط في السحب في الدقيقة.»
«استدعاء API واحد كل 10 ثوانٍ.»
«تجاهل التنبيهات إذا كان التراكب مشغولًا بالفعل.»

الضبط

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

تنبيه: لا تعيد محددات المعدل ضبط نفسها تلقائيًا عند تعديل التدفق. استخدم Reset State Node إذا احتجت إلى حالة نظيفة أثناء الاختبار.

05 · ذاكرة المستخدمين

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

الأنسب لـ

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

العمليات

Remember User و Forget User.
User Is Remembered.
Pick Random User.
Clear All Users أو Reset State Node.

مشغّل المشاركة ──▶ تذكّر المستخدم ······▶ ذاكرة المستخدمين: Entrants أمر السحب ───────────▶ اختيار مستخدم عشوائي ···▶ ذاكرة المستخدمين: Entrants أمر إعادة الضبط ──────────▶ مسح جميع المستخدمين ·····▶ ذاكرة المستخدمين: Entrants

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

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

06 · حلول جاهزة للمشكلات

اختر سيناريو واتبع الخطوات.

فترة انتظار الأمر

عقدة مفتاح اسمها “commandCooldown”.
مشغّل → مفتاح → رد.
ضبط البوابة OFF → تأخير → ضبط البوابة ON.
أضف رسالة دردشة «فترة الانتظار نشطة» إلى مخرج false إن رغبت.

هدايا مجانية محدودة

عداد بقيمة افتراضية 0 وهدف 3.
زِد بعد كل استبدال.
عندما تكون القيمة ≥ 3، انتقل إلى فرع «عذرًا، نفدت الكمية».
استخدم إجراء إعادة الضبط في نهاية البث.

مفتاح تبديل للمشاهدين

مفتاح اسمه “overlayToggle”.
!overlay on أمر → ضبط البوابة ON.
!overlay off أمر → ضبط البوابة OFF.
تمر جميع مشغّلات التراكب عبر المفتاح.

أمثلة مخططات التدفق

مشغّل ─▶ مفتاح (overlayToggle) ─▶ عند ON → إظهار التراكب └─false─▶ إخطار المشرف «التراكب معطل»

استبدال مكافأة ─▶ العداد ticketsSold ├─value < 50 ─▶ الموافقة على الاستبدال └─value ≥ 50 ─▶ الرفض + إعادة النقاط

07 · استكشاف الأخطاء والأسئلة الشائعة

العَرَض	السبب المحتمل	الحل
إجراء Set Gate State لا يُحفظ.	لا توجد عقدة مفتاح مطابقة (أو تختلف الأسماء).	أضف عقدة المفتاح أولًا وتأكد من أن القائمة المنسدلة تشير إليها.
العداد لا يزيد أبدًا.	يتجاوز التدفق عقدة العداد أو تكون البوابة false.	تأكد من مرور سلك المشغّل عبر العداد وأن خرج البوابة true.
محدد المعدل يمنع كل شيء إلى الأبد.	النافذة الزمنية صارمة جدًا أو هناك حالة متبقية من الاختبار.	خفف الحد وأضف إجراء Reset State Node قبل إعادة الاختبار.
عملية ذاكرة مستخدمين بلا رابط متقطع.	لم تُحدَّد ذاكرة مستهدفة.	اختر الذاكرة المسماة في خصائص العملية أو اسحب موصلها الجانبي الأرجواني إلى الذاكرة.
أزرار الدليل لا تفتح.	التشغيل داخل الإضافة دون تحديث موارد web_accessible.	تأكد من `actions/state-nodes-guide.html` مضمَّن عبر manifest، ثم أعِد تحميل الإضافة.

قائمة فحص الاختبار

استخدم أداة «Send Test Event» في Event Flow لمحاكاة الأوامر.
قصّر فترات الانتظار مؤقتًا إلى ثانيتين أو اخفض أهداف العدادات أثناء التحقق.
أعِد ضبط عقد الحالة بين الاختبارات حتى لا تقرأ بيانات قديمة.
سمِّ الفروع (مثل «false → فترة الانتظار نشطة») لتتمكن من تتبع المسار بصريًا.

08 · الخطوات التالية

ادمج عقد الحالة مع بقية أدوات Event Flow:

استخدم البوابات المنطقية (AND/OR/NOT) قبل المفتاح لتحديد من يمكنه تبديله.
خزّن البيانات الوصفية المعتمدة على الحالة ضمن meta حتى تعرف التراكبات سبب تشغيل الفرع.
صدّر الأنماط التي تعمل كقوالب حتى يتمكن فريقك من استيرادها لاحقًا.

واصل التجربة! الدليل الجديد دليل Event Flow يكمل هذا الدليل لتتمكن من إتقان طبقتي المنطق والحالة.