# 命令面板

按快捷键或点按钮弹出的搜索框：输入几个字就能跳到某个页面或执行某个操作。支持模糊匹配（含关键词）、按分组显示、最近使用、键盘上下选择、回车执行。命令用一个数组描述。

**依赖**：`zhaoui.css` 与 `zhaoui.js`（原生 HTML、CSS、JS，不需要框架或 jQuery）。只用核心包时，还要加 `modular/command.min.js` 和 `modular/command.min.css`；全量版已包含。

## 用法

```html
<button class="zh-btn" id="cmd-open"><i data-i="search"></i>搜索 <span class="zh-kbd">Ctrl</span><span class="zh-kbd">K</span></button>
<script>
  var palette = ZhaoUI.commandPalette({
    hotkey: true,
    commands: [
      { id: 'home', group: '页面', label: '概览', icon: 'layout-dashboard', keywords: 'home dashboard 首页' },
      { id: 'set', group: '页面', label: '系统设置', icon: 'settings', keywords: 'settings 偏好' },
      { id: 'new', group: '操作', label: '新建文章', icon: 'file-text', hint: 'N', run: function () { ZhaoUI.message('新建文章'); } }
    ]
  });
  document.getElementById('cmd-open').addEventListener('click', function (e) { palette.open(e.currentTarget); });
</script>
```

## 样式类

`zh-cmd`、`zh-cmd-input`、`zh-cmd-list`、`zh-cmd-item`、`zh-cmd-gl`、`zh-cmd-hint`、`zh-cmd-empty`、`zh-cmd-foot`

## 方法

- `ZhaoUI.commandPalette(options)`：创建面板，返回 { open(from), close(), setCommands(list), el }。open 的参数是触发元素，关闭后焦点回到它
- `options`：hotkey 为 true 时 Ctrl/⌘+K 打开或关闭（默认不开，避免和你的页面快捷键冲突）；recent 是“最近”分组的条数，0 则不显示；onRun(command) 在命令执行后调用
- `命令 command`：label 参与匹配并高亮命中的字；keywords 是额外的搜索词（可写拼音、英文、同义词）；group 是分组标题；hint 显示快捷键提示；run(command) 是要执行的函数

## 事件

| 事件 | 触发于 | detail | 说明 |
|---|---|---|---|
| `zh:command-run` | 面板元素（冒泡） | undefined | 执行了某个命令 |

## 无障碍

- 面板是模态 <dialog>，焦点被限制在里面，Esc 或点击外部关闭，关闭后焦点回到触发元素
- 输入框是 combobox，列表是 listbox，当前项用 aria-activedescendant 指示
- 结果数量通过 role=status 区域读出
- 搜索框按钮的 aria-label 里写明快捷键，如“搜索，快捷键 Ctrl K”

## 常见问题

### 命令面板是什么？

按快捷键或点按钮弹出的搜索框：输入几个字就能跳到某个页面或执行某个操作。支持模糊匹配（含关键词）、按分组显示、最近使用、键盘上下选择、回车执行。命令用一个数组描述。

### 怎么使用命令面板？

先在页面里引入 zhaoui.css 和 zhaoui.js（放在 </body> 前，不加 defer），再照本页「用法」里的标记书写；需要用代码控制时，用「方法」里列出的接口。

### 命令面板有哪些事件？

zh:command-run（执行了某个命令）。

### 命令面板有哪些方法？

ZhaoUI.commandPalette(options)：创建面板，返回 { open(from), close(), setCommands(list), el }。open 的参数是触发元素，关闭后焦点回到它；options：hotkey 为 true 时 Ctrl/⌘+K 打开或关闭（默认不开，避免和你的页面快捷键冲突）；recent 是“最近”分组的条数，0 则不显示；onRun(command) 在命令执行后调用；命令 command：label 参与匹配并高亮命中的字；keywords 是额外的搜索词（可写拼音、英文、同义词）；group 是分组标题；hint 显示快捷键提示；run(command) 是要执行的函数。

### 命令面板支持键盘和读屏吗？

面板是模态 <dialog>，焦点被限制在里面，Esc 或点击外部关闭，关闭后焦点回到触发元素；输入框是 combobox，列表是 listbox，当前项用 aria-activedescendant 指示；结果数量通过 role=status 区域读出。

### 命令面板需要依赖框架吗？

不需要。ZhaoUI 是原生 HTML、CSS 和 JavaScript，不依赖 jQuery、Vue 或 React。