⌘K

⌘K是一个命令菜单React组件，也可以用作可访问的组合框。你渲染项目，它会自动过滤和排序。⌘K支持完全可组合的API如何实现？，因此你可以将项目包装在其他组件中，甚至作为静态JSX。

演示和示例：cmdk.paco.me

安装

pnpm install cmdk

使用

import { Command } from 'cmdk'

const CommandMenu = () => {
  return (
    <Command label="命令菜单">
      <Command.Input />
      <Command.List>
        <Command.Empty>未找到结果。</Command.Empty>

        <Command.Group heading="字母">
          <Command.Item>a</Command.Item>
          <Command.Item>b</Command.Item>
          <Command.Separator />
          <Command.Item>c</Command.Item>
        </Command.Group>

        <Command.Item>苹果</Command.Item>
      </Command.List>
    </Command>
  )
}

或在对话框中：

import { Command } from 'cmdk'

const CommandMenu = () => {
  const [open, setOpen] = React.useState(false)

  // 按下⌘K时切换菜单
  React.useEffect(() => {
    const down = (e) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault()
        setOpen((open) => !open)
      }
    }

    document.addEventListener('keydown', down)
    return () => document.removeEventListener('keydown', down)
  }, [])

  return (
    <Command.Dialog open={open} onOpenChange={setOpen} label="全局命令菜单">
      <Command.Input />
      <Command.List>
        <Command.Empty>未找到结果。</Command.Empty>

        <Command.Group heading="字母">
          <Command.Item>a</Command.Item>
          <Command.Item>b</Command.Item>
          <Command.Separator />
          <Command.Item>c</Command.Item>
        </Command.Group>

        <Command.Item>苹果</Command.Item>
      </Command.List>
    </Command.Dialog>
  )
}

部件和样式

所有部件都将属性（包括ref）转发给适当的元素。每个部件都有一个特定的数据属性（以cmdk-开头），可用于样式设置。

Command `[cmdk-root]`

渲染此项以内联显示命令菜单，或使用Dialog在高级上下文中渲染。可以通过value和onValueChange属性进行控制。

注意

值总是使用trim()方法进行修剪。

const [value, setValue] = React.useState('apple')

return (
  <Command value={value} onValueChange={setValue}>
    <Command.Input />
    <Command.List>
      <Command.Item>橙子</Command.Item>
      <Command.Item>苹果</Command.Item>
    </Command.List>
  </Command>
)

你可以提供一个自定义的filter函数，用于对每个项目进行排名。请注意，值将被修剪。

<Command
  filter={(value, search) => {
    if (value.includes(search)) return 1
    return 0
  }}
/>

过滤函数还可以接受第三个参数keywords。关键词作为项目值的别名，也可以影响项目的排名。关键词会被修剪。

<Command
  filter={(value, search, keywords) => {
    const extendValue = value + ' ' + keywords.join(' ')
    if (extendValue.includes(search)) return 1
    return 0
  }}
/>

或者完全禁用过滤和排序：

<Command shouldFilter={false}>
  <Command.List>
    {filteredItems.map((item) => {
      return (
        <Command.Item key={item} value={item}>
          {item}
        </Command.Item>
      )
    })}
  </Command.List>
</Command>

你可以通过设置loop属性使箭头键在列表中循环（当到达末尾时，返回第一个项目）：

<Command loop />

Dialog `[cmdk-dialog]` `[cmdk-overlay]`

属性转发给Command。组合了Radix UI的Dialog组件。覆盖层始终渲染。有关更多信息，请参阅Radix文档。可以通过open和onOpenChange属性进行控制。

const [open, setOpen] = React.useState(false)

return (
  <Command.Dialog open={open} onOpenChange={setOpen}>
    ...
  </Command.Dialog>
)

你可以提供一个container属性，该属性接受一个HTML元素，并转发给Radix UI的Dialog Portal组件，以指定Dialog应该传送到哪个元素（默认为body）。有关更多信息，请参阅Radix文档。

const containerElement = React.useRef(null)

return (
  <>
    <Command.Dialog container={containerElement.current} />
    <div ref={containerElement} />
  </>
)

Input `[cmdk-input]`

所有属性都转发给底层的input元素。可以通过value和onValueChange属性进行控制。

const [search, setSearch] = React.useState('')

return <Command.Input value={search} onValueChange={setSearch} />

List `[cmdk-list]`

包含项目和组。使用--cmdk-list-height CSS变量来设置高度动画。

[cmdk-list] {
  min-height: 300px;
  height: var(--cmdk-list-height);
  max-height: 500px;
  transition: height 100ms ease;
}

要在视口边缘附近提前滚动项目到视图中，请使用scroll-padding：

[cmdk-list] {
  scroll-padding-block-start: 8px;
  scroll-padding-block-end: 8px;
}

Item `[cmdk-item]` `[data-disabled?]` `[data-selected?]`

在指针进入时变为活动状态的项目。你应该为每个项目提供一个唯一的value，但它会自动从.textContent推断。

<Command.Item
  onSelect={(value) => console.log('已选择', value)}
  // 由于提供的文本内容，值隐含为"apple"
