模块和功能

插件可以使用两种系统将其功能扩展到基本 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 }); // 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	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
        );
    }
}