> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/command-palette.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# CommandPalette 命令面板

快速搜索并执行操作。

## 基础用法


搜索命令 · Ctrl/Cmd K

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/command-palette/basic.tsx"
import { Button, CommandPalette, useMessage } from '@ifhover/leaf-ui';

import { FilePlus2, Search, Settings } from 'lucide-react';

import { useState } from 'react';

export function CommandPaletteBasic() {
  const [open, setOpen] = useState(false);
  const { message } = useMessage();
  return (
    <>
      <Button startIcon={<Search size={16} />} variant="outline" onClick={() => setOpen(true)}>
        {'搜索命令 · Ctrl/Cmd K'}
      </Button>
      <CommandPalette
        open={open}
        onOpenChange={setOpen}
        items={[
          {
            key: 'create',
            label: '新建项目',
            icon: <FilePlus2 size={17} />,
            group: '项目',
            keywords: 'new add',
            onSelect: () => {
              message.success('项目已创建');
            },
          },
          {
            key: 'settings',
            label: '设置',
            icon: <Settings size={17} />,
            group: '工作区',
            shortcut: 'G S',
            onSelect: () => {
              message.info('打开设置');
            },
          },
        ]}
      />
    </>
  );
}
```

展开代码

## 异步操作


异步操作反馈

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/command-palette/basic.tsx"
import { Button, CommandPalette } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function CommandPaletteFailure() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        {'异步操作反馈'}
      </Button>
      <CommandPalette
        shortcut={false}
        open={open}
        onOpenChange={setOpen}
        items={[
          {
            key: 'sync',
            label: '同步项目',
            onSelect: async () => {
              throw new Error(
                '连接暂不可用，请重试。',
              );
            },
          },
        ]}
      />
    </>
  );
}
```

展开代码

## CommandItem

| 属性         | 类型                            | 默认值 | 说明            |
| ---------- | ----------------------------- | --- | ------------- |
| `key`      | `string`                      | —   | 必需。稳定且唯一的标识。  |
| `label`    | `ReactNode`                   | —   | 必需。展示文字或内容。   |
| `keywords` | `string`                      | —   | 搜索匹配的额外关键词。   |
| `group`    | `ReactNode`                   | —   | 条目的分组标题。      |
| `icon`     | `ReactNode`                   | —   | 图标内容。         |
| `shortcut` | `string`                      | —   | 展示在条目旁的快捷键提示。 |
| `disabled` | `boolean`                     | —   | 禁用交互。         |
| `onSelect` | `() => void \| Promise<void>` | —   | 条目被选择时调用。     |

## CommandPalette API

| 属性             | 类型                                                                | 默认值     | 说明                                |
| -------------- | ----------------------------------------------------------------- | ------- | --------------------------------- |
| `items`        | `readonly `[`CommandItem`](#commanditem)`[]`                      | —       | 必需。展示的条目。                         |
| `open`         | `boolean`                                                         | —       | 控制面板是否展开。                         |
| `defaultOpen`  | `boolean`                                                         | `false` | 面板初始展开状态。                         |
| `onOpenChange` | `(open: boolean) => void`                                         | —       | 面板展开或收起时调用。                       |
| `onSelect`     | `(item: `[`CommandItem`](#commanditem)`) => void`                 | —       | 条目被选择时调用。                         |
| `shortcut`     | `string \| false`                                                 | `'k'`   | 使用 Ctrl/Cmd 与该按键打开面板；false 禁用快捷键。 |
| `placeholder`  | `string`                                                          | —       | 设置 placeholder。                   |
| `loading`      | `boolean`                                                         | —       | 展示加载状态。                           |
| `emptyContent` | `ReactNode`                                                       | —       | 没有内容时的展示。                         |
| `onSearch`     | `(query: string) => void`                                         | —       | 搜索文字改变时调用。                        |
| `onError`      | `(error: unknown, item: `[`CommandItem`](#commanditem)`) => void` | —       | 操作失败时调用；命令面板会保留并展示错误。             |

## 类型与交互

组装可复用配置时，可导入对应的属性和数据类型。

```ts
import type { CommandItem, CommandPaletteProps } from '@ifhover/leaf-ui';
```

为仅展示图标的操作提供可访问名称。交互控件支持键盘操作，并跟随 ConfigProvider 的主题和减少动画设置。