defineShortcuts
用于在应用中定义键盘快捷键的 composable。
用法
使用自动导入的 defineShortcuts composable 来定义键盘快捷键。
<script setup lang="ts">
const open = ref(false)
defineShortcuts({
meta_k: () => {
open.value = !open.value
}
})
</script>
- 此 composable 使用 VueUse 的
useEventListener来处理 keydown 事件。 - 有关可用快捷键的完整列表，请参阅
KeyboardEvent.keyAPI 文档。请注意，键名应以小写形式书写。
API
defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions)
为您的应用定义键盘快捷键。
config: 一个对象，其键是快捷键定义，值可以是处理函数或快捷键配置对象。options: 快捷键行为的可选配置。chainDelay: 将快捷键视为链式时按键之间的延迟。默认为250。
快捷键定义
快捷键使用以下格式定义
- 单键:
'a','b','1','?'等。 - 组合键: 使用
_分隔按键，例如'meta_k','ctrl_shift_f' - 按键序列: 使用
-定义序列，例如'g-d'
修饰键
meta: 在 macOS 上代表⌘ Command，在 Windows 上代表⊞ Windowsctrl: 在所有平台上都代表Ctrlshift: 用于需要 Shift 键的字母键。
特殊键
escape: 在 Esc 键按下时触发enter: 在 Enter 键按下时触发arrowleft,arrowright,arrowup,arrowdown: 在相应的方向键按下时触发
快捷键配置
每个快捷键可以定义为一个函数或一个具有以下属性的对象
interface ShortcutConfig {
handler: () => void
usingInput?: boolean | string
}
handler: 快捷键触发时执行的函数usingInput:false(默认): 快捷键仅在没有输入框聚焦时触发true: 即使有任何输入框聚焦，快捷键也会触发string: 快捷键仅在指定的输入框（按名称）聚焦时触发
示例
基本用法
<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>