simplex2-sdk-util Keyboard

功能说明

Keyboard 是一个浏览器端键盘事件监听工具，支持单键和组合键（如 Ctrl+A、Shift+Z）监听，自动处理修饰键，适用于快捷键、表单增强、游戏等场景。支持多实例并行，事件解绑和销毁，API 简单易用。

Example

import Keyboard from '@simplex2-sdk-util/keyboard';

// 创建实例，默认阻止原生事件
const keyboard = new Keyboard();

// 单键监听
keyboard.onKeyDown('myKey', keyName => {
  console.log('按下:', keyName);
});

// 组合键监听
keyboard.onComboKey(
  'combo',
  comboKeys => {
    // comboKeys 如 ['Control', 'a']
    console.log('组合键按下:', comboKeys);
    if (comboKeys.includes('Control') && comboKeys.includes('a')) {
      // 只处理 Ctrl+A
    }
  },
  comboKeys => {
    console.log('组合键抬起:', comboKeys);
  }
);

// 解绑事件
keyboard.offKeyDown('myKey');
keyboard.offComboKey('combo');

// 销毁所有监听
keyboard.destroy();

// 多实例并行监听
const keyboard2 = new Keyboard({ stopOriginalEvent: false });
keyboard2.onKeyDown('other', key => { /* ... */ });

Features

• 支持单键和组合键监听，组合键顺序与实际按键一致
• 自动处理 Ctrl、Meta、Shift、Alt 等修饰键，抬起时自动清空队列
• 组合键抬起事件完整（如 Ctrl+A 抬起 A 键可监听）
• 可自定义是否阻止原生事件（如表单输入场景）
• 多实例并行监听，互不干扰
• 支持事件解绑和销毁，防止内存泄漏

Installation

npm install @simplex2-sdk-util/keyboard

Usage

import Keyboard from '@simplex2-sdk-util/keyboard';

const keyboard = new Keyboard({ stopOriginalEvent: true });

Options

构造参数

• stopOriginalEvent (boolean)：是否阻止原生事件，默认 true。适合快捷键场景，表单输入建议设为 false。
• comboKeyClearTimeout (number)：组合键清空延迟（毫秒），默认 500。极端场景可调整。

Default options

options = {
  stopOriginalEvent: true, // 是否阻止原生事件
  comboKeyClearTimeout: 500 // 组合键清空延迟（毫秒）
}

API

Methods

• onKeyDown(name: string, fn: (keyName: string) => void) 注册单键按下事件。name 用于唯一标识和解绑。
• offKeyDown(name: string) 移除单键事件。
• onComboKey(name: string, downFn: (comboKeys: string[]) => void, upFn: (comboKeys: string[]) => void) 注册组合键按下/抬起事件。
• offComboKey(name: string) 移除组合键事件。
• destroy() 清理所有事件监听。

参数说明

• name：事件唯一标识，建议使用业务相关英文名。
• fn/downFn/upFn：回调函数，参数为当前按下/抬起的键名或组合键数组。

事件机制说明

• 单键监听通过 window.keydown 事件，组合键监听通过 keydown+keyup 事件，内部维护队列。
• 修饰键（Ctrl、Meta、Shift、Alt）抬起时自动清空队列，防止组合键残留。
• 组合键队列顺序与实际按键顺序一致，便于区分如 Ctrl+Z 与 Z+Ctrl。
• 回调中可根据 comboKeys 内容灵活处理任意组合。

边界与异常处理

• 浏览器兼容性：支持主流现代浏览器，部分特殊键（如 Fn、系统键）可能无法监听。
• 冲突处理：建议每个监听用唯一 name，避免重复注册导致解绑失效。
• 性能优化：大量监听时建议及时解绑和 destroy，避免内存泄漏。

最佳实践

• name 推荐用业务英文名，如 'saveShortcut'、'formEnter'，便于管理和解绑。
• 表单输入场景建议 stopOriginalEvent 设为 false，避免阻止输入。
• 组合键监听时，回调中判断 comboKeys 内容，只处理需要的组合。

注意事项

• 组合键监听时，建议使用唯一 name 标识，避免冲突
• 修饰键抬起时自动清空组合队列，防止残留
• 支持多实例并行监听

常见问题

• Q: 为什么 Ctrl+A 抬起 A 键时能监听到？ A: 内部先移除抬起的键，再判断是否为修饰键清空队列，保证抬起事件完整。

• Q: 如何只监听某些组合键？ A: 在回调中判断 comboKeys 内容即可。

• Q: 如何防止事件冲突或内存泄漏？ A: 每个监听用唯一 name，及时解绑和 destroy。

• Q: 可以监听所有键盘按键吗？ A: 支持主流键盘按键，部分特殊键（如 Fn、系统键）受限于浏览器。

如需更多高级用法或定制，请查阅源码或联系维护者。