HumanBreak/docs/api/motajs-system-action/Hotkey.md

Hotkey API 文档

本文档由 DeepSeek R1 模型生成并微调。

graph LR
    Hotkey --> EventEmitter

    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"

类描述

Hotkey 是按键系统的核心类，用于管理按键绑定、辅助键状态、按键分组及事件触发逻辑。继承自 EventEmitter，支持自定义事件监听。主要用于实现复杂的快捷键系统。

---

属性说明

属性名	类型	描述
id	string	控制器的唯一标识符
name	string	控制器的显示名称
data	Record<string, HotkeyData>	存储所有已注册的按键配置
keyMap	Map<KeyCode, HotkeyData[]>	按键代码到配置的映射（支持多键绑定同一操作）
enabled	boolean	当前控制器是否启用（默认 false）
list（静态）	Hotkey[]	静态属性，存储所有已创建的控制器实例

---

构造方法

function constructor(id: string, name: string): Hotkey;

• 参数
  • id: 控制器的唯一标识符
  • name: 控制器的显示名称

示例

const editorHotkey = new Hotkey('editor', '编辑器快捷键');

---

方法说明

register

function register(data: RegisterHotkeyData): this;

注册一个按键配置。

• 参数

  interface RegisterHotkeyData {
      id: string; // 按键唯一标识（可含数字后缀，如 "copy_1"）
      name: string; // 显示名称（如 "复制"）
      defaults: KeyCode; // 默认按键代码
      ctrl?: boolean; // 是否默认需要 Ctrl 辅助键
      shift?: boolean; // 是否默认需要 Shift 辅助键
      alt?: boolean; // 是否默认需要 Alt 辅助键
  }
  

示例

editorHotkey.register({
    id: 'copy',
    name: '复制',
    defaults: KeyCode.KeyC,
    ctrl: true
});

---

realize

function realize(id: string, func: HotkeyFunc, config?: HotkeyEmitConfig): this;

为按键绑定触发逻辑。

• 参数
  • id: 目标按键 ID（无需后缀）
  • func: 触发时执行的函数
  • config: 触发类型配置（节流/超时等）

示例

editorHotkey.realize(
    'copy',
    (id, key, ev) => {
        console.log('执行复制操作');
    },
    { type: 'down-throttle', throttle: 500 }
);

---

group

function group(id: string, name: string, keys?: RegisterHotkeyData[]): this;

创建按键分组，后续注册的按键自动加入该组。

• 参数
  • id: 分组唯一标识
  • name: 分组显示名称
  • keys: 可选，预注册的按键列表

---

set

function set(id: string, key: KeyCode, assist: number, emit?: boolean): void;

动态修改按键绑定。

• 参数
  • id: 目标按键 ID
  • key: 新按键代码
  • assist: 辅助键状态（二进制位：Ctrl=1<<0, Shift=1<<1, Alt=1<<2）
  • emit: 是否触发 set 事件（默认 true）

---

when

function when(fn: () => boolean): this;

为当前作用域的按键绑定添加触发条件。

• 参数
  • fn: 条件函数，返回 true 时允许触发按键逻辑

示例

// 仅在游戏处于运行状态时允许触发
controller.when(() => gameState === 'running');

---

enable

function enable(): void;

disable

function disable(): void;

启用/禁用整个按键控制器（禁用后所有按键事件将被忽略）。

示例

// 暂停游戏时禁用按键
controller.disable();

---

use

function use(symbol: symbol): void;

切换当前作用域，后续 realize 方法绑定的逻辑将关联到该作用域。

• 参数
  • symbol: 唯一作用域标识符

---

dispose

function dispose(symbol?: symbol): void;

释放指定作用域及其绑定的所有按键逻辑。

• 参数
  • symbol（可选）: 要释放的作用域（默认释放当前作用域）

示例

const scope = Symbol();
controller.use(scope);
// ...绑定操作...
controller.dispose(scope); // 释放该作用域

---

emitKey

function emitKey(
    key: KeyCode,
    assist: number,
    type: KeyEventType,
    ev: KeyboardEvent
): boolean;

手动触发按键事件（可用于模拟按键操作）。

• 参数
  • key: 按键代码
  • assist: 辅助键状态（二进制位：Ctrl=1<<0, Shift=1<<1, Alt=1<<2）
  • type: 事件类型（'up' 或 'down'）
  • ev: 原始键盘事件对象
• 返回值
  true 表示事件被成功处理，false 表示无匹配逻辑

示例

// 模拟触发 Ctrl+S 保存操作
controller.emitKey(
    KeyCode.KeyS,
    1 << 0, // Ctrl 激活
    'down',
    new KeyboardEvent('keydown')
);

---

静态方法说明

Hotkey.get

function get(id: string): Hotkey | undefined;

静态方法：根据 ID 获取控制器实例。

---

事件说明

事件名	参数类型	触发时机
set	[id: string, key: KeyCode, assist: number]	按键绑定被修改时
emit	[key: KeyCode, assist: number, type: KeyEmitType]	按键被触发时
press	[key: KeyCode]	按键被按下时
release	[key: KeyCode]	按键被释放时

事件监听示例

editorHotkey.on('emit', (key, assist) => {
    console.log(`按键 ${KeyCode[key]} 触发，辅助键状态：${assist}`);
});

---

总使用示例

::: code-group

import { gameKey } from '@motajs/system-action';

gameKey.register({
    id: 'jump',
    name: '跳跃',
    defaults: KeyCode.Space
});

import { useKey } from '@motajs/render-vue';

const [gameKey] = useKey();

// 绑定跳跃逻辑
gameKey.realize('jump', () => {
    player.jump();
});

:::