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
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| ariaLabel | string | "" | Accessible name for the dialog. |
| emptyText | string | "输入关键字搜索" | Shown when `query` is empty (a hint / "recent"). |
| highlight | boolean | true | Highlight the query terms in the default item render. Default `true`. |
| items | readonly 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. |
| loading | boolean | false | Async search in flight → a loading state instead of the no-result text. |
| noResultText | string | "无结果" | Shown when `query` is non-empty but there are no results. |
| open | boolean | false | |
| placeholder | string | "搜索…" | |
| query | string | "" | |
| shortcut | string | boolean | true | Global open shortcut. `true` (default) = ⌘K / Ctrl-K; a single-char string sets a custom key (still with meta/ctrl); `false` disables it. |
事件
| 事件 | 回调参数 | 说明 |
|---|---|---|
| select | item: KunCommandItem | The item the user activated. A disabled item never emits. |
| submit | query: string | Enter 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:open | value: boolean | |
| update:query | value: string |
插槽
| 插槽 | 作用域 |
|---|---|
| #empty | — |
| #footer | — |
| #item | { item: KunCommandItem; active: boolean; index: number; highlight: (text: string) => string; } |
| #loading | — |
| #no-result | { query: string; } |
| #trigger | { open: () => void; shortcut: string; } |