~/notes/screenpin-03-wayland-shortcut-lifecycle.md1135 字

项目实战ScreenPin 桌面编辑器学习笔记 · 03/03

ScreenPin(三):Wayland 快捷键授权与会话切换

从门户按键格式转换到新绑定确认、配置保存和旧会话清理,讲解全局快捷键的生命周期与验证边界。

目录 4 节

全局快捷键看起来只需要注册一个组合,但 Wayland 桌面门户还涉及授权、实际按键分配和会话生命周期。返回了截图操作 ID,不能单独证明实际按键能触发。

本篇从 ScreenPin 的门户按键转换讲起,再追踪修改快捷键时,新绑定、配置文件与旧会话之间的切换顺序。

一、快捷键 ID 返回了,也不等于真的能触发

Wayland 下,项目通过桌面门户申请全局快捷键。此前出现过一种失败:门户返回的会话包含截图操作 ID,应用看起来已经注册,实际按键却没有反应。

仓库排查记录指出,项目传入的按键格式有问题。内部使用的 Super 需要转换成门户的 LOGO,字母主键也不能跟修饰键一起统一转成大写。

修复后的转换测试包含这个例子:

应用配置:Super+Shift+A
门户请求:LOGO+SHIFT+a

大小写在这里参与按键符号的表达,修饰键和主键需要分别转换。

src-tauri/src/shortcuts.rs 中的 portal_shortcut 使用带前瞻的迭代器,判断当前 token 是否为最后一个:

while let Some(token) = tokens.next() {
    if tokens.peek().is_none() {
        parts.push(portal_keysym(token));
    } else {
        parts.push(portal_modifier(token).to_string());
    }
}
Ok(parts.join("+"))

前置语义校验已经确保组合有效,最后一项作为主键转换,之前各项按修饰键转换。这种写法把“主键”和“修饰键”的角色直接放进处理流程,不需要靠整串大小写转换去猜。

保存流程也不能只检查返回了操作 ID。现在会等待门户授权结果,核对截图操作是否实际获分配按键、按键描述是否为空,完成后再继续配置保存。

这仍有一个边界:当前校验不能证明门户最终分配的组合与请求完全相同。门户可能重映射,因此真实按键行为和实际分配结果还需要桌面验收。

二、替换快捷键要保留失败后的旧绑定

用户修改快捷键时,授权可能被拒绝,配置文件也可能写入失败。如果先注销旧快捷键,再尝试新绑定,失败后应用会失去原来可用的组合。

项目改成先建立新绑定,等待门户确认,再保存配置,最后才替换旧绑定。

保留旧绑定
  → 申请新绑定并等待授权
  → 校验返回的按键分配
  → 保存配置
  → 替换旧绑定并清理旧会话

中间任一步失败,都保留旧绑定和原配置,并关闭不再使用的新会话。保存期间拒绝并发提交,避免两次授权互相覆盖。

快捷键事件还需要按会话过滤。旧门户会话和监听任务没有清理干净时,可能重复触发截图,或者在稍后结束时覆盖新一轮注册状态。

因此,快捷键功能除了注册和注销,还需要明确授权等待、配置写入、事件归属和会话清理的顺序。

三、代码检查与实际桌面验收

建议先读 src-tauri/src/shortcuts.rs 的 portal_shortcut 和门户返回值校验,再结合 lib.rs 追踪保存入口。记录在 2026 年 9 月 11 日的前端与 Rust 自动化检查覆盖部分数据、转换和响应逻辑,不代表授权成功、取消、冲突与反复切换都已完成真机验收。

当前校验可以确认截图操作获分配非空按键描述,却不能证明实际分配完全等于请求组合。完整验收仍需实际按键,检查失败后旧组合仍然可用、成功后新组合只触发一次,以及废弃会话已释放。

项目的具体待验收事项见 IMPROVEMENTS.md。本文没有重新执行桌面测试;学习时应把返回值校验和真实按键行为分开确认。

本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。

系列阅读

上一章:ScreenPin(二):SVG 逆矩阵与拖拽事件合并

  1. ScreenPin(一):可编辑标注、工程文件与图片导出
  2. ScreenPin(二):SVG 逆矩阵与拖拽事件合并
  3. ScreenPin(三):Wayland 快捷键授权与会话切换