Command 命令面板

新粗野主义风格的命令面板组件，用于搜索和导航。基于 reka-ui 的 Listbox 原语构建，内置搜索过滤功能。

预览

Preview

基础用法

未找到结果。

建议

日历

搜索表情

计算器

---

设置

个人资料 ⌘P

账单 ⌘B

设置 ⌘S

命令对话框

程序化控制（filterSearch）

通过 ref 写入 filterSearch 可在不操作输入框的情况下触发过滤。

未找到结果。

建议

日历

搜索表情

计算器

---

设置

个人资料

设置

安装

pnpm dlx brutx-vue@latest add command

用法

<script setup>
import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut } from 'brutx-ui-vue'
</script>

<template>
    <Command>
        <CommandInput placeholder="Type a command or search..." />
        <CommandList>
            <CommandEmpty>No results found.</CommandEmpty>
            <CommandGroup title="Suggestions">
                <CommandItem value="calendar">Calendar</CommandItem>
                <CommandItem value="search">Search Emoji</CommandItem>
                <CommandItem value="calculator">Calculator</CommandItem>
            </CommandGroup>
            <CommandSeparator />
            <CommandGroup title="Settings">
                <CommandItem value="profile">
                    Profile
                    <CommandShortcut>⌘P</CommandShortcut>
                </CommandItem>
                <CommandItem value="billing">
                    Billing
                    <CommandShortcut>⌘B</CommandShortcut>
                </CommandItem>
                <CommandItem value="settings">
                    Settings
                    <CommandShortcut>⌘S</CommandShortcut>
                </CommandItem>
            </CommandGroup>
        </CommandList>
    </Command>
</template>

搜索过滤

CommandInput 输入的文本会自动过滤 CommandItem，匹配逻辑基于项目文本内容。当所有项目都被过滤掉时，CommandEmpty 会自动显示；当某个分组内所有项目都被过滤掉时，该分组会自动隐藏。

<Command>
    <CommandInput />
    <CommandList>
        <CommandEmpty />
        <CommandGroup title="Suggestions">
            <CommandItem value="calendar">Calendar</CommandItem>
            <CommandItem value="search">Search Emoji</CommandItem>
        </CommandGroup>
        <CommandGroup title="Settings">
            <CommandItem value="profile">Profile</CommandItem>
        </CommandGroup>
    </CommandList>
</Command>

禁用内部过滤

当外部组件自行处理过滤逻辑时（如 Combobox），可使用 disable-filter 禁用 Command 的内部搜索过滤，避免双重过滤冲突：

<Command disable-filter>
    <CommandInput v-model="searchQuery" />
    <CommandList>
        <CommandEmpty />
        <CommandGroup>
            <CommandItem
                v-for="item in filteredItems"
                :key="item.value"
                :value="item.value"
            >
                {{ item.label }}
            </CommandItem>
        </CommandGroup>
    </CommandList>
</Command>

搜索组件 recipe

可直接用 Command disable-filter 组合搜索框、分组结果、最近搜索和加载状态。

<script setup>
import { computed, ref } from 'vue'
import {
    Command,
    CommandInput,
    CommandList,
    CommandEmpty,
    CommandGroup,
    CommandItem,
} from 'brutx-ui-vue'

const query = ref('')
const suggestions = [
    { label: 'Button 按钮', value: 'button', group: '组件' },
    { label: '主题配置', value: 'theming', group: '文档' },
]

const filteredItems = computed(() =>
    suggestions.filter(item => item.label.toLowerCase().includes(query.value.toLowerCase()))
)
</script>

<template>
    <Command disable-filter class="w-full max-w-lg border-3 border-brutal shadow-brutal">
        <CommandInput v-model="query" placeholder="搜索组件或文档..." />
        <CommandList>
            <CommandEmpty />
            <CommandGroup title="搜索结果">
                <CommandItem v-for="item in filteredItems" :key="item.value" :value="item.value">
                    {{ item.label }}
                </CommandItem>
            </CommandGroup>
        </CommandList>
    </Command>
</template>

