airi 桌面端的键盘魔法：VueUse `useMagicKeys` 组合键监听实战指南-北京尧图网络

人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载useMagicKeys是 VueUse 提供的响应式键盘监听组合式函数它把每一个按键含修饰键变成响应式布尔状态并原生支持用/_声明组合快捷键。本指南以 airi 仓库内.agents/skills/vueuse-functions/references/useMagicKeys.md为骨架结合仓库中 devtools 演示页、Live2D 播放快捷键与性能可视化页的真实源码讲解从单键监听到组合键、别名映射、条件禁用、自定义事件处理器的完整用法并给出可直接落地的实战模式。什么是useMagicKeys响应式按键状态useMagicKeys返回一个由“键名 → 布尔响应式状态”组成的对象只要某个键处于按下状态对应的ComputedRefboolean即为true。它归类在 VueUse 的 Sensors传感器分类下见 SKILL.md在 airi 中的调用级别为 AUTO——即只要需求匹配即可直接使用无需额外安装依赖vueuse/core已通过 pnpm catalog 被apps/stage-web、apps/stage-pocket、apps/stage-tamagotchi等多个应用统一引用见各 package.json。最基本的用法是解构出想监听的键名然后交给watch或watchEffectimport { useMagicKeys } from vueuse/core const { shift, space, a /* keys you want to monitor */ } useMagicKeys() watch(space, (v) { if (v) console.log(space has been pressed) }) watchEffect(() { if (shift.value a.value) console.log(Shift A have been pressed) })TypeScriptnoUncheckedIndexedAccess注意事项如果项目在tsconfig.json中启用了noUncheckedIndexedAccessNuxt 默认开启解构出的键名类型会是ComputedRefboolean | undefined。原因在于useMagicKeys()内部用索引签名支持任意动态键访问TypeScript 会把解构属性视为“可能未定义”。此时需要改用可选链或包一层 getterconst { shift, space, a } useMagicKeys() watch( () space?.value, (v) { if (v) console.log(space has been pressed) }, ) watchEffect(() { if (shift?.value a?.value) console.log(Shift A have been pressed) })键名的取值来源是KeyboardEvent的 code/key 值完整键码列表可参考 MDN 的 KeyboardEvent code values 文档键名如shift、space、control、alt、escape、tab以及单个字母a、s等。组合键Combinations用与_声明快捷键这是useMagicKeys最“魔法”的部分用或_把多个键名连接起来即可得到一个代表“这些键同时按下”的响应式布尔值。用语法通过索引访问组合键import { useMagicKeys } from vueuse/core const keys useMagicKeys() const shiftCtrlA keys[ShiftCtrlA] watch(shiftCtrlA, (v) { if (v) console.log(Shift Ctrl A have been pressed) })用_语法组合名可以直接作为解构变量名Ctrl_A_B会被解析为Control A Bimport { useMagicKeys } from vueuse/core const { Ctrl_A_B, space, alt_s /* ... */ } useMagicKeys() watch(Ctrl_A_B, (v) { if (v) console.log(ControlAB have been pressed) })用whenever进一步精简whenever是watch的“真值简写”它只在条件为 truthy 时触发回调见 whenever.md非常适合配合组合键写快捷键import { useMagicKeys, whenever } from vueuse/core const keys useMagicKeys() whenever(keys.shift_space, () { console.log(ShiftSpace have been pressed) })airi 中的 Lag 可视化页面正是这种写法的直接体现在 performance-visualizer.vue 中用whenever(magicKeys[ctrlaltl], () lagStore.toggleAll(true))开启全部指标、whenever(magicKeys[ctrlaltk], () lagStore.toggleAll(false))关闭全部指标两条快捷键让性能面板的开关无需鼠标操作。current当前按下的全部按键集合useMagicKeys()返回一个特殊属性current它是一个Setstring代表当前正在按下的全部键存储的是原始键码import { useMagicKeys, whenever } from vueuse/core const { current } useMagicKeys() console.log(current) // Set { control, a } whenever( () current.has(a) !current.has(b), () console.log(A is pressed but not B), )这个属性非常适合需要“枚举当前状态”的场景比如按键可视化面板。airi 的 devtools 演示页 use-magic-keys.vue 就用const keys computed(() Array.from(current))把实时按下的键渲染成一排code标签逐个键高亮用来验证应用是否正确接收到修饰键和按键状态该页面对应的用户文档见 desktop-developer-tools.md。Key Aliasing按键别名映射aliasMap允许把自定义的“语义名”映射到真实键码适合让快捷键命名贴近业务含义。注意映射目标键名应保持小写import { useMagicKeys, whenever } from vueuse/core const { shift_cool } useMagicKeys({ aliasMap: { cool: space, }, }) whenever(shift_cool, () console.log(Shift Space have been pressed))VueUse 默认自带一套常用别名的预配置映射DefaultMagicKeysAliasMap覆盖了shift、control、alt、meta等常见命名差异并作为命名导出暴露见 useMagicKeys.md。从类型声明可以看出别名映射中“目标键”统一小写例如{ ctrl: control }。条件禁用避免在输入框中触发快捷键应用里常存在input、textarea等文本输入元素用户在这些元素上输入时不应触发全局快捷键。参考做法是组合useActiveElement响应式document.activeElement见 useActiveElement.md与vueuse/math的logicAnd多个 ref 的 AND 条件见 logicAnd.mdimport { useActiveElement, useMagicKeys, whenever } from vueuse/core import { logicAnd } from vueuse/math const activeElement useActiveElement() const notUsingInput computed(() activeElement.value?.tagName ! INPUT activeElement.value?.tagName ! TEXTAREA,) const { tab } useMagicKeys() whenever(logicAnd(tab, notUsingInput), () { console.log(Tab has been pressed outside of inputs!) })airi 的 Live2D 播放快捷键实现把这一思路做得更彻底除了排除input/textarea/select还额外排除了contentEditable区域并且只在“快捷键启用且非文本输入”时才执行preventDefault详见下文“仓库实战”。自定义事件处理器onEventFired与passive: false默认情况下useMagicKeys以 passive 模式注册监听器无法调用event.preventDefault()。若想在按键事件里执行自定义逻辑例如阻止浏览器默认行为需要显式传passive: false并在onEventFired中判断事件类型import { useMagicKeys, whenever } from vueuse/core const { ctrl_s } useMagicKeys({ passive: false, onEventFired(e) { if (e.ctrlKey e.key s e.type keydown) e.preventDefault() }, }) whenever(ctrl_s, () console.log(CtrlS have been pressed))⚠️ 官方文档明确提示这种用法不推荐请谨慎使用。它会让应用接管原生快捷键可能影响用户习惯或可访问性。Reactive 模式在模板中直接使用默认情况下useMagicKeys()的每个键值是Refboolean。如果希望在模板里直接读取keys.shift而不是keys.shift.value可以把reactive选项设为trueimport { useMagicKeys } from vueuse/core // ---cut--- const keys useMagicKeys({ reactive: true })template div v-ifkeys.shift You are holding the Shift key! /div /template选项与类型声明useMagicKeys的完整选项UseMagicKeysOptionsReactive与返回值类型如下摘自 useMagicKeys.md选项类型默认值说明reactiveReactive extends booleanfalse返回 reactive 对象而非 ref 对象targetMaybeRefOrGetterEventTargetwindow监听事件的目标元素aliasMapRecordstring, string预定义映射键别名表键与值均为小写如{ ctrl: control }passivebooleantrue是否注册 passive 监听器onEventFired(e: KeyboardEvent) void \| boolean无keydown/keyup 自定义处理器要调用e.preventDefault()必须配合passive: falseexport interface MagicKeysInternal { /** * A Set of currently pressed keys, * Stores raw keyCodes. * * see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key */ current: Setstring } export type UseMagicKeysReturnReactive extends boolean Readonly Recordstring, Reactive extends true ? boolean : ComputedRefboolean MagicKeysInternal 关键点返回值是Recordstring, ComputedRefboolean | boolean { current: Setstring }的只读交叉类型——动态键访问通过索引签名实现这正是前文noUncheckedIndexedAccess告警的来源而current是类型安全的内置属性。仓库实战airi 中的真实用法1. devtools 按键演示页useMagicKeys在 airi 中既是开发调试工具也是验证键盘链路的手段。apps/stage-web与apps/stage-pocket下都有一份几乎相同的 use-magic-keys.vue 演示页它解构了shift、control、escape、tab、v、u、e、s等单键以及v_u_eVue、u_s_eUse、i_Shift_Alt等组合键并实时显示current集合。页面用一组“按键卡片”随按下状态切换高亮样式用来确认应用是否正确接收修饰键与按键状态——桌面版开发者工具文档明确说明该页面没有面向普通用户的配置项见 desktop-developer-tools.md。2. Live2D 运动播放快捷键最完整的生产级示例use-playback-keys.ts 是 airi 中把useMagicKeys用到一个“生产级”复杂度的例子它把 Live2D 动作播放控制绑定到窗口级快捷键上组合键判定用 computed 叠加playbackPressed、backwardPressed、forwardPressed、startPressed、endPressed分别对应ShiftSpace播放/暂停、ShiftA/D逐帧后退/前进、AltA/D跳到开头/结尾并且全部叠加了!keys.ctrl.value !keys.meta.value与!keys.alt.value/!keys.shift.value的互斥条件L52-L78passive: falseonEventFired抢占默认行为在 L44-L50 注册useMagicKeys({ passive: false, onEventFired })当快捷键启用且不在文本输入中时调用event.preventDefault()。源码注释特别指出useMagicKeys会先更新键的 ref 再调用onEventFired因此快捷键 ref 与浏览器默认行为共享同一个事件这也是该处能可靠“拦截”的原因文本输入保护isTextEntry检查isContentEditable或input/textarea/select匹配L174-L177同时shortcutsEnabled是!disabled !isTextEntry(activeElement.value)的响应式计算窗口失焦window.blur与组件卸载时都会清空长按方向状态长按加速寻帧按住ShiftA/D超过 300ms 延迟后进入加速循环按 80ms 间隔步进步数随按住时长按二次曲线增长holdSeekPolicyL23-L28 与heldStepCountL97-L104。这个例子同时演示了useMagicKeys与useActiveElement、useIntervalFn、useTimeoutFn、useEventListener、whenever、tryOnBeforeUnmount的组合——这正是 SKILL.md 所提倡的“用组合式函数替代手写逻辑”的落地范本。3. 性能可视化页面的全局开关如前文所述performance-visualizer.vue 用useMagicKeys() 字符串索引magicKeys[ctrlaltl]/magicKeys[ctrlaltk]注册调试快捷键展示了语法在“不预先解构”场景下的优势——键名完全由字符串动态决定适合集中管理快捷键表。总结与最佳实践回顾 airi 中useMagicKeys的使用方式可以沉淀出一套可复用的快捷键实现模式优先用whenever写一次性触发的快捷键播放/暂停、开关面板语义最清晰复杂组合键用 computed 叠加互斥条件显式排除Ctrl/Meta/Alt冲突避免误触发必须阻止默认行为时使用passive: falseonEventFired并记住useMagicKeys的 ref 更新先于onEventFired二者共享同一事件始终用useActiveElement排除文本输入input、textarea、select、contentEditable保证打字不被打断多键状态枚举用currentSet可视化面板、调试输出都依赖它模板中直接使用就开启reactive: true脚本逻辑则保持默认的 ref 形式。useMagicKeys把键盘输入变成了纯粹的数据流按键即状态、组合即命名配合 Vue 的响应式体系即可零成本声明全局快捷键。上述 airi 源码既验证了它的全部能力边界别名、条件禁用、自定义事件、被动/主动监听也为在自己的 Vue 3 应用中实现安全、不冲突的快捷键系统提供了经过生产验证的参考实现。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐VueUse useMagicKeys 深入指南响应式键盘监听与魔法组合键实战VueUse useMagicKeys 深入指南响应式键盘监听与魔法组合键实战 useMagicKeys 是 VueUse位于 packages/core/前端llm-graph-builder从 PDF 到知识图谱构建的完整指南llm graph builder从 PDF 到知识图谱构建的完整指南手头几百份 PDF知识散落在各页里想检索某个实体、再顺着它找关联都很费劲。llm后端前端人工智能大模型RAG知识图谱VueUse onKeyStroke 键盘事件监听实战从单键到组合键的完整指南airi 项目视角VueUse onKeyStroke 键盘事件监听实战从单键到组合键的完整指南airi 项目视角本文以 airi 仓库技能体系 .agents/skil人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端上一篇openEuler/cve-void高级技巧如何处理复杂CVE补丁冲突与依赖分析的完整指南下一篇Kiran-wallpapers终极指南如何为你的桌面换上OpenEuler官方壁纸创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

airi 桌面端的键盘魔法：VueUse `useMagicKeys` 组合键监听实战指南

相关推荐

鸣潮一键日常与自动刷声骸实战指南：从安装到后台挂机 3 步跑通

408复习规划：四科三档分层、三段执行与自填优先级打分卡

Hermes 配置 DeepSeek：一条命令装好，向导选三项就能对话

更多资讯

各类继电器接线详解：线圈与触点、接线图与避坑指南

MCU与MATLAB串口通信帧格式设计：协议、状态机与联调实战

QQ邮箱网页版下载无法改保存路径？根因与浏览器设置有关

ES查询入门：URI Search与Query DSL对比解析

《派出你的AI同事：WorkBuddy案例实战》042：私有化部署落地

Windows 激活与 Office 激活完整指南：MAS 一键免费激活，3 分钟拿到永久授权

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？