背景
devbox Console UI 已具备桌面、Dock 和应用窗口交互,但主要依赖鼠标操作:
console-ui/src/App.jsx 统一维护应用启动、聚焦、最小化、关闭和“显示桌面”等窗口状态。
console-ui/src/components/Dock.jsx 提供运行中应用聚焦/关闭入口。
console-ui/src/components/AppWindow.jsx 提供最小化、最大化/还原和关闭按钮。
- 当前没有统一的全局快捷键注册机制,也没有面向用户的快捷键帮助入口;现有
Escape 处理仅散落在个别弹窗/抽屉中。
需要在不影响表单输入、浏览器默认行为和内嵌应用操作的前提下,为常用窗口操作增加一致、可发现、可测试的键盘交互。
目标
- 为 Console UI 增加统一、可扩展的全局快捷键系统。
- 为高频窗口与导航操作提供默认快捷键。
- 提供可通过按钮和键盘打开的“快捷键帮助”面板。
- 快捷键定义与帮助展示使用同一数据源,避免实现与文档漂移。
功能范围
1. 快捷键注册表
建立单一快捷键注册表,每项至少包含:
- 稳定
id
- 按平台显示的组合键(Windows/Linux 使用
Ctrl,macOS 使用 ⌘/Option)
- 动作、名称和说明
- 分类(导航、窗口、通用)
- 生效条件与禁用条件
全局事件监听在应用顶层统一安装和清理,不在各页面重复注册。
2. 首批快捷键
建议先覆盖已有能力,最终按浏览器/操作系统冲突审计结果确定具体键位:
| 功能 |
建议默认键位 |
| 打开/关闭快捷键帮助 |
?(Shift+/),并提供 Ctrl/⌘ + / 备选 |
| 显示桌面 |
Ctrl/⌘ + Alt/Option + D |
| 最小化当前应用 |
Ctrl/⌘ + Alt/Option + M |
| 最大化/还原当前应用 |
Ctrl/⌘ + Alt/Option + F |
| 关闭当前应用 |
Ctrl/⌘ + Alt/Option + W |
| 聚焦/启动 Dock 中第 1~9 个应用 |
Alt/Option + 1…9 |
| 关闭最上层弹窗/抽屉/帮助 |
Escape |
不采用会被浏览器或操作系统稳定占用的组合键;实现前需在 Chrome/Chromium、Firefox、Safari 的目标平台上完成冲突检查。
3. 快捷键帮助面板
- 在全局可发现位置增加“键盘快捷键”入口(优先放在
StatusBar 的帮助/菜单区域)。
- 支持点击入口、
? 和备选组合键打开。
- 按“通用 / 导航 / 窗口”分组展示。
- 根据当前平台渲染正确的 modifier 符号和按键名称。
- 仅展示当前可用或明确标注暂不可用的快捷键。
- 支持
Escape 关闭、点击遮罩关闭、焦点陷阱和关闭后焦点恢复。
- 使用语义化
dialog(role="dialog"、aria-modal="true"、可访问标题)。
4. 事件与冲突规则
- 当焦点位于
input、textarea、select、contenteditable 或代码编辑器/终端时,不触发会修改窗口或导航状态的快捷键。
- 不覆盖未纳入本功能的浏览器默认快捷键;只有匹配到已启用动作时才调用
preventDefault()。
Escape 按“最上层交互优先”关闭:确认框/弹窗 → 抽屉/帮助 → 其他临时 UI;不得一次关闭多层。
- 按住按键产生的
repeat 默认只执行一次,除非某动作明确允许重复。
- 组合键匹配不依赖键盘布局可见字符时,应合理使用
KeyboardEvent.code;帮助展示仍使用用户可理解的键名。
- 跨域 iframe 内的键盘事件不会冒泡到父页面;帮助面板需说明快捷键仅在焦点位于 devbox Console UI 时生效。必要时在应用窗口标题栏获得焦点后再响应。
非目标
- 本 Issue 不实现完整 Command Palette。
- 本 Issue 不提供用户自定义键位和持久化配置;注册表需为后续自定义预留扩展能力。
- 不尝试拦截操作系统级或跨域 iframe 内部快捷键。
验收标准
实现建议
- 顶层接入点:
console-ui/src/App.jsx。
- 可复用动作:
launchApp、focusApp、showDesktop、最小化/关闭/最大化相关状态更新。
- 新增通用模块可拆为:快捷键定义、组合键规范化/匹配 hook、帮助面板组件。
- 将层级关闭行为显式建模,避免继续由多个组件各自监听全局
keydown。
背景
devbox Console UI 已具备桌面、Dock 和应用窗口交互,但主要依赖鼠标操作:
console-ui/src/App.jsx统一维护应用启动、聚焦、最小化、关闭和“显示桌面”等窗口状态。console-ui/src/components/Dock.jsx提供运行中应用聚焦/关闭入口。console-ui/src/components/AppWindow.jsx提供最小化、最大化/还原和关闭按钮。Escape处理仅散落在个别弹窗/抽屉中。需要在不影响表单输入、浏览器默认行为和内嵌应用操作的前提下,为常用窗口操作增加一致、可发现、可测试的键盘交互。
目标
功能范围
1. 快捷键注册表
建立单一快捷键注册表,每项至少包含:
idCtrl,macOS 使用⌘/Option)全局事件监听在应用顶层统一安装和清理,不在各页面重复注册。
2. 首批快捷键
建议先覆盖已有能力,最终按浏览器/操作系统冲突审计结果确定具体键位:
?(Shift+/),并提供Ctrl/⌘ + /备选Ctrl/⌘ + Alt/Option + DCtrl/⌘ + Alt/Option + MCtrl/⌘ + Alt/Option + FCtrl/⌘ + Alt/Option + WAlt/Option + 1…9Escape3. 快捷键帮助面板
StatusBar的帮助/菜单区域)。?和备选组合键打开。Escape关闭、点击遮罩关闭、焦点陷阱和关闭后焦点恢复。dialog(role="dialog"、aria-modal="true"、可访问标题)。4. 事件与冲突规则
input、textarea、select、contenteditable或代码编辑器/终端时,不触发会修改窗口或导航状态的快捷键。preventDefault()。Escape按“最上层交互优先”关闭:确认框/弹窗 → 抽屉/帮助 → 其他临时 UI;不得一次关闭多层。repeat默认只执行一次,除非某动作明确允许重复。KeyboardEvent.code;帮助展示仍使用用户可理解的键名。非目标
验收标准
App.jsx窗口/导航动作,且不会复制一套独立状态。contenteditable、代码编辑器和终端中输入时,不误触发窗口/导航动作。Escape每次只关闭最上层交互。实现建议
console-ui/src/App.jsx。launchApp、focusApp、showDesktop、最小化/关闭/最大化相关状态更新。keydown。