命令对话框

使用 CommandDialog 实现模态命令面板。注意 CommandDialog 是完全受控组件：必须绑定 v-model:open（或监听 update:open），否则用户操作（如 Escape / 点击遮罩）不会改变开合状态。

<script setup>
import { ref } from 'vue'
import { CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem } from 'brutx-ui-vue'

const open = ref(false)
</script>

<template>
    <button @click="open = true">Open Command Palette</button>
    <CommandDialog v-model:open="open">
        <CommandInput placeholder="Type a command..." />
        <CommandList>
            <CommandEmpty />
            <CommandGroup title="Actions">
                <CommandItem value="new">New File</CommandItem>
                <CommandItem value="open">Open File</CommandItem>
            </CommandGroup>
        </CommandList>
    </CommandDialog>
</template>

子组件

组件	说明
Command	根容器，管理过滤状态，基于 ListboxRoot 构建
CommandDialog	模态对话框包装器，基于 DialogRoot 构建
CommandInput	搜索输入框，输入时自动过滤项目
CommandList	可滚动列表容器，基于 ListboxContent 构建，必须在 Command 内使用
CommandEmpty	无匹配结果时显示
CommandGroup	带标题的分组区域，过滤为空时自动隐藏
CommandItem	可选项，基于 ListboxItem 构建，支持 @select 事件
CommandSeparator	分组之间的视觉分隔线
CommandShortcut	键盘快捷键提示

程序化控制

Command 通过 defineExpose 暴露 filterSearch 响应式引用，允许父组件程序化读取或设置搜索关键词，从而在不依赖 CommandInput 的情况下触发项目过滤。当内部存在 CommandInput 时，外部写入 filterSearch 会同步回显到输入框；若写入的值与输入框当前显示不一致，还会同步触发 CommandInput 的 update:modelValue 事件，保证父组件 v-model 与输入框显示一致（父组件 v-model 驱动的回写不会重复触发该事件，无回环）。

注意：仅当内部过滤启用时（即未设置 disable-filter）写入 filterSearch 才会触发过滤逻辑；disable-filter 为 true 时内部过滤被禁用，写入不会影响项目显示。

<script setup>
import { ref } from 'vue'
import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem } from 'brutx-ui-vue'

const commandRef = ref()
</script>

<template>
    <Command ref="commandRef">
        <CommandInput />
        <CommandList>
            <CommandEmpty />
            <CommandGroup title="建议">
                <CommandItem value="calendar">日历</CommandItem>
                <CommandItem value="search">搜索表情</CommandItem>
                <CommandItem value="calculator">计算器</CommandItem>
            </CommandGroup>
        </CommandList>
    </Command>

    <button @click="commandRef?.filterSearch = 'cal'">外部触发搜索 "cal"</button>
    <button @click="commandRef?.filterSearch = ''">清除搜索</button>
</template>

API 参考

Command

Command — 属性

名称	类型	默认值	说明
class 可空	ClassValue	undefined	追加到命令列表根容器的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 声明 undefined 来源: packages/ui/src/components/command/Command.vue 解析值 undefined 来源 Command.vue:9 packages/ui/src/components/command/Command.vue
disableFilter	boolean | undefined	false	关闭组件内部的条目文本过滤；适用于外部自行过滤列表的场景。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/command/Command.vue 解析值 false 来源 Command.vue:10 packages/ui/src/components/command/Command.vue

Command — 插槽

名称	签名或类型	说明
#default	{}	放置命令输入框、列表、分组和条目等子组件。
详情 声明类型 {} 来源 Command.vue packages/ui/src/components/command/Command.vue

Command — 暴露成员

名称	签名或类型	说明
filterSearch	string	当前共享搜索关键词。写入新字符串会更新内部匹配状态；disableFilter 为 true 时不隐藏不匹配条目。
详情 声明类型 string 来源 Command.vue:79 packages/ui/src/components/command/Command.vue

CommandDialog

CommandDialog — 属性

