Справочник API

Command

interface Command<T = unknown> {
  id: string // уникальный идентификатор
  label: string // отображаемый текст, ищется движком нечёткого поиска
  description?: string // подзаголовок под label
  icon?: Component | string // Vue-компонент или эмодзи / строка
  keywords?: string[] // дополнительные термины для поиска
  aliases?: string[] // альтернативные label (тот же счёт, что и совпадение по label)
  shortcut?: string[] // подсказка только для отображения: ['$mod', 'k']
  disabled?: boolean // постоянно недоступна
  enabled?: () => boolean // динамическое отключение — вычисляется на каждом рендере
  disabledReason?: string // тултип, показываемый когда команда отключена
  badge?: string | { text: string; color?: string } // небольшая метка (например, "New", "Pro")
  confirm?: string // подсказка перед выполнением
  perform: () => void | Promise<void> // действие; может быть асинхронным
  subCommands?: Command[] // открывает вложенную палитру при выборе
  page?: CommandPage // открывает страницу со своим вводом/асинхронным поиском
  actions?: CommandAction[] // дополнительные действия, открываются по Tab
  info?: string // текст/HTML, показываемый в панели предпросмотра (v-html)
  data?: T // типобезопасный payload (см. «Типизированные данные команды»)
}

Поле icon

Принимает строку-эмодзи, обычную текстовую строку или любой Vue-компонент:

import MyIcon from './MyIcon.vue'

{
  icon: '🏠'
} // строка-эмодзи
{
  icon: '⌘'
} // строка-символ
{
  icon: MyIcon
} // Vue-компонент — рендерится как <MyIcon />

CommandAction

interface CommandAction {
  id: string
  label: string
  icon?: Component | string
  shortcut?: string[] // подсказка только для отображения
  perform: () => void | Promise<void>
}

Дополнительное действие команды — см. Дополнительные действия.

CommandPage

interface CommandPage {
  placeholder?: string // плейсхолдер ввода на странице
  items?: Command[] // статичные элементы (пустой запрос)
  onSearch?: (query: string) => Command[] | Promise<Command[]> // результаты по запросу (с debounce)
}

Открывается командой вместо (или в дополнение к) выполнения — см. Страницы команд.

Типизированные данные команды

Прикрепите произвольный типобезопасный payload к командам через дженерик Command<T> и его поле data. useRegisterCommands / useRegisterGroup, fuzzySearch<T>, SearchResult<T> и SearchFn<T> — все пробрасывают тип дальше, так что вы получаете полный вывод типов (и ошибки при несовпадении). По умолчанию используется unknown, поэтому существующий нетипизированный код не затрагивается.

interface UserData {
  id: number
  email: string
}

useRegisterCommands<UserData>([
  {
    id: 'user-ada',
    label: 'Ada Lovelace',
    data: { id: 1, email: 'ada@example.com' }, // проверяется по UserData
    perform: () => {},
  },
])

// Автономный поиск сохраняет тип:
const results = fuzzySearch<UserData>('ada', commands)
results[0].command.data?.email // string | undefined

// @ts-expect-error — data должен соответствовать UserData
const bad: Command<UserData> = { id: 'x', label: 'X', data: { wrong: true }, perform: () => {} }

Внутри слотов #item / #preview command типизирован как Command (data: unknown), поскольку палитра хранит команды смешанных типов — сужайте тип через приведение или type guard, когда там нужен payload.

SearchResult

interface SearchResult {
  command: Command
  score: number
  matches: Array<[start: number, end: number]>
  groupId?: string
  parents?: Command[] // цепочка предков, когда результат — вложенная под-команда
  matchedField?: 'label' | 'description' | 'keyword' | 'alias' // какое поле выиграло счёт
  matchedText?: string // текст совпавшего ключевого слова/алиаса
}

PaletteContext

Полный инжектируемый контекст, доступный в кастомных composables через inject(PALETTE_INJECT_KEY):

interface PaletteContext {
  store: CommandStore
  keyboard: KeyboardManager
  isOpen: Ref<boolean>
  query: Ref<string>
  activeIndex: Ref<number>
  history: Ref<HistoryEntry[]>
  recentIds: Ref<string[]>
  loadingCommandId: Ref<string | null>
  results: ComputedRef<SearchResult[]>
  persistRecent: boolean
  maxRecent: number
  maxRecentPerGroup: number
  localStorageKey: string
  onOpen?: () => void
  onClose?: () => void
  onError?: (err: unknown, command: Command) => void
}

createCommandStore

(search?: SearchFn, searchNested?: boolean, scoreBonus?: (command: Command) => number, showDisabled?: boolean) => CommandStore

Низкоуровневая фабрика, лежащая в основе VCommandPalettePlugin и утилит тестирования — регистрирует/ищет команды напрямую. Обычно не нужна напрямую: используйте плагин или useCommandPalette().

Типы TypeScript

Все публичные типы экспортируются из корня пакета:

import type {
  Command,
  CommandGroupType, // определение группы — НЕ компонент CommandGroup
  CommandAction, // дополнительное действие команды
  CommandPage, // страница, открываемая командой (плейсхолдер + асинхронный onSearch)
  SearchResult, // { command, score, matches, groupId?, parents?, matchedField? }
  SearchFn, // сигнатура кастомной стратегии поиска
  PaletteMode, // активируемая префиксом область
  CommandUsage, // статистика frecency { count, lastUsed }
  PaletteOptions,
  PaletteLabels, // настраиваемые строки UI (i18n)
  PaletteContext,
  PaletteState,
  CommandStore,
  KeyboardManager,
} from '@macrulez/vue-command-palette'

Примечание: именованный экспорт CommandGroup — это Vue-компонент. Интерфейс определения группы экспортируется как CommandGroupType, чтобы избежать конфликта.