الوحدات والميزات

يمكن للإضافات توسيع قدراتها إلى ما هو أبعد من عمليات القراءة والكتابة الأساسية عبر USB باستخدام نظامين: الوحدات (Modules) والميزات (Features). يساعدك فهم الفرق بينهما على اكتشاف ما هو متاح واستخدام الآلية المناسبة للمهمة.

الوحدات مقابل الميزات

	الوحدات	الميزات
طريقة الاستخدام	import { x } from "@SignalRGB/name"	device.addFeature("name") داخل Initialize()
الغرض	خدمات مساعدة (الشبكات، الترميز، معلومات النظام)	قدرات الجهاز (البطارية، حقن الإدخال)
مساحة الأسماء	الأسماء المُصدَّرة الخاصة بالوحدة	device.featureName.*
المثيلات	واحد لكل إضافة	يمكن أن يكون هناك عدة مثيلات

---

الوحدات المتاحة

استوردها في أعلى ملف الإضافة.

مسار الاستيراد	الغرض
@SignalRGB/serial	الاتصال عبر المنفذ التسلسلي/COM
@SignalRGB/tcp	الاتصال عبر مقبس TCP
@SignalRGB/udp	الاتصال عبر مقبس UDP
@SignalRGB/base64	ترميز Base64 وفك ترميزه
@SignalRGB/performance	تحليل الأداء ومؤقتات الإطارات
@SignalRGB/appInfo	معلومات إصدار تطبيق SignalRGB
@SignalRGB/systeminfo	معلومات عتاد النظام
@SignalRGB/permissions	التحقق من حالة أذونات المستخدم

راجع الاتصال المتقدم للاطلاع على أمثلة استخدام serial وtcp وudp.

---

الميزات المتاحة

استدعِ device.addFeature("name") داخل التصدير Initialize(). تُنشئ الميزة كائنًا عامًا بالاسم نفسه للميزة.

اسم الميزة	مساحة الأسماء	الغرض
"keyboard"	keyboard	حقن ضغطات المفاتيح أو توجيه أحداث لوحة المفاتيح إلى وحدات الماكرو في SignalRGB
"mouse"	mouse	حقن إدخال الماوس أو توجيه أحداث الماوس إلى وحدات الماكرو في SignalRGB
"battery"	battery	الإبلاغ عن مستوى البطارية وحالة الشحن للأجهزة اللاسلكية
"dtls"	dtls	UDP مشفّر بتقنية DTLS مع مصادقة PSK

---

ميزة لوحة المفاتيح

للإضافات التي تمثل أجهزة لوحات المفاتيح. تتيح لك حقن ضغطات مفاتيح حقيقية في نظام التشغيل أو إطلاق أحداث يمكنها تشغيل وحدات الماكرو في SignalRGB.

export function Initialize() {
    device.addFeature("keyboard");
}

keyboard.sendHid(vkCode, options)

ترسل ضغطة مفتاح خام مباشرة إلى نظام التشغيل عبر keybd_event. يظهر المفتاح كإدخال حقيقي لجميع التطبيقات — ويتجاوز نظام الماكرو بالكامل.

المعامل	النوع	الوصف	مثال
vkCode	Number	رمز المفتاح الافتراضي في Windows	0x41 (المفتاح A)
options.released	Boolean (مطلوب)	true لتحرير المفتاح، وfalse للضغط عليه	false

keyboard.sendHid(0x41, { released: false }); // Press A
keyboard.sendHid(0x41, { released: true });  // Release A

keyboard.sendEvent(eventData, eventType)

توجّه حدث لوحة مفاتيح عبر نظام الماكرو في SignalRGB. يمكن لوحدات الماكرو التي تحتوي على مُشغّل onKey مطابقة هذه الأحداث. لا تحقن ضغطة مفتاح حقيقية — فقط وحدات الماكرو في SignalRGB ترى هذا الحدث.

يُثري نظام الماكرو الحدث تلقائيًا بالحالة الحية لمفاتيح التعديل (Ctrl وShift وAlt وWin) من لوحة المفاتيح الفعلية قبل إرساله.

المعامل	النوع	الوصف	مثال
eventData	Object أو String	بيانات الحدث. ضمّن key (اسم نصي) واختياريًا keyCode (رقم) لمطابقة المفتاح.	{ key: "A", keyCode: 0x41 }
eventType	String	تسمية نوع الحدث	"KeyPress"

keyboard.sendEvent({ key: "A", keyCode: 0x41, released: false }, "KeyPress");

