defineShortcuts
一个用于在应用中定义键盘快捷键的可组合项。
用法
使用自动导入的 defineShortcuts 可组合项来定义键盘快捷键。
<script setup lang="ts">
const open = ref(false)
defineShortcuts({
meta_k: () => {
open.value = !open.value
}
})
</script>
- 快捷键会自动针对非 macOS 平台进行调整，将
meta转换为ctrl。 - 该可组合项使用 VueUse 的
useEventListener来处理键盘按下事件。 - 有关可用快捷键的完整列表，请参考
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，在其他平台上表示Ctrlctrl：在所有平台上表示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>