CommandPalette 命令面板

快速搜索并执行操作。

基础用法

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

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[]`	—	必需。展示的条目。
`open`	`boolean`	—	控制面板是否展开。
`defaultOpen`	`boolean`	`false`	面板初始展开状态。
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起时调用。
`onSelect`	`(item: 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) => void`	—	操作失败时调用；命令面板会保留并展示错误。

类型与交互

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

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

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

#CommandPalette 命令面板

#基础用法

#异步操作

#CommandItem

#CommandPalette API

#类型与交互

CommandPalette 命令面板

基础用法

异步操作

CommandItem

CommandPalette API

类型与交互