vue3-shortKey
- 专为 Vue3 设计的「键盘快捷键专用插件」,所有功能围绕 "快捷键绑定、触发控制、冲突规避" 展开,无任何冗余能力,它接受全局快捷键,并支持单个监听器,用最简单的方式解决 Vue 项目的快捷键需求,是一个非常好用的快捷键利器!
特点
- 完全支持
vue3
特性 - 完全支持
nuxt3
SSR 场景 - 原生
指令化
全场景
覆盖- 精细化避免
快捷键
冲突 - API 简洁,
轻量化
- 学习
成本低
,语义化
如何使用
安装
shell
pnpm install vue3-shortkey
用法
js
Vue.use(require('vue3-shortkey'))
- 监听组合快捷键
下面的代码将监听组合键 ctrl
+ alt
+ o
执行 theAction
方法。
html
<template>
<button
v-shortkey="['ctrl', 'alt', 'o']"
@shortkey="theAction()">
ˇOpen
</button>
</template>
@shortkey 的函数将在按下相应键时重复调用。如果只想调用一次该函数,使用 once
修饰符。
html
<template>
<button
v-shortkey.once="['ctrl', 'alt', 'o']"
@shortkey="theAction()">
Open
</button>
</template>
- 同时监听多个快捷键
html
<template>
<button
v-shortkey="{up: ['arrowup'], down: ['arrowdown']}"
@shortkey="theAction">
Joystick
</button>
</template>
<script lang="ts" setup>
const theAction = (event) => {
switch (event.srcKey) {
case 'up': /* 上移逻辑 */ break;
case 'down': /* 下移逻辑 */ break;
}
}
</script>
- 设置焦点
使用 focus
修饰符,按下快捷键时,使元素获得焦点,特别适合输入框聚焦的场景。
下面的代码监听 ALT
+ I
键按下,直接聚焦到输入框。
html
<template>
<input
type="text"
v-shortkey.focus="['alt', 'i']"
v-model="name" />
</template>
- 快捷键切换
通过 push
修饰符,点击按钮时,会调用一次函数。再次点击时,释放快捷键,会再次调用函数
html
<template>
<tooltip
v-shortkey.push="['f3']"
@shortkey="toggleToolTip">
</tooltip>
</template>
- 组件和多监听器
自定义组件的使用方式是一样的
html
// 加 native 修饰符监听原生事件
<my-component
v-shortkey="['ctrl', 'alt', 'o']"
@shortkey.propagate="anAction()">
</my-component>
// 加 propagate 修饰符,让同一快捷键触发多个函数
<my-component
v-shortkey="['ctrl', 'alt', 'o']"
@shortkey.propagate="aDifferentAction()">
</my-component>
支持 Nuxt3
- 新建 /plugins/vue3-shortkey.js
js
import Vue from 'vue'
const ShortKey = require('vue-shortkey')
Vue.use(ShortKey, { prevent: ['input', 'textarea'] })
export default ShortKey
- 在 nuxt.config.js 中配置(仅客户端加载,避免 SSR 冲突)
js
plugins: [ { src: '@/plugins/vue-shortkey.js', mode: 'client' }]
和 vueuse 快捷键的区别
vueuse
中,如 useKeyModifier
、useMagicKeys
等 API,也具备处理键盘快捷键的能力;vue3-shortkey
基于 Vue 指令设计,完全贴合 Vue 开发者的使用习惯,无需理解底层事件逻辑;而 VueUse 需通过组合式 API 手动管理按键监听,对不太友好。
举个例子 🌰:实现 "Ctrl+Alt+O 触发打开事件"
- vue3-shortkey
html
<template>
<button v-shortkey="['ctrl', 'alt', 'o']" @shortkey="open()">打开</button>
</template>
1 行指令直接绑定,无需关心生命周期(插件自动管理事件绑定 / 解绑);支持 once/push 等修饰符,功能扩展零成本。
- vueuse
html
<template>
<button>打开</button>
</template>
<script setup>
import { useMagicKeys } from '@vueuse/core'
const { ctrl, alt, o } = useMagicKeys()
// 监听组合键按下
watch([ctrl, alt, o], ([c, a, oKey]) => {
if (c && a && oKey) open()
},
{ flush: 'sync' }
)
</script>
vue3-shortkey
的优势在于省去了 "组合按键状态、处理触发时机" 的手动逻辑,尤其适合批量绑定快捷键(如列表项动态绑定 F1-F10),代码更简洁。
而且还内置了 vue 项目中高频的快捷键场景化功能,这些功能若用 vueuse 实现,需额外编写大量辅助代码。
专业的事情交给专业的做,用 vue3-shortkey 做键盘快捷键处理是一个非常好的选择。
附上一个获取键盘按键 key 的工具:www.toptal.com/developers/...
关注学什么前端,更多前端技巧,我们一起学习。