命令面板

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

带行为 分包 modular/command 1 个事件 3 个方法

示例

在线试用 Markdown 版

代码

<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>

只用核心包（modular/core）时，还要加 modular/command.min.js 和 modular/command.min.css；全量版已包含。见 按需引入。

事件

方法

• 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) 是要执行的函数

样式类

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

无障碍

• 面板是模态 <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。