全局快捷键看起来只需要注册一个组合,但 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。本文没有重新执行桌面测试;学习时应把返回值校验和真实按键行为分开确认。
本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。