CommandPalette 命令面板CommandPalette

一个搜索框加一份可以键盘操作的命令列表：让熟练用户不离开键盘就能跳转、执行操作。它是已有功能的捷径，不要把只能从这里进入的功能藏在里面。

基本用法

传一组 CommandItem。相同 group 的归到一组，组的顺序按首次出现。输入时按标签、说明、分组和 keywords 过滤（空格分隔的每个词都要命中）。快捷键只是展示，绑定由你自己做——这个示例绑了 ⌘K / Ctrl+K。

外部过滤、选中后不关闭

filter={false} 时组件不做过滤，结果完全由你按 query 给出（远程搜索就是这样接）；也可以传一个函数自定义匹配。closeOnSelect={false} 让面板在选中后保持打开，适合连续多选。width 改宽度，placeholder / emptyText / label 改文案。

还没有添加成员

规格

外壳: FloatingCard · placement="top" · 不撑满 · 宽 560 · 圆角 24
位置: 离顶边让出 10vh（最多 96px），窄屏贴顶
搜索行: 高 56 · 左右内边距 20
列表: 内边距 12 = 外圆角 24 − 列表项圆角 12；最高 520，超出原生滚动
高亮: 中性浅灰底 · 键盘和指针共用同一个高亮

接口

CommandPalette

属性	类型	默认值	说明
`items`*	`CommandItem[]`	—	命令列表。
`open / defaultOpen`	`boolean`	`false`	开合，受控 / 非受控。快捷键由使用者自己绑。
`onOpenChange`	`(open: boolean) => void`	—	开合变化时。
`query / defaultQuery`	`string`	`''`	搜索词，受控 / 非受控。每次打开会清空。
`onQueryChange`	`(query: string) => void`	—	搜索词变化时。
`filter`	`false \| ((item, query) => boolean)`	—	自定义匹配；false 表示不在组件里过滤。
`onSelect`	`(item: CommandItem) => void`	—	选中一项时（Enter 或点按）。`item.onSelect` 也会被调用。
`closeOnSelect`	`boolean`	`true`	选中后是否关闭。
`placeholder`	`string`	`'搜索命令…'`	搜索框占位文字。
`emptyText`	`ReactNode`	`'没有匹配的结果'`	没有结果时显示的内容。
`label`	`string`	`'命令面板'`	面板和搜索框的读屏名称。
`width`	`number \| string`	`560`	宽度。
`footer`	`ReactNode`	—	列表下面的一行提示（比如按键说明）。
`dismissible`	`boolean`	`true`	允许 Esc 和点遮罩关闭。

CommandItem

属性	类型	默认值	说明
`id`*	`string`	—	唯一标识。
`label`*	`string`	—	命令名。
`description`	`string`	—	标签右边的一句说明。
`icon`	`ReactNode`	—	图标。
`shortcut`	`string[]`	—	快捷键提示，一个键一项，如 ['⌘', 'S']。只是展示。
`keywords`	`string[]`	—	额外的搜索关键词（拼音、英文别名…）。
`group`	`string`	—	分组标题；相同的归到一组。
`disabled`	`boolean`	—	禁用：显示但不能选，键盘移动时跳过。
`onSelect`	`() => void`	—	选中时。

基本用法

外部过滤、选中后不关闭

规格

接口

CommandPalette

CommandItem

无障碍