mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-10-31 12:12:58 +08:00
312 lines
6.6 KiB
Markdown
312 lines
6.6 KiB
Markdown
# Hotkey API 文档
|
||
|
||
本文档由 `DeepSeek R1` 模型生成并微调。
|
||
|
||
```mermaid
|
||
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[]` | 静态属性，存储所有已创建的控制器实例 |
|
||
|
||
---
|
||
|
||
## 构造方法
|
||
|
||
```typescript
|
||
function constructor(id: string, name: string): Hotkey;
|
||
```
|
||
|
||
- **参数**
|
||
- `id`: 控制器的唯一标识符
|
||
- `name`: 控制器的显示名称
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
const editorHotkey = new Hotkey('editor', '编辑器快捷键');
|
||
```
|
||
|
||
---
|
||
|
||
## 方法说明
|
||
|
||
### `register`
|
||
|
||
```typescript
|
||
function register(data: RegisterHotkeyData): this;
|
||
```
|
||
|
||
注册一个按键配置。
|
||
|
||
- **参数**
|
||
```typescript
|
||
interface RegisterHotkeyData {
|
||
id: string; // 按键唯一标识（可含数字后缀，如 "copy_1"）
|
||
name: string; // 显示名称（如 "复制"）
|
||
defaults: KeyCode; // 默认按键代码
|
||
ctrl?: boolean; // 是否默认需要 Ctrl 辅助键
|
||
shift?: boolean; // 是否默认需要 Shift 辅助键
|
||
alt?: boolean; // 是否默认需要 Alt 辅助键
|
||
}
|
||
```
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
editorHotkey.register({
|
||
id: 'copy',
|
||
name: '复制',
|
||
defaults: KeyCode.KeyC,
|
||
ctrl: true
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### `realize`
|
||
|
||
```typescript
|
||
function realize(id: string, func: HotkeyFunc, config?: HotkeyEmitConfig): this;
|
||
```
|
||
|
||
为按键绑定触发逻辑。
|
||
|
||
- **参数**
|
||
- `id`: 目标按键 ID（无需后缀）
|
||
- `func`: 触发时执行的函数
|
||
- `config`: 触发类型配置（节流/超时等）
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
editorHotkey.realize(
|
||
'copy',
|
||
(id, key, ev) => {
|
||
console.log('执行复制操作');
|
||
},
|
||
{ type: 'down-throttle', throttle: 500 }
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### `group`
|
||
|
||
```typescript
|
||
function group(id: string, name: string, keys?: RegisterHotkeyData[]): this;
|
||
```
|
||
|
||
创建按键分组，后续注册的按键自动加入该组。
|
||
|
||
- **参数**
|
||
- `id`: 分组唯一标识
|
||
- `name`: 分组显示名称
|
||
- `keys`: 可选，预注册的按键列表
|
||
|
||
---
|
||
|
||
### `set`
|
||
|
||
```typescript
|
||
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`
|
||
|
||
```typescript
|
||
function when(fn: () => boolean): this;
|
||
```
|
||
|
||
为当前作用域的按键绑定添加触发条件。
|
||
|
||
- **参数**
|
||
- `fn`: 条件函数，返回 `true` 时允许触发按键逻辑
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
// 仅在游戏处于运行状态时允许触发
|
||
controller.when(() => gameState === 'running');
|
||
```
|
||
|
||
---
|
||
|
||
### `enable`
|
||
|
||
```typescript
|
||
function enable(): void;
|
||
```
|
||
|
||
### `disable`
|
||
|
||
```typescript
|
||
function disable(): void;
|
||
```
|
||
|
||
启用/禁用整个按键控制器（禁用后所有按键事件将被忽略）。
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
// 暂停游戏时禁用按键
|
||
controller.disable();
|
||
```
|
||
|
||
---
|
||
|
||
### `use`
|
||
|
||
```typescript
|
||
function use(symbol: symbol): void;
|
||
```
|
||
|
||
切换当前作用域，后续 `realize` 方法绑定的逻辑将关联到该作用域。
|
||
|
||
- **参数**
|
||
- `symbol`: 唯一作用域标识符
|
||
|
||
---
|
||
|
||
### `dispose`
|
||
|
||
```typescript
|
||
function dispose(symbol?: symbol): void;
|
||
```
|
||
|
||
释放指定作用域及其绑定的所有按键逻辑。
|
||
|
||
- **参数**
|
||
- `symbol`（可选）: 要释放的作用域（默认释放当前作用域）
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
const scope = Symbol();
|
||
controller.use(scope);
|
||
// ...绑定操作...
|
||
controller.dispose(scope); // 释放该作用域
|
||
```
|
||
|
||
---
|
||
|
||
### `emitKey`
|
||
|
||
```typescript
|
||
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` 表示无匹配逻辑
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
// 模拟触发 Ctrl+S 保存操作
|
||
controller.emitKey(
|
||
KeyCode.KeyS,
|
||
1 << 0, // Ctrl 激活
|
||
'down',
|
||
new KeyboardEvent('keydown')
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 静态方法说明
|
||
|
||
### `Hotkey.get`
|
||
|
||
```typescript
|
||
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]` | 按键被释放时 |
|
||
|
||
**事件监听示例**
|
||
|
||
```typescript
|
||
gameKey.on('emit', (key, assist) => {
|
||
console.log(`按键 ${KeyCode[key]} 触发，辅助键状态：${assist}`);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 总使用示例
|
||
|
||
::: code-group
|
||
|
||
```typescript [注册]
|
||
import { gameKey } from '@motajs/system-action';
|
||
|
||
gameKey.register({
|
||
id: 'jump',
|
||
name: '跳跃',
|
||
defaults: KeyCode.Space
|
||
});
|
||
```
|
||
|
||
```typescript [实现]
|
||
import { useKey } from '@motajs/render-vue';
|
||
|
||
const [gameKey] = useKey();
|
||
|
||
// 绑定跳跃逻辑
|
||
gameKey.realize('jump', () => {
|
||
player.jump();
|
||
});
|
||
```
|
||
|
||
:::
|