CommandPalette 命令面板

搜索并执行命令的浮层面板

已验证自 0.3.4

用法

启动器

示例加载中...

最佳实践

id 跨版本保持稳定；埋点、持久化与权限判断都用 id，不用本地化标题。
同义词、别名、插件名放进 keywords，不要为搜索变体复制命令。
全局快捷键在应用外壳注册，再通过 v-model 打开面板。
footer 放数据来源、结果数或键盘帮助；empty 展示当前 query 与恢复动作。
命令较多时限制 maxHeight，让面板留在视口内。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`boolean`	-	是否显示，配合 `v-model` 使用。
`commands`	`CommandPaletteItem[]`	`[]`	命令列表。
`placeholder`	`string`	`'Search commands'`	搜索框占位文本，也是搜索框的 `aria-label`。
`emptyText`	`string`	`'No commands found'`	无匹配时的提示。
`maxHeight`	`number`	`320`	列表最大高度（px）。
`autoFocus`	`boolean`	`true`	打开时聚焦搜索框。
`closeOnSelect`	`boolean`	`true`	选中后关闭；批量操作时设为 `false`。
`overlayClass`	`string \| string[] \| Record<string, boolean>`	-	遮罩层的 class。
`panelClass`	`string \| string[] \| Record<string, boolean>`	-	面板的 class。
`query`	`string`	-	搜索文本，配合 `v-model:query`；不传时由组件自行管理。
`ariaLabel`	`string`	`'Command palette'`	对话框与命令列表的无障碍名称。

事件

事件名	参数	说明
`update:modelValue`	`(value)`	请求打开或关闭时触发。
`select`	`(item)`	选中可用命令时触发，参数为原始条目。
`open`	-	面板打开时触发。
`close`	-	已打开的面板关闭时触发。
`update:query`	`(value)`	输入变化时触发；关闭时重置为空串。

插槽

插槽名	参数	说明
`empty`	`{ query, emptyText }`	无匹配时的内容。
`footer`	`{ query, visibleCount }`	列表下方的区域。

类型

CommandPaletteItem

字段	类型	说明
`id`	`string`	唯一标识。
`title`	`string`	标题，参与过滤。
`description`	`string`	标题下的说明，参与过滤。
`keywords`	`string[]`	参与过滤的额外搜索词，不显示。
`icon`	`TxIconSource \| string`	图标源或图标 class。
`shortcut`	`string`	右侧的快捷键提示；不注册快捷键。
`disabled`	`boolean`	保持可见，但不可选中。

概述

显示状态只由 modelValue 决定。打开时触发 open，从打开变为关闭时触发 close。
过滤是对 title、description、keywords 的本地子串匹配，不区分大小写；组件不排序、不节流、不请求远端。
↑ / ↓ 循环移动并跳过禁用项，Enter 选中，Esc 关闭。高亮初始落在第一个可用命令上。
输入法组合期间不响应键盘选择，避免提前提交中日韩输入。
遮罩层是 role="dialog" 与 aria-modal="true"；禁用项带 aria-disabled="true"，不触发 select。

技术实现

源码：packages/tuffex/packages/components/src/command-palette/。

packages/tuffex/packages/components/src/command-palette/index.ts