SDK 事件系统
事件名使用冒号格式，例如 playback:trackChanged；方法调用使用点格式，例如 playback.play。
订阅事件
javascript
// 订阅事件，返回取消订阅函数
const unsubscribe = fb.on('playback:trackChanged', (track) => {
console.log('Now playing:', track.title);
});
// 取消订阅
unsubscribe();一次性事件
javascript
fb.once('playback:trackChanged', (track) => {
console.log('First track:', track.title);
});取消订阅
javascript
// 方式一：使用返回的 unsubscribe 函数（推荐）
const unsub = fb.on('playback:time', handler);
unsub();
// 方式二：手动 off
fb.on('playback:time', handler);
fb.off('playback:time', handler);播放事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| playback:trackChanged | 曲目切换 | |
| playback:stateChanged | 播放状态变化 | {state, position, duration} (state: "playing" / "paused" / "stopped") |
| playback:paused | 播放/暂停切换 | |
| playback:stopped | 播放停止 | {reason} ("user" / "eof" / "starting_another" / "shutting_down") |
| playback:starting | 播放即将开始 | {command, paused} (command: "play" / "next" / "previous" / "random") |
| playback:seeked | 播放位置跳转 | |
| playback:volumeChanged | 音量变化 | |
| playback:time | 播放时间更新（~1秒/次，整数秒） | |
| playback:timeHighRes | 高精度时间更新（~100ms，小数秒，C++ 定时器轮询真实位置） | |
| playback:orderChanged | 播放顺序变化 | |
| playback:queueChanged | 播放队列变化 | {origin} ("user_added" / "user_removed" / "playback_advance") |
| playback:edited | 当前曲目元数据被编辑 | |
| playback:dynamicInfo | 动态信息变化（网络流） | |
| playback:dynamicInfoTrack | 动态曲目信息变化 | |
| playback:itemPlayed | 曲目播放完成 | {title, artist, album, duration, path, ...} (完整 track info) |
| playback:stopAfterCurrentChanged | "当前曲目后停止"状态变化 | |
| playback:followCursorChanged | "播放跟随光标"变化 | |
| playback:cursorFollowChanged | "光标跟随播放"变化 |
播放列表事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| playlist:activated | 活动播放列表切换 | |
| playlist:created | 播放列表创建 | |
| playlist:removed | 播放列表删除 | |
| playlist:renamed | 播放列表重命名 | |
| playlist:reordered | 播放列表顺序变化 | |
| playlist:lockChanged | 锁定状态变化 | |
| playlist:itemsAdded | 曲目添加 | |
| playlist:itemsRemoved | 曲目移除 | |
| playlist:itemsReordered | 曲目重新排序 | |
| playlist:itemsReplaced | 曲目替换 | |
| playlist:selectionChanged | 选中项变化 | |
| playlist:focusChanged | 焦点曲目变化 | |
| playlist:defaultFormatChanged | 默认格式变化 | - |
| playlist:addComplete | 异步添加完成（广播） |
媒体库 / 元数据事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| library:itemsAdded | 媒体库新增项目 | |
| library:itemsRemoved | 媒体库移除项目 | |
| library:itemsModified | 媒体库项目修改 | |
| library:initialized | 媒体库初始化完成 | |
| library:getAllResult | 异步 library.getAll 结果就绪 | LibraryGetAllResultPayload |
| metadata:writeComplete | 异步元数据写入完成 | MetadataWriteCompletePayload |
| metadb:changed | 元数据变化 | |
| selection:changed | 全局选择变化（50ms 节流） |
音频事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| audio:spectrum | 频谱数据更新（需订阅） | |
| audio:stream | 音频流数据更新（需调用 subscribeStream 订阅） | 音频流数据 |
| audio:dspPresetChanged | DSP 预设变化 | - |
| audio:outputDeviceChanged | 输出设备变化 | - |
| audio:replaygainModeChanged | ReplayGain 模式变化 | |
| audio:fullWaveformReady | 完整波形生成完成 | |
| audio:fullWaveformFailed | 完整波形生成失败 |
窗口 / 面板 / UI 事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| window:alwaysOnTopChanged | 置顶状态变化 | |
| window:stateChanged | 窗口状态变化 | 规范字段 {isMaximized, isMinimized}（运行时暂兼容 maximized / minimized） |
| window:popupOpened | 弹出窗口打开 | |
| window:popupClosed | 弹出窗口关闭 | |
| window:beforeClose | 窗口关闭前确认 | |
| window:message | 跨窗口消息接收 | |
| window:behaviorChanged | 弹窗行为策略变更 | |
| window:minimizeSuppressed | 抑制最小化（Win+D 策略） | |
| window:backdropStateChanged | 主窗口 / popup 的 DWM 激活/失焦策略生效 | |
| window:hoverStateChanged | 窗口悬停状态变化 | |
| panel:initialized | 面板初始化完成 | |
| panel:focus | 面板获得焦点 | - |
| panel:blur | 面板失去焦点 | - |
| panel:visibilityChanged | DUI 面板可见性变化 | |
| panel:configChanged | 面板配置变化 | |
| ui:coloursChanged | 颜色主题变化 | - |
| ui:fontChanged | 字体变化 | - |
| ui:menuItemClicked | 菜单项点击 | |
| ui:toast | 通知消息 | |
| system:themeChanged | 系统主题变化 | |
| cursor:hiddenChanged | 光标隐藏状态变化 | CursorHiddenChangedPayload |
| taskbar:buttonClicked | 任务栏按钮被点击 | |
| webview:processFailed | WebView 进程失败或恢复 |
Tray 事件
托盘图标为应用级（无来源窗口），事件广播到所有窗口。
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| tray:click | 单击托盘图标 | |
| tray:doubleClick | 双击托盘图标 | |
| tray:beforeContextMenu | 右键菜单弹出前（异步；处理器内修改仅影响下一次右键） | |
| tray:menuItemClicked | 普通用户托盘项点击 / 富控件值变更 |
tray:menuItemClicked 的 value 语义：普通用户项与 now-playing 卡片回报 {id} 并关闭菜单；富值控件回报 {id, value} 并保持菜单打开——rating 为 0..5，slider 为 [min, max] 内的整数，segmented 为被选中分段的从 0 起索引。忽略 value 的前端保持既有 {id} 行为。内置 showPlaybackControls / showSystemItems 注入项，以及声明了 playbackAction 的项，由插件原生执行且不发此事件。
应用 / 键盘 / 菜单事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| app:beforeQuit | foobar2000 即将退出 | - |
| keyboard:hotkey | 已注册快捷键触发 | |
| menu:show | 自定义菜单打开 | |
| menu:select | 选中自定义菜单项 | |
| menu:dismiss | 自定义菜单关闭 |
跨窗口通信事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| port:connected | 命名通道连接 | |
| port:disconnected | 命名通道断开 | |
| port:message | 收到跨窗口消息 | |
| state:changed | 共享状态变更 | |
| state:deleted | 共享状态删除 |
插件事件
| 事件名 | 触发时机 | 数据 |
|---|---|---|
| plugin:registered | 外部插件注册 | |
| plugin:unregistered | 外部插件注销 | |
| api:registered | 外部 API 注册 | |
| api:unregistered | 外部 API 注销 | |
| http:response | 异步 HTTP 请求完成 | |
| http:downloadComplete | 下载完成 | HttpDownloadCompletePayload |
| jitQueue:needNext | 后端请求下一首 | {currentTrackId, reason} (reason: "trackChange" / "prefetch") |
| jitQueue:trackChanged | 播放曲目变化 | |
| jitQueue:listExhausted | 缓冲区耗尽 | |
| jitQueue:preloadComplete | JIT 预加载完成 | JitQueuePreloadCompletePayload |
| jitQueue:error | 错误 |
所有事件同时派发为 fb2k:* DOM 事件（CustomEvent）。