Repository navigation
feat(console-ui): 添加全局快捷键与快捷键帮助面板 #4
Copy link
Copy link
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
背景
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 内部快捷键。
验收标准
- 存在单一快捷键注册表,事件处理与帮助面板均从该注册表读取。
- 首批快捷键可以调用现有
App.jsx窗口/导航动作,且不会复制一套独立状态。 - 用户可从全局可见入口和键盘打开快捷键帮助面板。
- 帮助面板支持键盘操作、焦点管理、屏幕阅读器语义和 reduced motion。
- 在普通表单、
contenteditable、代码编辑器和终端中输入时,不误触发窗口/导航动作。 - 顶层弹窗叠加时,
Escape每次只关闭最上层交互。 - Windows/Linux 与 macOS 显示各自正确的 modifier 文案。
- 跨域 iframe 限制在帮助中有明确提示。
- 为组合键规范化、上下文禁用、重复按键、层级关闭和平台展示补充单元测试。
- 使用浏览器测试覆盖:打开帮助、显示桌面、最小化、最大化/还原、关闭、Dock 数字快捷键,以及输入框不误触发。
- 不破坏现有鼠标操作、认证弹窗和各应用页面交互。
实现建议
- 顶层接入点:
console-ui/src/App.jsx。 - 可复用动作:
launchApp、focusApp、showDesktop、最小化/关闭/最大化相关状态更新。 - 新增通用模块可拆为:快捷键定义、组合键规范化/匹配 hook、帮助面板组件。
- 将层级关闭行为显式建模,避免继续由多个组件各自监听全局
keydown。
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
Merge pull request #6 from a2d2-dev/issue-4-global-shortcuts