跳到主要内容

事件

Skydimo 以 JSON-RPC 2.0 通知的形式广播实时事件。事件由服务端主动推送，无需请求 —— 它们没有 id 字段。

事件格式​

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "event": "<事件名称>",
    "data": { ... }
  }
}

事件类型​

devices-changed​

当设备列表或任何设备配置发生变化时触发（设备连接/断开、设置更新等）。

{
  "event": "devices-changed",
  "data": {
    "devices": [ ... ]
  }
}

触发时机：设备连接/断开、昵称变更、灯效变更、亮度变更、区段更新、LED 锁状态变化。

提示

这是保持 UI 同步的核心事件。收到后，应刷新完整的设备列表。

device-led-update​

高频事件（约 30 fps），包含某设备输出端口的当前 LED 颜色。

{
  "event": "device-led-update",
  "data": {
    "port": "COM3",
    "outputId": "out1",
    "colors": [255, 0, 0, 0, 255, 0, 0, 0, 255, ...]
  }
}

colors 数组包含每个 LED 的 RGB 三元组（R, G, B, R, G, B, ...）。

性能提示

此事件高频触发。请使用 Web Worker 或对渲染进行节流，避免阻塞 UI 线程。

notification​

来自 Core 或插件的 Toast 通知。

{
  "event": "notification",
  "data": {
    "id": "notif_123",
    "title": "设备已连接",
    "description": "在 COM3 发现 Skydimo LED 控制器",
    "level": "info",
    "persistent": false
  }
}

级别："info"、"warn"、"error"

持久通知就地更新特性：如果 persistent 为 true 且 UI 收到了带有完全相同 id 的新 notification 事件，则不会弹出新的 Toast，而是就地更新已存在的 Toast 的 title 和 description。这对于显示进度或实时状态更新（例如 扫描中... 10/100）非常有用。

notification-dismiss​

关闭持久通知。

{
  "event": "notification-dismiss",
  "data": {
    "id": "notif_123"
  }
}

led-locks-changed​

当扩展插件锁定或解锁 LED 时触发。

{
  "event": "led-locks-changed",
  "data": { ... }
}

通过 get_led_locks 命令查询完整的锁定状态。

ext-page-message:{extId}​

当扩展插件的嵌入 HTML 页面向 Core 发送消息时触发。事件名称包含扩展插件 ID。

{
  "event": "ext-page-message:openrgb",
  "data": { ... }
}

Lua 扩展通过 on_page_message(data) 回调接收此消息。native-c 扩展通过 on_page_message_json 接收同一载荷。

system.process.changed​

版本

自 3.0.0-dev.3 起支持。目前仅支持 Windows。

当运行中的应用程序进程列表发生变化（应用启动或停止）时触发。拥有 system:process 权限的扩展插件通过 on_system_state_changed("process", data) 回调接收此事件。

{
  "event": "system.process.changed",
  "data": {
    "supported": true,
    "apps": [
      { "name": "chrome.exe", "instance_count": 3 },
      { "name": "code.exe", "instance_count": 1 }
    ],
    "changes": [
      { "name": "notepad.exe", "previous_instance_count": 1, "current_instance_count": 0 }
    ]
  }
}
字段类型说明
supportedboolean当前平台是否支持进程监控
appsarray当前运行中的应用程序完整列表
changesarray本次更新中实例数发生变化的应用程序

system.focus.changed​

版本

自 3.0.0-dev.3 起支持。目前仅支持 Windows。

当前台窗口焦点发生变化（用户切换到不同窗口，或当前窗口标题改变）时触发。拥有 system:window-focus 权限的扩展插件通过 on_system_state_changed("window_focus", data) 回调接收此事件。

{
  "event": "system.focus.changed",
  "data": {
    "supported": true,
    "reason": "foreground_changed",
    "current": {
      "app_name": "code.exe",
      "window_title": "extension-api.md - Light - Visual Studio Code"
    },
    "previous": {
      "app_name": "chrome.exe",
      "window_title": "GitHub"
    }
  }
}
字段类型说明
supportedboolean当前平台是否支持窗口焦点监控
reasonstring"snapshot"、"foreground_changed" 或 "title_changed"
currentobject?当前聚焦窗口（app_name、window_title），若无则为 null
previousobject?之前聚焦的窗口，若无则为 null

订阅事件​

从 3.0.0-dev.3 开始，事件会自动推送到所有已连接的本机 WebSocket 客户端，无需显式订阅。