#命令面板
命令面板让用户通过搜索快速定位并执行操作，适合键盘优先的导航、切换和高频工作流。它应提供可预测的命令名称、清晰的分组与快捷键，而不是承担复杂表单或长篇内容。
最近使用
打开项目⌘O
新建任务⌘N
查看任务队列⌘J
工作区
切换主题⌘⇧L
打开设置⌘,
运行诊断维护中
安装Terminal
npm install @a3s-lab/ui@0.4.0<div class="command border" aria-label="命令菜单">
<header>
<svg aria-hidden="true"><!-- 搜索图标 --></svg>
<input
type="text"
role="combobox"
aria-label="命令搜索"
aria-expanded="true"
aria-controls="project-command-menu"
placeholder="输入命令或搜索…"
/>
</header>
<div id="project-command-menu" role="menu" data-empty="没有匹配结果。">
<div role="group" aria-labelledby="project-command-heading">
<span id="project-command-heading" role="heading">项目</span>
<div role="menuitem" data-filter="打开项目 Open project">打开项目</div>
<div role="menuitem" data-filter="新建任务 New task">新建任务</div>
</div>
</div>
</div>import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";#用法
引入样式
导入 Tailwind 和完整样式包：
@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";拆分导入时，同时包含基础层、命令面板结构与主题样式：
@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/command.css";
@import "@a3s-lab/ui/styles/a3s.css";引入脚本
使用完整运行时：
<script src="/assets/js/all.min.js" defer></script>拆分加载时，同时引入共享运行时和命令面板控制器：
<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/command.min.js" defer></script>添加语义化结构
<div class="command border" aria-label="命令菜单">
<header>
<svg aria-hidden="true"><!-- 搜索图标 --></svg>
<input
type="text"
role="combobox"
aria-label="命令搜索"
aria-expanded="true"
aria-controls="project-command-menu"
placeholder="输入命令或搜索…"
/>
</header>
<div id="project-command-menu" role="menu" data-empty="没有匹配结果。">
<div role="group" aria-labelledby="project-command-heading">
<span id="project-command-heading" role="heading">项目</span>
<div role="menuitem" data-filter="打开项目 Open project">打开项目</div>
<div role="menuitem" data-filter="新建任务 New task">新建任务</div>
</div>
</div>
</div>需要模态命令面板时，将 .command 放进原生 <dialog class="command-dialog">，并为对话框提供可访问名称。
#HTML 结构
<dialog class="command-dialog">可选- 模态命令面板容器。直接子元素应为
.command，并通过aria-label或aria-labelledby提供名称。 <div class="command">命令面板根元素。设置
data-filter="manual"可由应用接管远程搜索或索引过滤。<header>- 搜索图标和输入框的容器。
<input role="combobox">- 命令搜索框。使用
aria-controls指向命令列表，并保持aria-expanded与列表状态一致。 <div role="menu">- 命令列表；通过
data-empty提供本地化的无结果文案。 <div role="group">可选- 组织相关命令；组内全部命令被过滤后会自动隐藏。
<span role="heading">可选- 命令组标题，应由父级的
aria-labelledby引用。 <div role="menuitem">- 可执行操作。导航命令使用
<a role="menuitem">；不可用操作使用aria-disabled="true"。 <span data-shortcut>可选- 位于行尾的快捷键提示。
<hr role="separator">可选- 命令组之间的分隔线；搜索期间会自动隐藏。
#JavaScript API
| API | 类型 | 描述 |
|---|---|---|
command.refresh() | 方法 | 动态添加、移除或重命名命令后，重新扫描当前列表。 |
#示例
#模态命令面板
把高频操作放在前面，并显示可记忆的快捷键。点击遮罩或按 Esc 关闭。
<button type="button" class="btn" data-variant="outline" onclick="document.getElementById('command-dialog-demo').showModal()">打开命令面板</button>
<dialog id="command-dialog-demo" class="command-dialog" aria-label="命令菜单" onclick="if (event.target === this) this.close()">
<div class="command">
<header>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg>
<input type="text" id="command-dialog-input" placeholder="输入命令或搜索…" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="命令搜索" aria-autocomplete="list" role="combobox" aria-expanded="true" aria-controls="command-dialog-menu" />
</header>
<div role="menu" id="command-dialog-menu" data-empty="没有匹配结果。">
<div role="group" aria-labelledby="command-dialog-project">
<span role="heading" id="command-dialog-project">项目</span>
<div role="menuitem" data-filter="打开项目 Open project"><span>打开项目</span><span data-shortcut>⌘O</span></div>
<div role="menuitem" data-filter="新建任务 New task"><span>新建任务</span><span data-shortcut>⌘N</span></div>
<div role="menuitem" data-filter="切换分支 Switch branch"><span>切换分支</span><span data-shortcut>⌘⇧B</span></div>
</div>
<hr role="separator" />
<div role="group" aria-labelledby="command-dialog-view">
<span role="heading" id="command-dialog-view">视图</span>
<div role="menuitem" data-filter="显示终端 Show terminal"><span>显示终端</span><span data-shortcut>⌘J</span></div>
<div role="menuitem" data-filter="切换侧栏 Toggle sidebar"><span>切换侧栏</span><span data-shortcut>⌘B</span></div>
</div>
</div>
</div>
</dialog>#长列表
长列表保持搜索框可见，命令区域独立滚动。分组应反映用户心智模型，避免按技术模块堆砌。
<button type="button" class="btn" data-variant="outline" onclick="document.getElementById('command-scrollable-dialog').showModal()">浏览全部命令</button>
<dialog id="command-scrollable-dialog" class="command-dialog" aria-label="全部命令" onclick="if (event.target === this) this.close()">
<div class="command">
<header>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg>
<input type="text" id="command-scrollable-input" placeholder="搜索全部命令…" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="命令搜索" aria-autocomplete="list" role="combobox" aria-expanded="true" aria-controls="command-scrollable-menu" />
</header>
<div role="menu" id="command-scrollable-menu" data-empty="没有匹配结果。">
<div role="group" aria-labelledby="command-navigation"><span role="heading" id="command-navigation">导航</span><div role="menuitem" data-filter="首页 Home">首页</div><div role="menuitem" data-filter="收件箱 Inbox">收件箱</div><div role="menuitem" data-filter="项目 Projects">项目</div><div role="menuitem" data-filter="设置 Settings">设置</div></div>
<hr role="separator" />
<div role="group" aria-labelledby="command-actions"><span role="heading" id="command-actions">操作</span><div role="menuitem" data-filter="新建文件 New file">新建文件</div><div role="menuitem" data-filter="新建文件夹 New folder">新建文件夹</div><div role="menuitem" data-filter="创建副本 Duplicate">创建副本</div><div role="menuitem" data-filter="移动到 Move to">移动到…</div></div>
<hr role="separator" />
<div role="group" aria-labelledby="command-tools"><span role="heading" id="command-tools">工具</span><div role="menuitem" data-filter="打开终端 Open terminal">打开终端</div><div role="menuitem" data-filter="查看日志 View logs">查看日志</div><div role="menuitem" data-filter="运行检查 Run checks">运行检查</div><div role="menuitem" data-filter="设备预览 Device preview">设备预览</div></div>
<hr role="separator" />
<div role="group" aria-labelledby="command-account"><span role="heading" id="command-account">账户</span><div role="menuitem" data-filter="个人资料 Profile">个人资料</div><div role="menuitem" data-filter="通知 Notifications">通知</div><div role="menuitem" data-filter="退出登录 Sign out">退出登录</div></div>
</div>
</div>
</dialog>#RTL
将 dir="rtl" 添加到命令根元素或祖先；标题、输入与快捷键会随文档方向重新排列。
التنقل
فتح المشروع⌘O
مهمة جديدة⌘N
فتح الإعدادات⌘,
<div dir="rtl">
<div id="command-rtl" class="command border" aria-label="قائمة الأوامر">
<header>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></svg>
<input type="text" id="command-rtl-input" placeholder="اكتب أمرًا أو ابحث…" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="بحث الأوامر" aria-autocomplete="list" role="combobox" aria-expanded="true" aria-controls="command-rtl-menu" />
</header>
<div role="menu" id="command-rtl-menu" data-empty="لم يتم العثور على نتائج.">
<div role="group" aria-labelledby="command-rtl-navigation">
<span role="heading" id="command-rtl-navigation">التنقل</span>
<div role="menuitem" data-filter="فتح المشروع"><span>فتح المشروع</span><span data-shortcut>⌘O</span></div>
<div role="menuitem" data-filter="مهمة جديدة"><span>مهمة جديدة</span><span data-shortcut>⌘N</span></div>
<div role="menuitem" data-filter="فتح الإعدادات"><span>فتح الإعدادات</span><span data-shortcut>⌘,</span></div>
</div>
</div>
</div>
</div>