名称	类型	默认值	说明
open	boolean | undefined	false	对话框当前开合状态。组件完全受控，需通过 v-model:open 或监听 update:open 更新该值。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/command/CommandDialog.vue 解析值 false 来源 CommandDialog.vue:19 packages/ui/src/components/command/CommandDialog.vue
title	string | undefined	undefined 运行时回退:命令面板	命令对话框的无障碍标题；空白或仅空格时回退到本地化标题。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/command/CommandDialog.vue 解析值 undefined 运行时回退 命令面板 组件在说明的运行条件下采用此回退值。 来源 CommandDialog.vue:20 packages/ui/src/components/command/CommandDialog.vue
description	string | undefined	undefined 运行时回退:搜索要运行的命令...	命令对话框的无障碍描述；空白或仅空格时回退到本地化描述。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/command/CommandDialog.vue 解析值 undefined 运行时回退 搜索要运行的命令... 组件在说明的运行条件下采用此回退值。 来源 CommandDialog.vue:21 packages/ui/src/components/command/CommandDialog.vue
class 可空	ClassValue	undefined	追加到对话框内容的 class 值；内部布局类在该值之后合并。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 声明 undefined 来源: packages/ui/src/components/command/CommandDialog.vue 解析值 undefined 来源 CommandDialog.vue:22 packages/ui/src/components/command/CommandDialog.vue

CommandDialog — 事件

名称	签名或类型	说明
@update:open	[value: boolean]	根对话框请求开合状态变化时发出新布尔值；父级仍需更新 open。
详情 声明类型 [value: boolean] 字面量 false true 来源 CommandDialog.vue packages/ui/src/components/command/CommandDialog.vue

CommandDialog — 插槽

名称	签名或类型	说明
#default	{}	放置命令输入框、列表、分组和条目等对话框内容。
详情 声明类型 {} 来源 CommandDialog.vue packages/ui/src/components/command/CommandDialog.vue

CommandEmpty

CommandEmpty — 属性

名称	类型	默认值	说明
class 可空	ClassValue	—	追加到无匹配结果提示段落的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 未声明默认值 — 来源 CommandEmpty.vue:9 packages/ui/src/components/command/CommandEmpty.vue

CommandEmpty — 插槽

名称	签名或类型	说明
#default	{}	自定义搜索结果为空时的提示内容；仅当内部过滤结果数量为零时渲染。未提供内容时使用本地化文本。 默认文案来自 command.emptyText：“未找到结果。”。
详情 声明类型 {} 来源 CommandEmpty.vue packages/ui/src/components/command/CommandEmpty.vue

CommandGroup

CommandGroup — 属性

名称	类型	默认值	说明
title	string | undefined	—	分组标题；提供非空文本时在分组条目之前呈现标题。
详情 声明类型 string | undefined 默认值详情 未声明默认值 — 来源 CommandGroup.vue:9 packages/ui/src/components/command/CommandGroup.vue
class 可空	ClassValue	—	追加到命令分组根元素的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 未声明默认值 — 来源 CommandGroup.vue:10 packages/ui/src/components/command/CommandGroup.vue

CommandGroup — 插槽

名称	签名或类型	说明
#default	{}	放置属于当前命令分组的 CommandItem 子项。
详情 声明类型 {} 来源 CommandGroup.vue packages/ui/src/components/command/CommandGroup.vue

CommandInput

CommandInput — 属性

名称	类型	默认值	说明
modelValue	string | undefined	undefined	命令搜索输入的受控值；未提供时初始读取根 Command 的共享搜索词。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/command/CommandInput.vue 解析值 undefined 来源 CommandInput.vue:12 packages/ui/src/components/command/CommandInput.vue
placeholder	string | undefined	undefined 运行时回退:输入命令或搜索...	输入框占位文本；仅 undefined 或 null 时使用本地化默认值，空字符串会按显式值保留。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/command/CommandInput.vue 解析值 undefined 运行时回退 输入命令或搜索... 组件在说明的运行条件下采用此回退值。 来源 CommandInput.vue:13 packages/ui/src/components/command/CommandInput.vue
class 可空	ClassValue	undefined	追加到原生搜索输入框的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 声明 undefined 来源: packages/ui/src/components/command/CommandInput.vue 解析值 undefined 来源 CommandInput.vue:14 packages/ui/src/components/command/CommandInput.vue

