From ddbc2825c4050ccc23d8dd5a01e27b66de224e6e Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Wed, 21 Oct 2026 17:20:42 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=8C=E5=96=84=E6=8C=89=E9=94=AE?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E6=8E=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/system/src/hotkey/type.ts | 54 ++++++++++++++++++++++++++----
 1 file changed, 48 insertions(+), 6 deletions(-)

diff --git a/packages/system/src/hotkey/type.ts b/packages/system/src/hotkey/type.ts
index ff799cb..7632d7b 100644
--- a/packages/system/src/hotkey/type.ts
+++ b/packages/system/src/hotkey/type.ts
@@ -12,7 +12,9 @@ export const enum HotkeyEmitMode {
     /** 只会触发一次 */
     Once,
     /** 按下后依据激励源进行触发 */
-    Excited
+    Continuous,
+    /** 按下后节流触发 */
+    Throttle
 }
 
 export interface IHotkeyEmitContext {
@@ -46,6 +48,14 @@ export interface IHotkeyEmitInfo {
 export interface IHotkeyCommand {
     /** 当前指令可以被多少种按键组合触发 */
     readonly length: number;
+    /** 按键触发方式 */
+    readonly mode: HotkeyEmitMode;
+    /** 首次触发与第二次触发的最小时间间隔 */
+    readonly interval: number;
+    /** 按下后距离第一次触发的最小时间间隔 */
+    readonly timeout: number;
+    /** Throttle 模式下，两次触发之间的最小时间间隔 */
+    readonly dt: number;
 
     /**
      * 设置此按键组合数量，如果小于当前值，会导致某些按键触发组合被删除
@@ -72,18 +82,36 @@ export interface IHotkeyCommand {
     iterateKeyCombinations(): Iterable<[index: number, key: KeyCode[]][]>;
 
     /**
-     * 按下时只触发一次，不会连续触发
+     * 按下后，在经过 `timeout` 时间后只触发一次，不会连续触发
+     * @param timeout 按下后距离首次触发的时间间隔，单位毫秒，默认为 0
      */
-    once(): void;
+    once(timeout?: number): void;
 
     /**
      * 当按下后立刻进行一次触发，之后在松开前，会按照激励源的激励触发
-     * @param excitation 触发激励源
+     * @param interval 第一次触发距离第二次触发的最小时间间隔，设置后，按下时会立刻进行一次触发，
+     *                 而第二次触发需要等待 `interval` 毫秒才会触发。默认为 0
+     * @param timeout 按下后距离首次触发的时间间隔，单位号码，默认为 0
      */
-    continuous(excitation: IExcitation<unknown>): void;
+    continuous(interval?: number, timeout?: number): void;
+
+    /**
+     * 当按下后立刻进行一次触发，之后在松开前，会根据激励源的激励进行触发，两次触发的触发间隔不小于节流间隔
+     * @param dt 节流间隔
+     * @param interval 第一次触发距离第二次触发的最小时间间隔，设置后，按下时会立刻进行一次触发，
+     *                 而第二次触发需要等待 `interval` 毫秒才会触发。默认为 0
+     * @param timeout 按下后距离首次触发的时间间隔，单位号码，默认为 0
+     */
+    throttle(dt: number, interval?: number, timeout?: number): void;
 }
 
 export interface IHotkeySystem {
+    /**
+     * 设置当前按键系统由指定激励源所激励，用于连续触发按下后持续触发等触发场景
+     * @param excitation 激励源
+     */
+    excitedBy(excitation: IExcitation<number>): void;
+
     /**
      * 进入新的按键作用域
      */
@@ -121,10 +149,24 @@ export interface IHotkeySystem {
     implement(command: string, func: (ctx: IHotkeyEmitContext) => void): void;
 
     /**
-     * 触发指定按键命令
+     * 手动触发指定按键命令
      * @param command 按键指令标识符
      * @param context 按键的上下文信息
      * @returns 是否执行成功，如果按键命令不存在或上下文条件无法触发指定按键指令，会返回 `false`
      */
     emit(command: string, context: IHotkeyEmitContext): boolean;
+
+    /**
+     * 按下指定按键
+     * @param key 按键码
+     * @returns 是否至少有一个已实现的指令被因此触发，包括将要延时触发的
+     */
+    down(key: KeyCode): boolean;
+
+    /**
+     * 松开指定按键
+     * @param key 按键码
+     * @returns 是否至少有一个已实现的指令被因此触发，包括将要延时触发的
+     */
+    up(key: KeyCode): boolean;
 }