CommandPalette

Usage

Best Practices

• Keep id stable across releases; use it for analytics, persistence, and permission checks instead of localized titles.
• Put synonyms, aliases, plugin names, and localized search terms in keywords; do not duplicate commands just to cover search variants.
• Register global shortcuts in the app shell, then drive v-model; shortcut is only a visible keyboard hint.
• Use footer for source labels, result counts, or keyboard help. Use empty to show the current query and suggest recovery actions.
• Cap maxHeight for dense command sets so the overlay stays keyboard-scannable and does not push below the viewport.

API Reference

Props

CommandPaletteItem

Events

Slots

Launcher Scenario

UX Notes

• Title, description, and keywords all participate in filtering. Put aliases, localized terms, and plugin keywords on the same command.
• icon accepts an icon class or TxIconSource; shortcut only renders the keyboard hint and does not register a global shortcut.
• disabled commands remain visible but cannot be selected, which is useful for missing permissions, unsupported platforms, or disabled features.
• Use closeOnSelect=false for batch workflows or settings panels. The default closes the palette after selection.

Overview

• modelValue is the single source of truth for visibility. The palette emits open when it becomes visible and close when an existing open state is dismissed.
• Search is local substring matching across title, description, and every keywords entry. The component does not rank, debounce, or fetch remote results.
• ArrowDown / ArrowUp cycle through the visible commands and skip disabled ones, so the highlight never parks on an unusable command; Enter selects the active command; Escape closes the overlay. The initial highlight lands on the first enabled command, and arrow navigation is a no-op when every command is disabled.
• IME composition (isComposing, keyCode 229, or an active composition session) suppresses keyboard selection so Chinese/Japanese/Korean input is not submitted early.
• select emits the original CommandPaletteItem. Disabled commands stay visible as role="option" with aria-disabled="true" and are removed from the tab order (tabindex="-1"); they never emit select. closeOnSelect=false keeps the palette open after selection.

Technologies

• Reviewed against packages/tuffex/packages/components/src/command-palette/src/types.ts, TxCommandPalette.vue, and command-palette.test.ts.
• Existing tests cover local filtering and selection, disabled-command skipping with aria-disabled / tabindex marking, IME composition guarding, matched text highlighting, and custom empty / footer slots.
• Accessibility note: the overlay renders role="dialog" with aria-modal="true"; keep the trigger label and placeholder specific enough for the current command domain, and do not treat the displayed shortcut as actual shortcut registration.
• Component source: packages/tuffex/packages/components/src/command-palette/src/TxCommandPalette.vue.
• Types: packages/tuffex/packages/components/src/command-palette/src/types.ts exports CommandPaletteProps, CommandPaletteEmits, CommandPaletteItem, and CommandPaletteClassValue.
• Verified coverage: packages/tuffex/packages/components/src/command-palette/__tests__/command-palette.test.ts verifies filtering, select emits, disabled-command skipping and aria-disabled / tabindex marking, IME guarding, match highlighting, and slots.
  查看源码

  packages/tuffex/packages/components/src/command-palette/index.ts