CommandInput — 事件

名称	签名或类型	说明
@update:modelValue	[value: string]	用户输入变化时发出新字符串；根 Command 的共享搜索词由外部更改时，也会同步并发出对应值。
详情 声明类型 [value: string] 来源 CommandInput.vue packages/ui/src/components/command/CommandInput.vue

CommandItem

CommandItem — 属性

名称	类型	默认值	说明
value 必填	string	—	命令项的唯一值；初始用于搜索索引，默认插槽渲染后索引会同步为可见文本。
详情 声明类型 string 默认值详情 未声明默认值 — 来源 CommandItem.vue:10 packages/ui/src/components/command/CommandItem.vue
disabled	boolean | undefined	—	将条目禁用并传递给 Reka UI 列表框条目。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 CommandItem.vue:11 packages/ui/src/components/command/CommandItem.vue
class 可空	ClassValue	—	追加到命令条目根元素的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 未声明默认值 — 来源 CommandItem.vue:12 packages/ui/src/components/command/CommandItem.vue

CommandItem — 事件

名称	签名或类型	说明
@select	[value: string]	条目被选中时发出其 value 字符串。
详情 声明类型 [value: string] 来源 CommandItem.vue packages/ui/src/components/command/CommandItem.vue

CommandItem — 插槽

名称	签名或类型	说明
#default	{}	呈现命令项内容；渲染后的可见文本可作为搜索匹配文本。
详情 声明类型 {} 来源 CommandItem.vue packages/ui/src/components/command/CommandItem.vue

CommandList

CommandList — 属性

名称	类型	默认值	说明
class 可空	ClassValue	—	追加到 Reka UI 列表框内容元素的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 未声明默认值 — 来源 CommandList.vue:14 packages/ui/src/components/command/CommandList.vue
asChild	boolean | undefined	—	让列表框内容与唯一子元素合并，由子元素作为最终渲染节点。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 CommandList.vue packages/ui/src/components/command/CommandList.vue
as	AsTag | Component | undefined	—	指定列表框内容渲染为的元素或组件；asChild 可覆盖该选择。
详情 声明类型 AsTag | Component | undefined 字面量 "a" "button" "div" "form" "h2" "h3" "img" "input" "label" "li" "nav" "ol" "p" "span" "svg" "template" "ul" 默认值详情 未声明默认值 — 来源 CommandList.vue packages/ui/src/components/command/CommandList.vue

CommandList — 插槽

名称	签名或类型	说明
#default	{}	放置 CommandEmpty、CommandGroup 等列表内容。
详情 声明类型 {} 来源 CommandList.vue packages/ui/src/components/command/CommandList.vue

CommandSeparator

CommandSeparator — 属性

名称	类型	默认值	说明
class 可空	ClassValue	—	追加到命令分隔线根元素的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 未声明默认值 — 来源 CommandSeparator.vue:7 packages/ui/src/components/command/CommandSeparator.vue

CommandShortcut

CommandShortcut — 属性

名称	类型	默认值	说明
class 可空	ClassValue	—	追加到快捷键提示元素的 class 值。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 未声明默认值 — 来源 CommandShortcut.vue:7 packages/ui/src/components/command/CommandShortcut.vue

CommandShortcut — 插槽

名称	签名或类型	说明
#default	{}	呈现与命令项关联的快捷键提示文本。
详情 声明类型 {} 来源 CommandShortcut.vue packages/ui/src/components/command/CommandShortcut.vue

可访问性

• 键盘操作：支持 ↑ / ↓ 上下移动焦点，Enter 选中当前项，Escape 关闭对话框（CommandDialog 内）
• ARIA 属性：CommandDialog 支持 title 和 description 属性用于无障碍访问
• 焦点管理：打开对话框时焦点锁定在组件内，关闭时恢复焦点