Command 命令面板

可搜索的命令面板，用于快速导航和操作，支持键盘操作和弹窗模式。

?

名称	分类	说明	类型	默认值
maxHeight	? 风格	列表最大高度	string	'300px'
disabled	? 状态	是否禁用	boolean	false
modelValue / v-model	? 状态	是否打开弹窗	boolean	false
filter	? 行为	自定义过滤函数	(value: string, search: string, keywords?: string[]) => boolean	—
shortcut	? 行为	启用 Ctrl+K 快捷键	boolean	true
ArrowDown	? 行为	高亮下一项		—
ArrowUp	? 行为	高亮上一项		—
Enter	? 行为	选择高亮项		—
Escape	? 行为	关闭弹窗		—
Ctrl+K / Cmd+K	? 行为	切换命令面板弹窗		—
modelValue / v-model	? 内容	搜索文本	string	''
label	? 内容	aria-label 标签	string	—
placeholder	? 内容	输入框占位文本	string	''
icon	? 内容	搜索图标名称	string	'search'
value	? 内容	项目唯一值（必填）	string	—
keywords	? 内容	额外的搜索关键词	string[]	[]
icon	? 内容	项目图标	string	—
shortcut	? 内容	快捷键标签	string[]	[]
heading	? 内容	分组标题	string	—
update:modelValue	? 事件	搜索文本变更时触发	(value: string) => void	—
select	? 事件	选择项目时触发	(value: string) => void	—
update:modelValue	? 事件	弹窗状态变更时触发	(value: boolean) => void	—
open	? 事件	弹窗打开时触发	() => void	—
close	? 事件	弹窗关闭时触发	() => void	—

基础用法

一个简单的命令菜单，支持搜索过滤。

<template>
  <px-command label="Command menu">
    <px-command-input placeholder="Type a command or search..." />
    <px-command-list>
      <px-command-empty>No results found.</px-command-empty>
      <px-command-item value="calendar" icon="calendar">Calendar</px-command-item>
      <px-command-item value="search" icon="search">Search</px-command-item>
      <px-command-item value="settings" icon="settings">Settings</px-command-item>
      <px-command-item value="profile" icon="user">Profile</px-command-item>
    </px-command-list>
  </px-command>
</template>

<style scoped>
.px-command {
  max-width: 480px;
}
</style>

分组项目

使用 CommandGroup 按标题组织项目，使用 CommandSeparator 添加视觉分隔线。

<template>
  <px-command label="Grouped command menu">
    <px-command-input placeholder="Search commands..." />
    <px-command-list>
      <px-command-empty>No results found.</px-command-empty>
      <px-command-group heading="Navigation">
        <px-command-item value="home" icon="home">Home</px-command-item>
        <px-command-item value="dashboard" icon="analytics">Dashboard</px-command-item>
        <px-command-item value="settings" icon="settings">Settings</px-command-item>
      </px-command-group>
      <px-command-separator />
      <px-command-group heading="Actions">
        <px-command-item value="new-file" icon="add-box">New File</px-command-item>
        <px-command-item value="upload" icon="upload">Upload</px-command-item>
        <px-command-item value="download" icon="download">Download</px-command-item>
      </px-command-group>
    </px-command-list>
  </px-command>
</template>

<style scoped>
.px-command {
  max-width: 480px;
}
</style>

弹窗模式

使用 CommandDialog 在模态弹窗中显示命令面板。按 Ctrl+K（Mac 上为 Cmd+K）切换。

<template>
  <div>
    <px-button type="primary" @click="open = true">
      Open Command Palette
      <px-badge size="small" type="info">Ctrl+K</px-badge>
    </px-button>

    <px-command-dialog v-model="open">
      <px-command @select="onSelect" label="Command palette">
        <px-command-input placeholder="What do you need?" />
        <px-command-list>
          <px-command-empty>No results found.</px-command-empty>
          <px-command-group heading="Pages">
            <px-command-item value="home" icon="home" :shortcut="['Ctrl', 'H']">Home</px-command-item>
            <px-command-item value="docs" icon="bookmark" :shortcut="['Ctrl', 'D']">Documentation</px-command-item>
          </px-command-group>
          <px-command-separator />
          <px-command-group heading="Theme">
            <px-command-item value="light" icon="sun">Light Mode</px-command-item>
            <px-command-item value="dark" icon="moon">Dark Mode</px-command-item>
          </px-command-group>
        </px-command-list>
      </px-command>
    </px-command-dialog>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const open = ref(false);

function onSelect() {
  open.value = false;
}
</script>

自定义过滤

提供自定义 filter 函数进行高级匹配（例如模糊搜索）。

<template>
  <px-command :filter="fuzzyFilter" label="Custom filter">
    <px-command-input placeholder="Try fuzzy search..." />
    <px-command-list>
      <px-command-empty>No matches.</px-command-empty>
      <px-command-item value="calendar">Calendar</px-command-item>
      <px-command-item value="calculator">Calculator</px-command-item>
      <px-command-item value="contacts">Contacts</px-command-item>
      <px-command-item value="configuration">Configuration</px-command-item>
    </px-command-list>
  </px-command>
</template>

<script setup lang="ts">
function fuzzyFilter(value: string, search: string): boolean {
  if (!search) return true;
  const chars = search.toLowerCase().split('');
  let idx = 0;
  for (const char of value.toLowerCase()) {
    if (char === chars[idx]) idx++;
    if (idx === chars.length) return true;
  }
  return false;
}
</script>

<style scoped>
.px-command {
  max-width: 480px;
}
</style>

禁用项目

设置 disabled 来阻止选择。禁用项目在键盘导航时会被跳过。

<template>
  <px-command label="Command with disabled items">
    <px-command-input placeholder="Search..." />
    <px-command-list>
      <px-command-item value="save" icon="check">Save</px-command-item>
      <px-command-item value="delete" icon="close" disabled>Delete (Disabled)</px-command-item>
      <px-command-item value="export" icon="download">Export</px-command-item>
      <px-command-item value="archive" icon="archive" disabled>Archive (Disabled)</px-command-item>
    </px-command-list>
  </px-command>
</template>

<style scoped>
.px-command {
  max-width: 480px;
}
</style>