命令面板系统 是做什么的？
目的
命令面板系统为全局、键盘触发的覆盖菜单（通常通过 Cmd+K 或 Ctrl+K 调用）提供了设计和空间框架。在现代、高密度的 Web 应用程序、开发者平台和内容丰富的文档门户中，标准导航栏会变得不堪重负。命令面板充当“指挥中心”，为高级用户提供直接、无摩擦的键盘路径来搜索、导航和执行操作，同时作为键盘快捷键的交互式字典。
此技能确保命令面板在空间上符合人体工程学，在视觉上结构清晰以防止认知疲劳，并完全符合高级无障碍规范（WCAG 2.2 AA）。
用例
- 为 SaaS 仪表板设计全局快捷键驱动的工作区控制器。
- 构建面向开发者的门户和文档搜索门户（例如，API 参考）。
- 为企业 CRM 或 CMS 平台实施快速操作管理面板。
- 在复杂的多层 Web 产品中创建统一的命令行界面 (CLI)。
何时不使用
- 静态营销落地页： 用户意图纯粹是探索性和转化性的；全局导航栏和清晰的号召性用语 (CTA) 更有效。
- 浅层信息站点（少于 15 页）： 实施和教授命令面板的开销超过了任何寻路收益。
- 简单的移动消费者站点： 屏幕空间很小，用户严格依赖触摸交互，没有外部物理键盘。
输入
- 命令和操作清单： 可搜索操作、页面、设置和文档的全面分类法。
- 上下文映射规则： 哪些命令是全局的，哪些是上下文特定的规则（例如，“删除项目”仅在查看项目时出现）。
- 键盘快捷键系统： 操作到物理键盘快捷键的映射（例如，
G然后D表示“转到仪表板”）。 - 品牌设计令牌： 排版比例、颜色、间距比例和阴影令牌（来自
fluid-spacing-system和fluid-typography-system）。
输出
- 触发元素规范： 持久入口点和键盘快捷键徽章的视觉设计。
- 面板布局架构： 覆盖模态框的网格结构、结果分组、类别导航和辅助页脚。
- 命令行视觉规范： 图标、命令标题、类别徽章和快捷键注释的层次结构规范。
- 键盘和无障碍规范： 与 ARIA APG Combobox 模式匹配的精确键盘事件映射和 ARIA 状态规范。
工作流程
1. 建立面板触发器和入口点
因为命令面板默认是隐藏的，所以你必须设计可发现的入口点：
- 持久头部触发器： 一个模仿全局头部搜索栏的按钮，包含放大镜图标、文本标签（例如，“搜索或运行命令...”）和右对齐的物理键盘快捷键徽章（例如，
⌘K或Ctrl+K）。 - 浮动命令按钮： 对于仪表板密集型或全屏视口，在视口右下角放置一个微妙的触发按钮。
- 不可见的全局监听器： 确保在文档上的任何位置按下
Cmd+K（macOS）或Ctrl+K（Windows/Linux）（除非焦点在文本输入中）会立即打开面板。
2. 设计模态覆盖层和背景遮罩
- 背景遮罩： 使用高对比度、半透明的背景遮罩（例如，
rgba(15, 23, 42, 0.4)）来调暗背景页面，将注意力完全集中在当前任务上。 - 垂直放置： 水平居中模态框，但将其锚定在视口的顶部 10%–15% 处，而不是绝对垂直居中。这与自然视线水平对齐，并为触摸屏上的物理虚拟键盘留出空间。
- 尺寸范围： 将宽度限制在舒适的扫描范围内——理想情况下在 600px 到 680px 之间。高度应该是动态的，最大值限制在 450px 到 550px，以确保它永远不会溢出小型笔记本电脑屏幕。
3. 构建内部布局网格
将命令面板划分为四个不同的水平区域：
- 搜索和过滤区域： 一个无边框、全宽的输入字段，带有突出的搜索图标（最小 20px）。使用指导用户的占位文本（例如，“键入命令或搜索...”）。
- 类别过滤栏（可选）： 一行紧凑的标签或分段控件（例如，“全部”、“操作”、“页面”、“用户”），让用户在搜索前过滤结果。
- 结果反馈区（滚动容器）： 一个包含滚动条且带有分组标题的列表框（例如，“最近”、“导航”、“系统设置”）。
- 辅助页脚： 一个低对比度的状态栏，显示键盘指南（例如，
↑↓ 导航，↵ 选择，esc 关闭）。
+-----------------------------------------------------------+
| [搜索图标] 搜索或键入命令... [ESC] |
+-----------------------------------------------------------+
| ( 全部 ) ( 操作 ) ( 页面 ) ( 成员 ) ( 帮助 ) |
+-----------------------------------------------------------+
| 最近搜索 |
| [图标] 转到结算 [ ⌘ G ] [ B ]|
| [图标] 创建新发票 [ ⌘ N ] |
| |
| 导航 |
| [图标] 仪表板 |
| [图标] 团队设置 [ ⌘ , ] |
+-----------------------------------------------------------+
| ↑↓ 导航 | ↵ 选择 | esc 关闭 | ? 帮助文档 |
+-----------------------------------------------------------+
4. 创建命令行的视觉层次结构
结果列表中的每个项目必须在几毫秒内可扫描：
- 左对齐图标： 一个明确、高对比度的图标，指示项目的类型（例如，文件图标表示文档，设置齿轮表示操作，用户头像表示人员）。
- 主要标签： 命令本身使用半粗体、主色文本（例如，“邀请团队成员”）。
- 次要子标签（可选）： 主标签下方或旁边的柔和、较小字体的描述，以提供上下文（例如，“设置 > 组织”）。
- 右对齐快捷键徽章： 使用小、高对比度的按键徽章（例如，
⌥I）显示与该命令关联的物理键盘快捷键。
5. 定义交互状态和键盘选择
命令面板主要由键盘驱动；因此，键盘选择状态优先于鼠标悬停：
- 活动/聚焦项目状态： 当使用箭头键导航到一个项目时，应用突出的背景填充更改（使用主色浅色令牌，例如，
var(--color-primary-light)）和左边框指示器。主要文本应变为品牌颜色。 - 悬停状态（鼠标）： 镜像活动键盘状态。将鼠标移到项目上应更新键盘选择，以防止双重焦点状态。
- 空状态： 当搜索没有返回结果时，显示一个清晰、说明性的空状态，建议替代操作（例如，“未找到命令。尝试搜索我们的帮助中心”并带有搜索链接）。
- 加载状态： 如果搜索查询结果是异步获取的，在搜索输入的底部显示一个微妙的线性加载指示器，避免导致布局偏移的骨架卡片。
决策规则
- “Cmd+K 与持久搜索”规则： 如果网站的主要价值是消费结构化内容（如电子商务目录），请使用持久搜索栏。如果价值在于管理工作流程、命令执行或密集导航，请使用
Cmd+K命令面板。 - 分组限制规则： 永远不要同时显示超过 3-4 个命令类别。保持每个类别中可见项目最多为 5 个，如果存在更多，则提供“显示更多...”选项。
- “按键次数”规则： 命令旁边显示的物理键盘快捷键必须不超过 3 个按键（例如，
Ctrl+Shift+P是可接受的；Ctrl+Alt+Shift+Z过于复杂）。 - 动态上下文规则： 根据活动路由动态过滤命令。如果用户在结算页面，则在默认（未输入）结果列表的顶部优先显示“更新信用卡”或“下载发票 PDF”。
约束条件
1. 无障碍性（至少 WCAG 2.2 AA）
- ARIA Combobox 模式： 你必须严格按照 ARIA 创作实践指南 (APG) 构建标记：
- 输入容器必须具有
role="combobox"、aria-expanded="true"、aria-autocomplete="list"和aria-controls="command-listbox-id"。 - 结果列表必须具有
role="listbox"，并且每个命令行必须具有role="option"。 - 当用户按下箭头键时，输入必须更新
aria-activedescendant以指向活动选项的 ID，并且该选项必须具有aria-selected="true"。
- 输入容器必须具有
- 焦点管理： 打开面板必须将键盘焦点锁定在覆盖层内。按下
Tab键应该被拦截以在面板内循环，或者完全禁用（优先使用箭头键进行选项导航）。关闭面板必须将焦点返回到确切的触发元素。 - 屏幕阅读器公告： 在输入旁边放置一个具有
aria-live="polite"和aria-atomic="true"的不可见div。搜索时，动态填充结果状态（例如，“找到 12 个结果，使用上下箭头键导航”）。 - 对比度： 所有文本、快捷键徽章和焦点指示器必须满足 WCAG AA（正常文本至少 4.5:1，UI 边框和选择指示器至少 3:1）。
- 背景锁定： 当面板激活时，应用程序的其余部分必须被渲染为
inert并对屏幕阅读器隐藏。使用<dialog>.showModal()来实现焦点捕获、背景变暗和原生的Escape关闭。
2. 响应式和触摸适应
- 触摸视口调整： 在移动屏幕上，命令面板必须切换到全屏覆盖层或底部滑出抽屉。
- 虚拟键盘处理： 打开时自动聚焦搜索输入，并使用
inputmode="search"确保移动设备在其虚拟键盘上显示正确的“搜索”操作按钮。 - 隐藏物理提示： 在纯触摸设备上，隐藏物理键盘快捷键徽章（例如，
⌘K或⌥I），因为它们不相关并会造成视觉混乱。 - 触摸目标大小： 在触摸屏上，可移除标签、类别标签和列表行的高度必须至少为 44px，以适应手指点击，符合 WCAG 2.2 SC 2.5.8。
常见失败模式
- “无限滚动”陷阱： 允许结果反馈区渲染 100 多个匹配项而没有滚动容器，从而溢出屏幕并使页脚指南无法访问。
- 缺少背景滚动锁定： 当用户滚动导航命令面板时，允许背景文档滚动，导致布局迷失方向。
- 输入焦点丢失： 点击类别标签或结果选项，并从文本输入中丢失键盘焦点，要求键盘用户制表符返回。
- 难以理解的移动显示： 在 320px 的移动屏幕上保留一个以桌面为中心的小型模态框，从而截断主要标签和快捷键徽章。
- 缺少触发器状态镜像： 持久头部按钮没有显示键盘快捷键，导致键盘用户不知道存在命令面板。
验证标准
- 头部存在一个持久触发器按钮，并带有清晰的
Cmd+K/Ctrl+K视觉快捷键徽章。 - 在页面上的任何位置按下
Cmd+K或Ctrl+K会打开模态框。 - 键盘焦点立即移动到搜索输入，并且背景页面滚动被锁定。
- 选项的导航由上、下箭头键驱动，并带有高度可见的聚焦活动状态。
- 选项行具有结构化的层次结构：左侧图标、粗体操作标题、上下文路由层次结构和右侧快捷键徽章。
- 完全指定了 ARIA APG Combobox 模式，包括
role="combobox"、role="listbox"、role="option"和aria-activedescendant。 - 存在一个
aria-live="polite"区域，用于向屏幕阅读器宣布搜索结果数量的变化。 - 在移动视口上，面板适应全屏或底部抽屉，隐藏物理快捷键徽章并将行大小调整为至少 44px 高度。
- 按下
Escape或点击背景遮罩会关闭面板并将焦点返回到触发器按钮。