VueCraft NPM

Vue-плагин ​

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

ts
app.use(VCommandPalettePlugin, options)

Опции ​

PaletteOptions

name ​

string · по умолчанию: 'default'

Имя инстанса — см. Множественные инстансы.

hotkey ​

string[] · по умолчанию: ['$mod', 'k']

Комбинация клавиш для переключения палитры.

colorTheme ​

'light' | 'dark' | 'system' · по умолчанию: 'system'

Начальная цветовая тема палитры.

SearchFn · по умолчанию: встроенный нечёткий поиск

Кастомная стратегия поиска — см. Кастомная стратегия поиска.

searchNested ​

boolean · по умолчанию: true

Показывать вложенные subCommands в результатах поиска с хлебными крошками.

showDisabled ​

boolean · по умолчанию: false

Показывать отключённые команды (серые, невыполнимые, в конце списка) вместо их скрытия.

frecency ​

boolean · по умолчанию: false

Повышать в ранжировании часто и недавно используемые команды — см. Frecency.

onSearch ​

(query: string) => 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 · по умолчанию: —

Вызывается при смене активной по клавиатуре команды (для превью/аналитики).

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

ts
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}"`)
  },
})

Множественные инстансы ​

Запускайте несколько независимых палитр в одном приложении — например, глобальную командную строку плюс поиск в сайдбаре — каждую со своей горячей клавишей, командами и состоянием. Используйте createCommandPalette() для каждого инстанса, кроме дефолтного (она возвращает новый объект плагина, чтобы дедупликация app.use во Vue его не пропустила).

ts
import { VCommandPalettePlugin, createCommandPalette } from '@macrulez/vue-command-palette'

app.use(VCommandPalettePlugin) // инстанс по умолчанию
app.use(createCommandPalette({ name: 'sidebar', hotkey: ['$mod', 'j'] }))
vue
<template>
  <!-- по умолчанию -->
  <CommandPalette />
  <!-- sidebar -->
  <CommandPalette name="sidebar" placeholder="Search the sidebar…" />
</template>

Обращайтесь к конкретному инстансу из composables через аргумент name:

ts
const sidebar = useCommandPalette('sidebar')
useRegisterCommands([/* … */], 'sidebar')
useRegisterGroup({/* … */}, 'sidebar')

Клавиша $mod ​

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

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