تستقبل نصوص الماكرو event.Sender (المعرّف الفريد UID للإضافة) وevent.SenderType ("Device")، بحيث يمكنها التمييز بين الأحداث الصادرة عن الإضافة وضغطات المفاتيح الحقيقية من العتاد.

---

ميزة الماوس

للإضافات التي تمثل أجهزة الماوس أو أجهزة التأشير.

export function Initialize() {
    device.addFeature("mouse");
}

mouse.sendHid(buttonCode, options)

ترسل حدث ماوس خام إلى نظام التشغيل عبر SendInput. حركة الماوس (MOUSEEVENTF_MOVE، MOUSEEVENTF_ABSOLUTE) محظورة لأسباب أمنية.

المعامل	النوع	الوصف
buttonCode	Number	علامة MOUSEEVENTF_* في Windows
options.XButton	Number	مطلوب لأحداث أزرار X — 1 (X1) أو 2 (X2)
options.WheelDelta	Number	مطلوب لأحداث عجلة التمرير — القيمة الموجبة للتمرير لأعلى، والسالبة للتمرير لأسفل

رموز الأزرار الشائعة:

الرمز	الثابت	الوصف
0x0002	MOUSEEVENTF_LEFTDOWN	الضغط على الزر الأيسر
0x0004	MOUSEEVENTF_LEFTUP	تحرير الزر الأيسر
0x0008	MOUSEEVENTF_RIGHTDOWN	الضغط على الزر الأيمن
0x0010	MOUSEEVENTF_RIGHTUP	تحرير الزر الأيمن
0x0020	MOUSEEVENTF_MIDDLEDOWN	الضغط على الزر الأوسط
0x0040	MOUSEEVENTF_MIDDLEUP	تحرير الزر الأوسط
0x0800	MOUSEEVENTF_WHEEL	التمرير العمودي
0x01000	MOUSEEVENTF_HWHEEL	التمرير الأفقي
0x0080	MOUSEEVENTF_XDOWN	الضغط على زر X (يتطلب الخيار XButton)
0x0100	MOUSEEVENTF_XUP	تحرير زر X (يتطلب الخيار XButton)

// Left click
mouse.sendHid(0x0002, {});  // down
mouse.sendHid(0x0004, {});  // up

// Scroll up one notch
mouse.sendHid(0x0800, { WheelDelta: 120 });

// X1 button press
mouse.sendHid(0x0080, { XButton: 1 });
mouse.sendHid(0x0100, { XButton: 1 });

mouse.sendEvent(eventData, eventType)

توجّه حدث ماوس مخصصًا عبر نظام الماكرو في SignalRGB. يمكن لنصوص الماكرو التي تحتوي على مُشغّل onMouse مطابقة هذه الأحداث. لا تحقن أي إدخال ماوس على مستوى نظام التشغيل.

mouse.sendEvent({ button: "LeftClick" }, "ButtonPress");

---

ميزة البطارية

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

export function Initialize() {
    device.addFeature("battery");
}

ضبط حالة البطارية

الطريقة	الوصف
battery.setBatteryLevel(level)	ضبط نسبة البطارية (0–100)
battery.setBatteryState(state)	ضبط حالة الشحن باستخدام ثابت حالة

ثوابت الحالة (يمكن الوصول إليها عبر battery.<name>):

الثابت	الوصف
battery.disabled	الإبلاغ عن البطارية معطّل
battery.unknown	الحالة غير معروفة بعد
battery.draining	يعمل على البطارية
battery.charging	يشحن عبر الكابل
battery.fullCharging	يشحن وممتلئ بالفعل
battery.full	مشحون بالكامل، ولا يشحن
battery.wirelessCharging	شحن لاسلكي

قراءة حالة البطارية

تعكس هذه الخصائص آخر القيم التي تم ضبطها:

الخاصية	النوع	الوصف
battery.batteryLevel	Number	المستوى الحالي (0–100)
battery.batteryState	Number	قيمة الحالة الحالية
battery.stateString	String	تسمية الحالة بصيغة مقروءة

مثال على البطارية

export function Initialize() {
    device.addFeature("battery");
}

export function Render() {
    // Non-blocking read — check if the device sent a battery report this frame
    var data = device.read([], 64, 0);

    if(device.getLastReadSize() > 0 && data[0] === 0x02) {
        var level = data[1];             // 0–100
        var charging = data[2] === 0x01;

        battery.setBatteryLevel(level);
        battery.setBatteryState(
            charging ? battery.charging : battery.draining
        );
    }
}