Liner 全局快捷键与窗口定位内幕：Hyprland/Sway 集成完整解析

Liner（README.md）是一款跨平台的 Linux/Windows 桌面音乐播放器，它把各平台的音乐和歌单汇聚到一个干净的应用中，主打同步歌词与无干扰播放。在 Linux 的 Wayland 环境下，Electron 原生的全局快捷键和窗口置顶常常失效，Liner 通过一套「Compositor Bridge」直接对话 Hyprland 和 Sway 窗口管理器，实现了可靠的全局快捷键绑定与悬浮播放条的精准窗口定位。

一、为什么 Wayland 下快捷键会变"哑"？

X11 时代，应用可以轻松"钩住"系统级按键。而 Wayland 出于安全设计，应用不能随意拦截其他窗口的按键事件，Electron 的globalShortcut在纯 Wayland 会话下要么不可用、要么不可靠。

Liner 的解法是：不硬拦按键，而是请求窗口管理器帮你绑定。当按键被触发时，由 compositor 执行一条命令，命令再把事件"转发"回 Liner。整个逻辑集中在 electron/compositor/ 目录中。

二、会话检测：先搞清楚你在哪个窗口管理器上

入口文件 session.ts 通过环境变量判断当前环境：

检测逻辑很简单直接：Hyprland 会导出HYPRLAND_INSTANCE_SIGNATURE，Sway 会导出SWAYSOCK，两个变量正是各自 IPC 通道的"门牌号"。

三、全局快捷键内幕：命令管道 + 反向绑定

1. 反向通信：mkfifo 命令管道

全局快捷键按下后，compositor 执行的是外部 shell 命令，如何把事件送进 Liner 进程？答案在 commandPipe.ts：

1. 在$XDG_RUNTIME_DIR下创建一个命名管道（FIFO），命名规则为liner-<pid>.cmd；
2. 应用以非阻塞方式打开并持续监听管道内容；
3. 绑定快捷键时，生成的命令形如：

test -p '/run/user/1000/liner-12345.cmd' && printf '%s\n' 'toggle-overlay' 1<>/run/user/1000/liner-12345.cmd

也就是说，"按下 Alt+Shift+O" 等价于往管道里写一行toggle-overlay，主进程读到后由 overlay.ts 的handleCompositorAction分发——toggle-overlay切换悬浮播放条，like-track触发点赞。管道随进程创建、随退出销毁（dispose时rmSync），干净利落。

2. Hyprland 绑定：直连 Socket，支持 Lua 模式

hyprlandIpc.ts 通过XDG_RUNTIME_DIR/hypr/<signature>/.socket.sock与 Hyprland 通信，带 1.5 秒超时保护。绑定快捷键（hyprlandBinds.ts）分两种情况：

• 经典配置模式：直接下发keyword bind Mod,Shift,O,exec,...，绑定前先keyword unbind清理旧绑定；
• Lua 配置模式（新版 Hyprland 默认）：bind不可用，返回失败，快捷键改由 Electron 的globalShortcut兜底注册——这是 index.ts 里bindShortcut失败后自动回退到registerGlobalToggle的原因。

另外还有一个巧妙的细节：keys.ts 会把按键映射为按键代码（keycode）而非字符，避免不同键盘布局下快捷键"漂移"；overlay.ts 甚至内置了西里尔字母到 QWERTY 的映射表，让俄语布局用户录制的Alt+Shift+Щ也能被正确识别为Alt+Shift+O。

3. Sway 绑定：swaymsg 命令行

sway.ts 走的是外部命令路线：

• 查询：swaymsg -r -t get_tree递归查找当前聚焦节点；
• 绑定：bindsym --no-repeat --to-code Mod4+Shift+O exec <命令>，--to-code同样是按物理键位绑定，布局无关；
• 解绑：精确unbindsym，避免误伤同名绑定。

所有swaymsg调用都设置了 1.5 秒超时，防止命令卡死拖垮 UI。

四、窗口定位内幕：把悬浮条"钉"到屏幕顶部

悬浮播放条（Overlay）是一个无边框、透明、320×56 的窗口。在平铺式窗口管理器里，它不能被平铺打乱，所以要"浮"起来并精确摆位。

1. 工作区计算与锚点

placement.ts 定义了三种锚点：top-left/top-center/top-right，并计算精确坐标（含 20px 边距）。Hyprland 侧还会从 hyprland.ts 的monitors接口读取焦点显示器的reserved区域（为 dock 等预留的空间），并按屏幕旋转、缩放换算出真正可用的工作区。

2. Hyprland：一批 dispatch 命令搞定

placeHyprlandWindow把多条命令打包成[[BATCH]]一次性下发：

• setfloating—— 悬浮化，脱离平铺；
• movewindowpixel exact x y—— 精确移动到计算好的坐标；
• pin—— 按设置决定跨工作区置顶；
• noborder / noshadow / rounding 0 / noblur—— 去掉一切装饰，得到纯净的药丸形态；
• 最后把焦点交还给之前捕获的窗口（captureFocus记录的previousFocus），做到"弹出但不抢焦点"。

3. Sway：一条 criteria 命令链

Sway 侧用[pid=<pid> title="^Liner Overlay$"]精确定位窗口（PID + 标题双重校验），然后：

[pid=12345 title="^Liner Overlay$"] floating enable, sticky on, border none, move absolute position 640 20

sticky对应跨工作区置顶，move absolute position给出绝对坐标；放置完成后[con_id=<旧焦点>] focus恢复原焦点。

五、用户体验细节：这些代码带来的实际好处

• 快捷键全局可用：切到任何应用，Alt+Shift+O（默认）随时唤起悬浮播放条，Alt+Shift+L一键点赞当前曲目；
• 弹出无感：Overlay 用showInactive显示、事后归还焦点，看视频/写代码时不会打断当前输入；
• 设置实时生效：前端的 overlaySettingsStore.ts 修改位置/快捷键后，立即通知主进程重新绑定并重新定位窗口；
• 自动降级：非 Hyprland/Sway 环境自动退回 Electron 原生globalShortcut与setAlwaysOnTop，行为一致。

六、常见问题

Q：我用的 GNOME/KDE Wayland 会话，快捷键不生效？Liner 目前只对 Hyprland 和 Sway 做深度集成，其他 Wayland 会话依赖 Electron 原生全局快捷键，可能受桌面环境限制。

Q：修改快捷键后没有反应？确认应用窗口有焦点后在设置中保存；Liner 会先unbind旧组合再bind新组合，若与系统快捷键冲突会注册失败并打印日志。

Q：悬浮条位置不对？位置由"锚点 + 工作区 + 边距"计算，多显示器下以 Overlay 所在显示器为准，可检查是否开启了独占全屏应用占用了 reserved 区域。

延伸阅读

• 会话与集成入口：electron/compositor/index.ts
• 悬浮条管理与快捷键注册：electron/overlay.ts
• 存储键说明（liner_overlay_settings_v1等）：docs/STORAGE.md