Command 命令面板

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

预览

Preview

基础用法

命令对话框

程序化控制（filterSearch）

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

安装

pnpm dlx brutx-vue@latest add command

用法

vue

<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 会自动显示；当某个分组内所有项目都被过滤掉时，该分组会自动隐藏。

vue

<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 的内部搜索过滤，避免双重过滤冲突：

vue

<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 组合搜索框、分组结果、最近搜索和加载状态。

vue

<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 实现模态命令面板：

vue

<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` 构建
`CommandEmpty`	无匹配结果时显示
`CommandGroup`	带标题的分组区域，过滤为空时自动隐藏
`CommandItem`	可选项，基于 `ListboxItem` 构建，支持 `@select` 事件
`CommandSeparator`	分组之间的视觉分隔线
`CommandShortcut`	键盘快捷键提示

程序化控制

Command 通过 defineExpose 暴露 filterSearch 响应式引用，允许父组件程序化读取或设置搜索关键词，从而在不依赖 CommandInput 的情况下触发项目过滤。

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

vue

<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

方法/属性	类型	说明
`filterSearch`	`Ref<string>`	当前搜索关键词，可读写；写入后会触发内部过滤逻辑（需 `disableFilter` 为 `false`）

Props

Command

属性	类型	默认值	说明
`disableFilter`	`boolean`	`false`	禁用内部搜索过滤，适用于外部自行过滤的场景
`class`	`string`	—	自定义 CSS 类名

CommandInput

属性	类型	默认值	说明
`modelValue`	`string`	—	输入框的值，支持 `v-model`
`placeholder`	`string`	`t('command.placeholder')`	占位符文本
`class`	`string`	—	自定义 CSS 类名

CommandItem

属性	类型	默认值	说明
`value`	`string`	—	项目的唯一标识值
`disabled`	`boolean`	—	是否禁用该项目
`class`	`string`	—	自定义 CSS 类名

CommandGroup

属性	类型	默认值	说明
`title`	`string`	—	分组标题文本
`class`	`string`	—	自定义 CSS 类名

CommandList

属性	类型	默认值	说明
`class`	`string`	—	自定义 CSS 类名

CommandEmpty

属性	类型	默认值	说明
`class`	`string`	—	自定义 CSS 类名

CommandSeparator

属性	类型	默认值	说明
`class`	`string`	—	自定义 CSS 类名

CommandShortcut

属性	类型	默认值	说明
`class`	`string`	—	自定义 CSS 类名

CommandDialog

属性	类型	默认值	说明
`open`	`boolean`	`false`	对话框是否打开，支持 `v-model:open`
`title`	`string`	`t('command.dialogTitle')`	对话框标题（无障碍访问用）
`description`	`string`	`t('command.dialogDescription')`	对话框描述（无障碍访问用）
`class`	`string`	—	自定义 CSS 类名

事件

CommandInput

事件	参数	说明
`update:modelValue`	`string`	输入值变化时触发

CommandItem

事件	参数	说明
`select`	`string`	选中项目时触发

CommandDialog

事件	参数	说明
`update:open`	`boolean`	对话框开关状态变化时触发

插槽

组件	插槽	说明
`Command`	`default`	用于放置 `CommandInput`、`CommandList` 等子组件
`CommandDialog`	`default`	用于放置 `CommandInput`、`CommandList` 等子组件
`CommandList`	`default`	用于放置 `CommandEmpty`、`CommandGroup` 等子组件
`CommandGroup`	`default`	用于放置 `CommandItem` 子组件
`CommandItem`	`default`	用于放置项目内容和 `CommandShortcut`
`CommandEmpty`	`default`	自定义无匹配结果时的显示内容，默认值为 `t('command.emptyText')`
`CommandShortcut`	`default`	用于放置快捷键文本

可访问性

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

Command 命令面板 ​

预览 ​

基础用法

命令对话框

程序化控制（filterSearch）

安装 ​

用法 ​

搜索过滤 ​

禁用内部过滤 ​

搜索组件 recipe ​

命令对话框 ​

子组件 ​

程序化控制 ​

暴露的 API ​

Props ​

Command ​

CommandInput ​

CommandItem ​

CommandGroup ​

CommandList ​

CommandEmpty ​

CommandSeparator ​

CommandShortcut ​

CommandDialog ​

事件 ​

CommandInput ​

CommandItem ​

CommandDialog ​

插槽 ​

可访问性 ​

Command 命令面板

预览

安装

用法

搜索过滤

禁用内部过滤

搜索组件 recipe

命令对话框

子组件

程序化控制

暴露的 API

Props

Command

CommandInput

CommandItem

CommandGroup

CommandList

CommandEmpty

CommandSeparator

CommandShortcut

CommandDialog

事件

CommandInput

CommandItem

CommandDialog

插槽

可访问性