>
  苹果
</Command.Item>

你还可以提供一个keywords属性来帮助过滤。关键词会被修剪。

<Command.Item keywords={['水果', '苹果']}>苹果</Command.Item>

<Command.Item
  onSelect={(value) => console.log('已选择', value)}
  // 由于提供的文本内容，值隐含为"apple"
>
  苹果
</Command.Item>

你可以通过传递forceMount属性强制一个项目始终渲染，而不考虑过滤。

Group `[cmdk-group]` `[hidden?]`

使用给定的heading（[cmdk-group-heading]）将项目分组。

<Command.Group heading="水果">
  <Command.Item>苹果</Command.Item>
</Command.Group>

组不会从DOM中卸载，而是应用hidden属性来隐藏它。这在你的样式中可能相关。

你可以通过传递forceMount属性强制一个组始终渲染，而不考虑过滤。

Separator `[cmdk-separator]`

当搜索查询为空或alwaysRender为true时可见，否则隐藏。

Empty `[cmdk-empty]`

当搜索查询没有结果时自动渲染。

Loading `[cmdk-loading]`

在加载异步项目时，你应该使用progress有条件地渲染此项。

const [loading, setLoading] = React.useState(false)

return <Command.List>{loading && <Command.Loading>请稍候…</Command.Loading>}</Command.List>

`useCommandState(state => state.selectedField)`

组合了useSyncExternalStore的钩子。传递一个返回命令菜单状态切片的函数，以在该切片更改时重新渲染。这个钩子是为高级用例提供的，通常不应使用。

一个很好的用例是渲染更详细的空状态，如下所示：

const search = useCommandState((state) => state.search)
return <Command.Empty>未找到"{search}"的结果。</Command.Empty>

示例

常见用例的代码片段。

嵌套项目

通常选择一个项目应该导航到更深层次，具有更精细的项目集。例如，选择"更改主题…"应该显示新的项目"深色主题"和"浅色主题"。我们将这些项目集称为"页面"，可以通过简单的状态来实现：

const ref = React.useRef(null)
const [open, setOpen] = React.useState(false)
const [search, setSearch] = React.useState('')
const [pages, setPages] = React.useState([])
const page = pages[pages.length - 1]

return (
  <Command
    onKeyDown={(e) => {
      // Escape键返回上一页
      // 当搜索为空时，Backspace键返回上一页
      if (e.key === 'Escape' || (e.key === 'Backspace' && !search)) {
        e.preventDefault()
        setPages((pages) => pages.slice(0, -1))
      }
    }}
  >
    <Command.Input value={search} onValueChange={setSearch} />
    <Command.List>
      {!page && (
        <>
          <Command.Item onSelect={() => setPages([...pages, 'projects'])}>搜索项目…</Command.Item>
          <Command.Item onSelect={() => setPages([...pages, 'teams'])}>加入团队…</Command.Item>
        </>
      )}

      {page === 'projects' && (
        <>
          <Command.Item>项目A</Command.Item>
          <Command.Item>项目B</Command.Item>
        </>
      )}
{页面 === 'teams' && (
        <>
          <Command.Item>团队1</Command.Item>
          <Command.Item>团队2</Command.Item>
        </>
      )}
    </Command.List>
  </Command>
)

搜索时显示子项

如果您的项目有嵌套的子项，只想在搜索时显示，可以根据搜索状态进行渲染：

const SubItem = (props) => {
  const search = useCommandState((state) => state.search)
  if (!search) return null
  return <Command.Item {...props} />
}

return (
  <Command>
    <Command.Input />
    <Command.List>
      <Command.Item>更改主题...</Command.Item>
      <SubItem>更改为深色主题</SubItem>
      <SubItem>更改为浅色主题</SubItem>
    </Command.List>
  </Command>
)

异步结果

在结果可用时渲染项目。过滤和排序将自动进行。

const [loading, setLoading] = React.useState(false)
const [items, setItems] = React.useState([])

React.useEffect(() => {
  async function getItems() {
    setLoading(true)
    const res = await api.get('/dictionary')
    setItems(res)
    setLoading(false)
  }

  getItems()
}, [])

return (
  <Command>
    <Command.Input />
    <Command.List>
      {loading && <Command.Loading>正在获取单词...</Command.Loading>}
      {items.map((item) => {
        return (
          <Command.Item key={`word-${item}`} value={item}>
            {item}
          </Command.Item>
        )
      })}
    </Command.List>
  </Command>
)

在Popover中使用

我们建议使用Radix UI popover组件。⌘K依赖于Radix UI Dialog组件，因此由于共享依赖项，这将略微减少您的包大小。

$ pnpm install @radix-ui/react-popover

在popover内容中渲染Command：

import * as Popover from '@radix-ui/react-popover'

return (
  <Popover.Root>
    <Popover.Trigger>切换弹出框</Popover.Trigger>

    <Popover.Content>
      <Command>
        <Command.Input />
        <Command.List>
          <Command.Item>苹果</Command.Item>
        </Command.List>
      </Command>
    </Popover.Content>
  </Popover.Root>
)