Skip to content

Latest commit

 

History

History
84 lines (60 loc) · 4.96 KB

File metadata and controls

84 lines (60 loc) · 4.96 KB

ADR-025: 浮窗锁定自解锁——全局快捷键方案(tauri-plugin-global-shortcut)

状态

已接受(v0.12.6,2026-08-23 用户裁决;已实施交付——浮窗显隐链路修复 + Ctrl+Shift+F 全局快捷键,真机验证待执行)

日期

2026-08-23

背景

浮窗交互三个用户反馈(2026-08-23):① 浮窗在应用启动时自动显示(应为用户选择才出现);② 浮窗出现后主页面应隐藏;③ 锁定(点击穿透)后无法从浮窗自身解锁,只能回主页面点"解锁浮窗"。

其中③与①②组合后成为硬问题:主窗隐藏 + 锁定 = 无任何可点击 UI。点击穿透是窗口级能力 (set_ignore_cursor_events → WS_EX_TRANSPARENT),锁定态下浮窗收不到任何鼠标事件;本机 tauri 2.11.5 / wry 0.55.1 无 set_cursor_hit_test(分区点击穿透,源码检索确认缺失), 两窗叠放(解锁把手窗)需额外 WebView2 实例(40-80MB 内存/个,v0.12.3 已记录成本)。

决策

  • 浮窗三态切换收拢到 Rust 单一来源(float_toggle_core:关→开 / 开未锁→收起+回主窗 / 开已锁→解锁),主窗按钮(float_toggle 命令)与全局快捷键共用——防主窗键 + 全局键 双触发双翻转(原主窗 keydown 三态分支删除,仅保留浮窗关闭态的打开快捷键)。
  • 全局快捷键 Ctrl+Shift+F(进程级):浮窗打开期间注册、收起期间注销——隔离冲突面; 锁定态/主窗隐藏下均可解锁/切换。解锁后 set_focus 浮窗(Esc 等快捷键恢复可用)。
  • 浮窗出现 → 主窗隐藏;收起/停止采集/回主窗 → 主窗回显(绝不把用户留在无可见窗口)。
  • 预创建修复:setup 预创建浮窗误传 visible=true(启动即显示抢焦点)——改隐藏预创建。
  • 浮窗窗口级 CSS 重置:无全局样式下 body 8px margin + 100vh 溢出 → 左右透明条 + 滚条, 浮窗组件挂载注入 html/body 重置(margin 0 / overflow hidden / 100%)。

备选方案

方案 A:锁定态仍从主窗解锁(现状)——否

主窗已隐藏(需求②),解锁路径不存在;且需先回主窗再操作,与需求③直接冲突。

方案 B:分区点击穿透(解锁把手窗 / set_cursor_hit_test)

  • 解锁把手:额外 28×28 WebView2 实例随浮窗同步位置——内存 +40-80MB、位置同步/吸附/形态 联动复杂度高。
  • set_cursor_hit_test:tauri 2.11.5 / wry 0.55.1 源码检索不存在该 API(后续版本才加入, 升级 tauri 属另一 ADR 范畴)。

方案 C:悬停自动解锁(Rust 轮询光标停留)

无依赖、无热键冲突,但误触率高(点击浮窗下方视频时光标必然停在浮窗内); 确定性弱于热键,否。

方案 D:全局快捷键(选定)

  • 优点:进程级热键(浮窗/主窗/第三方应用焦点下均可用)、零额外窗口、注册窗口期可控、 与既有 Ctrl+Shift+F 肌肉记忆一致。
  • 缺点:引入 tauri-plugin-global-shortcut 依赖;捕获等待场景下系统级热键占位 (Ctrl+Shift+F 少见,实测冲突概率低);需 UI 明示(锁定态显示"已锁定 · Ctrl+Shift+F")。

选择理由

需求②(主窗隐藏)使"从主窗解锁"不成立;方案 B 成本不成比例;方案 C 有确定性命门。 全局快捷键是唯一低成本且确定性的"浮窗自身可解锁"路径(对用户等效:不依赖主窗)。

影响

正面影响

  • 浮窗不再启动自显(随用户选择出现);出现后主窗隐藏(专注模式);锁定后可自解锁。

负面影响 / 代价

  • 新依赖 tauri-plugin-global-shortcut(约数个 crate,无传递重依赖)。
  • Ctrl+Shift+F 在应用运行 + 浮窗打开期间为进程级热键(系统其他应用焦点下同样触发)。
  • 收起/停止后主窗回显是行为变化(主窗不再保持隐藏直至用户自己回显)。

风险

  • 全局快捷键与宿主系统注册冲突(同键已被占用时注册失败)——注册失败即打开浮窗前置 失败(2026-08-23 审查即修:浮窗不显示、主窗不隐藏、错误可见可重试;杜绝"浮窗已开但 锁定后无法解锁"的死局),未做冲突提示文案(记需求池)。
  • 主窗隐藏的行为(浮窗打开即隐藏)需真机验收(含 ⌂ 主窗 → 主窗回显、浮窗保留语义)。

合规性验证

  • 应用启动 → 浮窗不显示、不抢焦点;点"浮窗化" → 浮窗显示 + 主窗隐藏;Ctrl+Shift+F (任意焦点)→ 收起 + 主窗回显;再按 → 打开 + 主窗隐藏;锁定 → 浮窗显示"已锁定"提示 → Ctrl+Shift+F → 解锁且浮窗可交互;⏹ 停止 → 浮窗收起 + 主窗回显;⌂ 主窗 → 主窗回显、 浮窗保留。

相关决策

  • ADR-007: 采集生命周期(主窗关闭拦截)
  • v0.12.3 版本文档:浮窗双形态 / 点击穿透锁定 / 常驻预创建(P2-10)