# 按键与快捷键 UI 里经常需要「按 Esc 关闭」「按 Enter 确认」「按方向键切换选中项」。不需要自己监听键盘:按键系统负责按键匹配、作用域与优先级,也负责让玩家在设置界面里改键。 下面按「在哪里写」「组件里怎么接」「什么时候需要额外参数」展开。 ## 前置知识 阅读本篇前,建议先读完: - [响应式](./reactivity.md) - [事件与交互](./events.md) ## 按键与元素事件 元素事件来自画布上的指针:先做命中测试,找到指针下的元素,再沿容器捕获与冒泡,关心的是「点在哪里」。 按键事件来自键盘:直接匹配指令,不经过画布命中,关心的是「按了什么」。 两条路径互相独立:按 Enter 不会触发按钮的 `onClick`,点按钮也不会触发绑定在 Enter 上的指令。两者可以同时存在,但没有统一的先后顺序;需要协同时,用一个共享的 `ref` 记录状态,让两边都读写同一份状态。 ## 指令与分组 指令和分组都注册在 `src/client/misc/hotkey.ts` 的 `initializeHotkey` 里。UI 组件里出现 `system.addCommand(...)` 或 `hotkey.setGroup(...)` 都是错误写法。 `hotkey.setGroup(groupId, name, commands)` 的第三个参数是指令数组,直接在数组里调用 `system.addCommand(...)`: ```ts // src/client/misc/hotkey.ts import { HotkeyEmitMode, KeyCode } from '@motajs/system'; import { IClientCore } from '@user/client-modules'; export function initializeHotkey(state: IClientCore) { const hotkey = state.hotkey; const system = hotkey.system; hotkey.setGroup('@my-ui', '我的界面', [ system.addCommand('@my-ui/refresh', '刷新面板', { defaults: [[KeyCode.KeyR]] }), system.addCommand('@my-ui/save', '保存', { defaults: [[KeyCode.Ctrl, KeyCode.KeyS]], mode: HotkeyEmitMode.Once }) ]); } ``` `addCommand(command, name, init)` 的 `command` 是全局指令 id。已有指令用命名空间前缀区分,例如 `@common/exit`、`@ui/book`、`@game/undo`;新增时用类似 `@my-ui/refresh` 的前缀,避免和已有 id 冲突。 `defaults` 是默认按键组合。 分组只影响设置界面里的显示,不影响按键是否生效。不分组也能用,只是不会出现在设置界面里。重复注册同一个 id 不会创建第二条指令,只会返回已有指令并给出警告。 `props.state.hotkey` 是客户端按键门面(`IClientHotkey`),`system` 是底层 `IHotkeySystem`:`addCommand` / `deleteCommand` 在 `system` 上,`setGroup` 在门面上。 ### 触发方式 | 取值 | 含义 | 默认 | | --------------------------- | ---------------- | ---- | | `HotkeyEmitMode.KeyUp` | 按键抬起时触发 | 是 | | `HotkeyEmitMode.Once` | 按下时只触发一次 | 否 | | `HotkeyEmitMode.Continuous` | 按住后持续触发 | 否 | `mode` 不写时是抬起触发。菜单里的「按一下执行一次」用默认抬起;需要按住连发才用持续触发。持续触发可以用 `timeout`、`interval`、`dt` 控制首次延迟与后续间隔,单位都是毫秒;这些是最小间隔,实际间隔只会不小于设定值,不能当作精确计时器。 ### 优先级与阻断 `priority` 越高越先执行,目前只对抬起触发的指令生效。`block` 为 `true` 时,会阻断优先级比它更低的指令;同优先级的指令会全部执行,不会互相阻断。这两个属性同样在 `hotkey.ts` 的 `addCommand` 里设置。 它们比较的是同一次按键匹配到的多条指令,不是两个界面之间的优先级。两个界面谁生效由作用域栈决定,见[按键与 UI 栈](#按键与-ui-栈)。 ## 组件中的实现 组件只做一件事:把当前界面的作用域接到指令回调上。 `useKey` 从 `@user/client-base` 引入,必须在 `setup` 中同步调用,才能拿到当前组件实例与作用域。它返回 `IHotkeyUsing | null`,组件内必定有实例,直接用非空断言 `!`: ```tsx // setup import { useKey } from '@user/client-base'; const key = useKey(props.state.hotkey.system)!; key.implement('@common/exit', () => { props.controller.close(props.instance); }); key.implement('@common/confirm', () => { props.controller.close(props.instance); }); ``` 回调通常写成无参的 `() =>`:一般情况下只关心触发了哪个指令,不需要 `info`。只有确实需要触发元信息时才接收 `info`,不要用它判断语义,见[辅助按键与按键组合](#辅助按键与按键组合)。 `useKey` 返回的对象只有 `implement()`、`scope()`、`when()`,它不是按键系统,也不是 `system`。不要在它上面调用 `addCommand`、`setGroup`、`deleteCommand`;需要这些方法时,单独取 `props.state.hotkey.system` 或 `props.state.hotkey`。 `implement` 把指令接到当前作用域,可以连续调用。同一次挂载里对同一指令重复 `implement` 会覆盖前一个回调,并给出警告。指令 id 拼错、或指令还没注册就 `implement`,不会抛异常,只会记录一条警告;「按了没反应」时先核对 id,再确认当前界面是否在栈顶。 ### 启用条件:when `when(() => boolean)` 给当前 `useKey` 的作用域设置启用条件:返回 `false` 时,这个界面的指令不会触发。适合临时禁用当前界面的快捷键。 ```tsx // setup const key = useKey(props.state.hotkey.system)!; const enabled = ref(true); key.when(() => enabled.value); key.implement('@common/exit', () => { ... }); ``` 条件在按键按下时判断一次;不要依赖「按下时 `false`、抬起时 `true` 就能触发」,按下时条件不成立,这次按键就不会生效。条件函数里直接读响应式值即可。 `when` 作用于当前 `useKey` 的作用域,不是全局系统。不要在其他作用域上调用它来改当前界面。 ### 作用域与生命周期 `useKey` 在组件挂载时进入一个新作用域,组件卸载时自动离开,不需要手动清理。 第二个参数 `clearImpl` 默认是 `true`,新作用域不继承下层界面的实现。传 `false` 时,下层已经实现的指令会复制到新作用域里继续生效,适合「面板打开时全局快捷键仍然可用」的场景;当前面板重新实现的指令会覆盖下层版本。 ### 子组件 普通子组件没有 `props.state`:把父级面板的 `props.state.hotkey.system` 作为普通 prop 传下来(类型 `IHotkeySystem` 从 `@motajs/system` 导入),在子组件 `setup` 里 `useKey(system)!`。也可以把按键处理留在能拿到 `props.state` 的父级面板,子组件只 emit。 ## 辅助按键与按键组合 `defaults` 是二维数组:每一项是一组按键组合,组内最后一个键是主按键,前面的键是辅助键。`[[KeyCode.Ctrl, KeyCode.KeyS]]` 表示按住 Ctrl 再按 S;单按 S 不会匹配。 辅助键要先于主键按下。抬起触发时,只有在辅助键和主键都按下后松开主键才触发。同一条指令可以写多组组合;同时能匹配多组时,只会触发辅助键精确匹配的那一组。 一般不要判断具体按键,包括 `info.keys` 和 `info.context`。玩家可以在设置界面里改键,按键和组合会变,按当前键位分支会得到错误的语义。 同一语义、只是默认组合不同时,在一条指令里写多个 `defaults`,组件里只 `implement` 一次,不需要 `info`: ```ts // src/client/misc/hotkey.ts hotkey.setGroup('@my-ui', '我的界面', [ system.addCommand('@my-ui/refresh', '刷新面板', { defaults: [ [KeyCode.KeyR], // R [KeyCode.Shift, KeyCode.KeyR] // Shift + R ] }) ]); ``` 不同语义就拆成不同指令,各自注册、各自 `implement`: ```ts // src/client/misc/hotkey.ts hotkey.setGroup('@my-ui', '我的界面', [ system.addCommand('@my-ui/save', '保存', { defaults: [[KeyCode.Ctrl, KeyCode.KeyS]] }), system.addCommand('@my-ui/quick-save', '快速保存', { defaults: [[KeyCode.KeyS]] }) ]); ``` ```tsx // setup import { useKey } from '@user/client-base'; const key = useKey(props.state.hotkey.system)!; key.implement('@my-ui/save', save); key.implement('@my-ui/quick-save', quickSave); ``` `info` 一般不需要;确实需要触发元信息时才接收,不要用它判断语义。 确实需要 `info` 时,通常是「一条指令有多个语义槽位」:槽位由 `defaults` 里的组合顺序稳定决定,组件只按 `info.index` 取槽位。 例如快速切换装备,`Alt+1` 到 `Alt+0` 依次对应槽位 0 到 9: ```ts // src/client/misc/hotkey.ts import { KeyCode } from '@motajs/system'; hotkey.setGroup('@my-ui', '我的界面', [ system.addCommand('@my-ui/quick-equip', '快速切换装备', { defaults: [ [KeyCode.Alt, KeyCode.Digit1], // 槽位 0 [KeyCode.Alt, KeyCode.Digit2], // 槽位 1 [KeyCode.Alt, KeyCode.Digit3], // 槽位 2 [KeyCode.Alt, KeyCode.Digit4], // 槽位 3 [KeyCode.Alt, KeyCode.Digit5], // 槽位 4 [KeyCode.Alt, KeyCode.Digit6], // 槽位 5 [KeyCode.Alt, KeyCode.Digit7], // 槽位 6 [KeyCode.Alt, KeyCode.Digit8], // 槽位 7 [KeyCode.Alt, KeyCode.Digit9], // 槽位 8 [KeyCode.Alt, KeyCode.Digit0] // 槽位 9 ] }) ]); ``` ```tsx // setup import { useKey } from '@user/client-base'; import { IHotkeyEmitInfo } from '@motajs/system'; const key = useKey(props.state.hotkey.system)!; // info.index 是触发组合在 defaults 里的下标,正好对应装备槽位 const quickEquip = (info: IHotkeyEmitInfo) => { const slot = info.index; // 使用 slot 切换装备 }; key.implement('@my-ui/quick-equip', quickEquip); ``` 这里需要 `info`,是因为一条指令有多个语义槽位,槽位由组合顺序稳定决定。不要判断 `info.keys` 或具体的数字键:玩家改键后按键会变,但 `info.index` 仍对应槽位。 ## 按键与 UI 栈 按键作用域是一条全局栈,不按控制器分开。最后挂载并调用 `useKey` 的面板在栈顶,只有栈顶作用域里的实现会执行: - 面板 A 打开,A 在栈顶,A 的 Esc 生效。 - 面板 B 打开,B 在栈顶,A 的 Esc 暂时不生效,背景界面也不会同时响应。 - 面板 B 关闭并卸载,B 的作用域移除,A 重新成为栈顶,A 的 Esc 恢复。 这里的「关闭」指组件卸载。只是把面板 `hidden` 起来,组件还在,作用域也还在,它仍然占着栈里的位置。用 `showAll` 让多个面板同时显示时,按键仍然只落到最后挂载的那个面板,不会因为都可见就都响应。 ## 默认按键 默认值只是起点,玩家可以在设置界面里改: | 指令 | 默认按键 | 说明 | | ------------------- | ----------------- | ----------- | | `@common/confirm` | Enter / Space / C | 确认 | | `@common/exit` | Escape / X | 取消 / 返回 | | `@ui/menu` | Escape | 游戏菜单 | | `@ui/toolbox` | T | 道具界面 | | `@ui/command` | Q | 装备界面 | | `@ui/save` | S | 存档界面 | | `@ui/load` | D | 读档界面 | | `@ui/book` | X | 怪物手册 | | `@ui/input-confirm` | Enter | 输入框确认 | | `@ui/view-map` | PageDown / PageUp | 浏览地图 | 表中只列出常用的 UI 指令;游戏按键与系统按键在 `hotkey.ts` 里另有分组。 ## 边界与注意 - 按键与元素事件是两条独立路径。不要用元素事件去等按键,也不要用按键去模拟点击。 - 指令和分组只在 `src/client/misc/hotkey.ts` 的 `initializeHotkey` 里注册,UI 组件里不调用 `addCommand` / `setGroup`。 - `useKey` 必须在 `setup` 中同步调用,返回可能为 `null`;组件内用非空断言 `!`。 - `useKey` 返回的对象只有 `implement()`、`scope()`、`when()`,不是 `system`,不要在它上面调用按键系统方法。 - 不要按具体按键、`info.keys` 或 `info.context` 判断行为。玩家可以改键,按键和组合会变,按当前键位分支会得到错误的语义;语义不同就拆成不同指令。 - 按键回调保持短小。不要在里面写长时间的异步任务,需要等待的操作另起流程。 - 一条指令确定不再被任何界面使用时,才在 `hotkey.ts` 里用 `system.deleteCommand` 删除;作用域卸载只清理实现,不会删除指令。