Skip to content

feat(console-ui): 添加全局快捷键与快捷键帮助面板 #4

Description

@wuxs

背景

devbox Console UI 已具备桌面、Dock 和应用窗口交互,但主要依赖鼠标操作:

  • console-ui/src/App.jsx 统一维护应用启动、聚焦、最小化、关闭和“显示桌面”等窗口状态。
  • console-ui/src/components/Dock.jsx 提供运行中应用聚焦/关闭入口。
  • console-ui/src/components/AppWindow.jsx 提供最小化、最大化/还原和关闭按钮。
  • 当前没有统一的全局快捷键注册机制,也没有面向用户的快捷键帮助入口;现有 Escape 处理仅散落在个别弹窗/抽屉中。

需要在不影响表单输入、浏览器默认行为和内嵌应用操作的前提下,为常用窗口操作增加一致、可发现、可测试的键盘交互。

目标

  1. 为 Console UI 增加统一、可扩展的全局快捷键系统。
  2. 为高频窗口与导航操作提供默认快捷键。
  3. 提供可通过按钮和键盘打开的“快捷键帮助”面板。
  4. 快捷键定义与帮助展示使用同一数据源,避免实现与文档漂移。

功能范围

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 关闭、点击遮罩关闭、焦点陷阱和关闭后焦点恢复。
  • 使用语义化 dialogrole="dialog"aria-modal="true"、可访问标题)。

4. 事件与冲突规则

  • 当焦点位于 inputtextareaselectcontenteditable 或代码编辑器/终端时,不触发会修改窗口或导航状态的快捷键。
  • 不覆盖未纳入本功能的浏览器默认快捷键;只有匹配到已启用动作时才调用 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
  • 可复用动作:launchAppfocusAppshowDesktop、最小化/关闭/最大化相关状态更新。
  • 新增通用模块可拆为:快捷键定义、组合键规范化/匹配 hook、帮助面板组件。
  • 将层级关闭行为显式建模,避免继续由多个组件各自监听全局 keydown

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions