模組和功能

外掛程式可以通過兩個系統擴展其基本 USB 讀寫以外的功能：模組和功能。了解它們之間的差異，有助於您發現可用的功能並使用正確的機制。

模組與功能的比較

	模組	功能
使用方式	import { x } from "@SignalRGB/name"	在 Initialize() 中使用 device.addFeature("name")
用途	實用服務（網路、編碼、系統資訊）	裝置能力（電池、輸入注入）
命名空間	模組自己匯出的名稱	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 的使用範例，請參閱進階通訊。

---

可用功能

在您的 Initialize() 匯出中呼叫 device.addFeature("name")。功能會建立一個與功能同名的全域物件。

功能名稱	命名空間	用途
"keyboard"	keyboard	注入按鍵或將鍵盤事件路由到 SignalRGB 巨集
"mouse"	mouse	注入滑鼠輸入或將滑鼠事件路由到 SignalRGB 巨集
"battery"	battery	回報無線裝置的電池電量和充電狀態
"dtls"	dtls	使用 PSK 認證的 DTLS 加密 UDP

---

鍵盤功能

用於表示鍵盤裝置的外掛程式。讓您向作業系統注入真實按鍵，或觸發可啟動 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 }); // 按下 A
keyboard.sendHid(0x41, { released: true });  // 釋放 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	Windows MOUSEEVENTF_* 旗標
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 選項）

// 左鍵點擊
mouse.sendHid(0x0002, {});  // 按下
mouse.sendHid(0x0004, {});  // 釋放

// 向上滾動一格
mouse.sendHid(0x0800, { WheelDelta: 120 });

// X1 鍵按下
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() {
    // 非阻塞讀取——檢查裝置是否在本幀發送了電池報告
    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
        );
    }
}