Composables и плагин

useCommandPalette

Composable, предоставляющий глобальное состояние палитры и все функции управления. Должен вызываться внутри дерева компонентов, где установлен VCommandPalettePlugin. Передайте имя инстанса — useCommandPalette('sidebar') — чтобы обратиться к именованному инстансу.

import { useCommandPalette } from '@macrulez/vue-command-palette'

const {
  isOpen, // Readonly<Ref<boolean>>
  query, // Ref<string>
  results, // ComputedRef<SearchResult[]>
  activeIndex, // Ref<number>
  history, // Readonly<Ref<HistoryEntry[]>>
  loadingCommandId, // Readonly<Ref<string | null>>

  open, // (paletteId?: string) => void
  close, // () => void
  toggle, // () => void
  goBack, // () => void — извлекает историю или закрывает, если пусто
  executeCommand, // (cmd: Command) => Promise<void>
  executeActive, // () => Promise<void> — запускает текущий выбранный результат
  getRecentCommands, // () => Command[]
  getPinnedCommands, // () => Command[]
  registerCommands, // (commands: Command[]) => () => void
  registerGroup, // (group: CommandGroup) => () => void
  addRecent, // (id: string) => void
  pin,
  unpin,
  togglePin,
  isPinned, // API закреплённых команд
  pinnedIds, // Readonly<Ref<string[]>>
  queryHistory, // Readonly<Ref<string[]>>
} = useCommandPalette()

Программное управление

const { open, close, toggle } = useCommandPalette()

open() // открыть палитру
close() // закрыть и сбросить состояние
toggle() // переключить открыто/закрыто

// Открыть под-палитру (навигация по хлебным крошкам)
open('parent-command-id')

useRegisterCommands

Регистрирует команды при монтировании компонента и автоматически снимает регистрацию при размонтировании. Команды, зарегистрированные так, не имеют заголовка группы.

import { useRegisterCommands } from '@macrulez/vue-command-palette'

// В любом setup() компонента
useRegisterCommands([
  {
    id: 'format-doc',
    label: 'Format Document',
    icon: '✨',
    perform: () => formatDocument(),
  },
  {
    id: 'toggle-sidebar',
    label: 'Toggle Sidebar',
    shortcut: ['$mod', 'b'],
    perform: () => sidebar.toggle(),
  },
])

useRegisterGroup

Регистрирует полную группу команд с label и приоритетом при монтировании, снимает регистрацию при размонтировании.

import { useRegisterGroup } from '@macrulez/vue-command-palette'

useRegisterGroup({
  id: 'editor',
  label: 'Editor',
  priority: 80,
  commands: [
    {
      id: 'editor-format',
      label: 'Format Document',
      description: 'Run Prettier on the current file',
      icon: '✨',
      perform: () => format(),
    },
    {
      id: 'editor-lint',
      label: 'Lint File',
      description: 'Run ESLint and show errors',
      icon: '🔍',
      enabled: () => isFileOpen.value,
      perform: () => lint(),
    },
  ],
})

VCommandPalettePlugin

Vue-плагин, настраивающий глобальное хранилище команд, слушатель клавиатуры и реактивное состояние.

app.use(VCommandPalettePlugin, options)

Опции (PaletteOptions)

Опция	Тип	По умолчанию	Описание
name	string	'default'	Имя инстанса (см. Множественные инстансы)
hotkey	string[]	['$mod', 'k']	Комбинация клавиш для переключения палитры
colorTheme	'light' | 'dark' | 'system'	'system'	Начальная цветовая тема палитры
search	SearchFn	встроенный нечёткий	Кастомная стратегия поиска (см. Кастомный поиск)
searchNested	boolean	true	Показывать вложенные subCommands в результатах поиска с хлебными крошками
showDisabled	boolean	false	Показывать отключённые команды (серые, невыполнимые, в конце списка) вместо их скрытия
frecency	boolean	false	Повышать в ранжировании часто и недавно используемые команды (см. Frecency)
onSearch	(query) => Command[] | Promise<Command[]>	—	Асинхронный источник данных уровня плагина, объединяется с каждым запросом (см. Асинхронный поиск)
bindShortcuts	boolean	false	Автоматически регистрировать shortcut каждой команды как глобальную горячую клавишу
persistRecent	boolean	true	Сохранять недавние команды в localStorage
maxRecent	number	5	Максимальное общее число хранимых недавних команд
maxRecentPerGroup	number	0	Максимум недавних на группу (0 = без ограничений)
localStorageKey	string	'vcp:recent'	Ключ, используемый в localStorage
onOpen	() => void	—	Вызывается каждый раз при открытии палитры
onClose	() => void	—	Вызывается каждый раз при закрытии палитры
onError	(err: unknown, command: Command) => void	—	Вызывается, когда perform() выбрасывает исключение
onHighlight	(command: Command | null) => void	—	Вызывается при смене активной по клавиатуре команды (для превью/аналитики)

Пример со всеми опциями

app.use(VCommandPalettePlugin, {
  hotkey: ['$mod', 'k'],
  colorTheme: 'system', // 'light' | 'dark' | 'system'
  persistRecent: true,
  maxRecent: 8,
  maxRecentPerGroup: 2,
  localStorageKey: 'myapp:palette:recent',
  onOpen: () => analytics.track('palette_opened'),
  onClose: () => analytics.track('palette_closed'),
  onError: (err, cmd) => {
    console.error(`Command "${cmd.label}" failed:`, err)
    toast.error(`Failed to run "${cmd.label}"`)
  },
})

Клавиша $mod

$mod разрешается в Meta (⌘) на macOS и Ctrl на Windows / Linux — используйте её для переносимых между платформами сочетаний:

hotkey: ['$mod', 'k'] // Cmd+K на Mac, Ctrl+K на Windows
shortcut: ['$mod', 'shift', 'p'] // Cmd+Shift+P на Mac, Ctrl+Shift+P на Windows