defineShortcuts

一个用于在你的应用中定义键盘快捷键的可组合函数。

用法

使用自动导入的 defineShortcuts 可组合函数来定义键盘快捷键。

<script setup lang="ts">
const open = ref(false)

defineShortcuts({
  meta_k: () => {
    open.value = !open.value
  }
})
</script>

快捷键会自动适配非 macOS 平台，将 meta 键转换为 ctrl 键。
此可组合函数使用 VueUse 的useEventListener来处理 keydown 事件。
有关可用快捷键的完整列表，请参阅KeyboardEvent.keyAPI 文档。请注意，键名应使用小写。

了解如何在组件中显示快捷键，请参阅 Kbd 组件文档。

API

defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions): void

为你的应用程序定义键盘快捷键。

参数

config

ShortcutsConfig required

一个对象，其中键是快捷键定义，值是处理函数或快捷键配置对象。

options

ShortcutsOptions

快捷键行为的可选配置。

快捷键定义

快捷键使用以下格式定义

单个按键： 'a', 'b', '1', '?' 等。
组合键：使用 _ 分隔按键，例如 'meta_k', 'ctrl_shift_f'
按键序列：使用 - 定义序列，例如 'g-d'

修饰键

meta：在 macOS 上表示 ⌘ Command，在其他平台上表示 Ctrl。
ctrl：在所有平台上表示 Ctrl。
shift：当字母键需要 Shift 修饰时使用。

特殊按键

escape：触发 Esc 键。
enter：触发 Enter 键。
arrowleft, arrowright, arrowup, arrowdown：分别触发方向键。

快捷键配置

每个快捷键都可以定义为一个函数或一个包含以下属性的对象

interface ShortcutConfig { handler: () => void; usingInput?: boolean | string }

参数

handler

() => void required

当快捷键被触发时执行的函数。

usingInput

boolean | string

控制快捷键在输入框聚焦时的触发条件

false (默认)：仅当没有输入框聚焦时触发快捷键。
true：即使任何输入框聚焦时也触发快捷键。
string：仅当指定名称（name）的输入框聚焦时触发快捷键。

示例

基本用法

<script setup lang="ts">
defineShortcuts({
  '?': () => openHelpModal(),
  'meta_k': () => openCommandPalette(),
  'g-d': () => navigateToDashboard()
})
</script>

带有输入框焦点处理

usingInput 选项可让您指定快捷键仅在特定输入框聚焦时触发。

<template>
  <UInput v-model="query" name="queryInput" />
</template>

<script setup lang="ts">
const query = ref('')

defineShortcuts({
  enter: {
    usingInput: 'queryInput',
    handler: () => performSearch()
  },
  escape: {
    usingInput: true,
    handler: () => clearSearch()
  }
})
</script>

从菜单项提取快捷键

extractShortcuts 工具函数可用于从菜单项自动定义快捷键。

<script setup lang="ts">
const items = [{
  label: 'Save',
  icon: 'i-lucide-file-down',
  kbds: ['meta', 'S'],
  onSelect() {
    save()
  }
}, {
  label: 'Copy',
  icon: 'i-lucide-copy',
  kbds: ['meta', 'C'],
  onSelect() {
    copy()
  }
}]

defineShortcuts(extractShortcuts(items))
</script>

useOverlay

一个用于以编程方式控制叠加层的可组合函数。