CommandPalette (命令面板)

通用 ⌘K 命令面板外壳:触发器 + 快捷键、弹层、键盘导航、分组与高亮。搜索逻辑由你提供(v-model:query → items),库负责交互与无障碍。

通用的 ⌘K 命令面板外壳:触发器 + 快捷键、弹层、自动聚焦、body 滚动锁、键盘导航(↑↓/Home/End/Enter/Esc)、分组、安全高亮与无障碍。 它不含搜索逻辑 —— 你用 v-model:query 拿到查询,自己算出 items(扁平或分组),库负责渲染与导航;选中触发 @select

基础用法

静态命令,按 query 过滤并分组。默认 ⌘K / Ctrl K 打开(本页顶部的搜索就是活例;这里的示例关掉了快捷键以免和它冲突,改用按钮触发)。

选中:—
Basic.vue

远程搜索(loading)

监听 query 发请求,请求中传 :loading —— 面板显示加载态而非「无结果」。

选中:—
Async.vue

回车提交查询(@submit)

回车落在某一条结果上时照常 @select没有可选中的结果时(无结果,或结果全部 disabled)才触发 @submit,带上去掉首尾空格的 query —— 面板本身不含搜索,这是拿到原始查询去做「全站搜索」的出口。此时回车不会被 preventDefault 吞掉。

想在有结果时也能提交,把动作项排在第 0 位当成一条普通结果 —— 这也是 cmdk(forceMount)、GitHub、Linear 的做法,好处是这个动作看得见、能用鼠标点。

最近一次:—
Submit.vue

属性

属性类型默认值说明
ariaLabelstring""Accessible name for the dialog.
emptyTextstring"输入关键字搜索"Shown when `query` is empty (a hint / "recent").
highlightbooleantrueHighlight the query terms in the default item render. Default `true`.
itemsreadonly KunCommandItem[] | readonly KunCommandGroup<KunCommandItem>[][]Results to show: a flat item list (one unlabelled group) OR grouped. You compute these from `v-model:query` — the shell does no matching itself.
loadingbooleanfalseAsync search in flight → a loading state instead of the no-result text.
noResultTextstring"无结果"Shown when `query` is non-empty but there are no results.
openbooleanfalse
placeholderstring"搜索…"
querystring""
shortcutstring | booleantrueGlobal open shortcut. `true` (default) = ⌘K / Ctrl-K; a single-char string sets a custom key (still with meta/ctrl); `false` disables it.

事件

事件回调参数说明
selectitem: KunCommandItemThe item the user activated. A disabled item never emits.
submitquery: stringEnter with nothing to select — no results, or every result disabled. The shell has no search of its own, so this is the only way a consumer can act on the raw query ("search the whole site for …"). Enter over a real result still selects it; put an action row first if you want one that is visible.
update:openvalue: boolean
update:queryvalue: string

插槽

插槽作用域
#empty
#footer
#item{ item: KunCommandItem; active: boolean; index: number; highlight: (text: string) => string; }
#loading
#no-result{ query: string; }
#trigger{ open: () => void; shortcut: string; }