---
title: "CommandPalette 命令面板"
description: "搜索并执行命令的浮层面板"
category: Advanced
status: beta
since: 0.3.4
tags: [command, palette, launcher, shortcut]
syncStatus: reviewed
verified: true
---

## 用法

### 启动器
::TuffDemoWrapper{demo="CommandPaletteCommandPaletteDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const open = ref(false)
  const commands = [
    {
      id: 'search-files',
      title: '搜索文件',
      description: '在文档、下载和桌面中查找本地文件',
      keywords: ['file', 'finder', '文件'],
      icon: 'i-carbon-search',
      shortcut: '⌘ K',
    },
    { id: 'locked-admin', title: '管理员脚本', icon: 'i-carbon-locked', disabled: true },
  ]
  </script>

  <template>
    <TxButton variant="primary" @click="open = true">打开命令面板</TxButton>
    <TxCommandPalette
      v-model="open"
      :commands="commands"
      placeholder="搜索命令、插件或设置..."
      empty-text="没有匹配的命令"
      :max-height="280"
      @select="(item) => run(item.id)"
    />
  </template>
---
::

### 最佳实践

- `id` 跨版本保持稳定；埋点、持久化与权限判断都用 `id`，不用本地化标题。
- 同义词、别名、插件名放进 `keywords`，不要为搜索变体复制命令。
- 全局快捷键在应用外壳注册，再通过 `v-model` 打开面板。
- `footer` 放数据来源、结果数或键盘帮助；`empty` 展示当前 query 与恢复动作。
- 命令较多时限制 `maxHeight`，让面板留在视口内。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|------|------|
| `modelValue` | `boolean` | - | 是否显示，配合 `v-model` 使用。 |
| `commands` | `CommandPaletteItem[]` | `[]` | 命令列表。 |
| `placeholder` | `string` | `'Search commands'` | 搜索框占位文本，也是搜索框的 `aria-label`。 |
| `emptyText` | `string` | `'No commands found'` | 无匹配时的提示。 |
| `maxHeight` | `number` | `320` | 列表最大高度（px）。 |
| `autoFocus` | `boolean` | `true` | 打开时聚焦搜索框。 |
| `closeOnSelect` | `boolean` | `true` | 选中后关闭；批量操作时设为 `false`。 |
| `overlayClass` | `string \| string[] \| Record<string, boolean>` | - | 遮罩层的 class。 |
| `panelClass` | `string \| string[] \| Record<string, boolean>` | - | 面板的 class。 |
| `query` | `string` | - | 搜索文本，配合 `v-model:query`；不传时由组件自行管理。 |
| `ariaLabel` | `string` | `'Command palette'` | 对话框与命令列表的无障碍名称。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(value)` | 请求打开或关闭时触发。 |
| `select` | `(item)` | 选中可用命令时触发，参数为原始条目。 |
| `open` | - | 面板打开时触发。 |
| `close` | - | 已打开的面板关闭时触发。 |
| `update:query` | `(value)` | 输入变化时触发；关闭时重置为空串。 |

### 插槽

| 插槽名 | 参数 | 说明 |
|------|------|------|
| `empty` | `{ query, emptyText }` | 无匹配时的内容。 |
| `footer` | `{ query, visibleCount }` | 列表下方的区域。 |

### 类型

#### CommandPaletteItem

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `string` | 唯一标识。 |
| `title` | `string` | 标题，参与过滤。 |
| `description` | `string` | 标题下的说明，参与过滤。 |
| `keywords` | `string[]` | 参与过滤的额外搜索词，不显示。 |
| `icon` | `TxIconSource \| string` | 图标源或图标 class。 |
| `shortcut` | `string` | 右侧的快捷键提示；不注册快捷键。 |
| `disabled` | `boolean` | 保持可见，但不可选中。 |

## 概述

- 显示状态只由 `modelValue` 决定。打开时触发 `open`，从打开变为关闭时触发 `close`。
- 过滤是对 `title`、`description`、`keywords` 的本地子串匹配，不区分大小写；组件不排序、不节流、不请求远端。
- `↑` / `↓` 循环移动并跳过禁用项，`Enter` 选中，`Esc` 关闭。高亮初始落在第一个可用命令上。
- 输入法组合期间不响应键盘选择，避免提前提交中日韩输入。
- 遮罩层是 `role="dialog"` 与 `aria-modal="true"`；禁用项带 `aria-disabled="true"`，不触发 `select`。

## 技术实现

- 源码：`packages/tuffex/packages/components/src/command-palette/`。

<TuffDocSourceLink />