UI 热键 API

客户端 UI 脚本通过全局对象 Hotkeys（大写）注册/管理 UI 热键。

UI 热键只在当前 UI 上下文生效（按 storeId/runtimeContextKey 隔离）。

Quick Start

const id = Hotkeys.register({
  pattern: "CTRL+K",
  trigger: "press",
  consume: true,
  priority: 10
}, (payload) => {
  console.log("触发热键:", payload.pattern)
})

Hotkeys.unregister(id)
Hotkeys.clear()

API Reference

Hotkeys.register(options, callback?)

注册一条 UI 热键，返回热键 ID；注册失败返回 null。

• callback 与 options.on 二选一；若都提供，优先使用 options.on。
• 必须提供回调，否则注册失败。

参数	类型	说明
options	object	热键选项，见下方字段表
callback	function	触发回调（可选）

返回值：string | null

Hotkeys.unregister(id)

注销指定 ID 的热键。

参数	类型	说明
id	string	register 返回的热键 ID

返回值：boolean

Hotkeys.clear()

清理当前 UI 上下文注册的全部热键。

Hotkeys.list()

返回当前 UI 上下文已注册的热键 ID 列表。

返回值：string[]

options 字段参考

字段	类型	默认值	说明
pattern / keys	string	--	热键模式，必填
trigger	string	"press"	press / release / hold
consume	boolean	true	命中后是否阻断后续匹配
allowWhenTyping	boolean	false	输入组件聚焦时是否允许触发
priority	int	0	优先级（越大越先触发）
cooldownMs / cooldown	int	0	冷却时间（毫秒）
sequenceIntervalMs / sequenceInterval	int	320	连招步进最大间隔（毫秒）
holdMs / hold	int	null	按住触发阈值（毫秒）
id	string	自动生成	可选自定义 ID
on	function	null	回调函数（优先于第二参数 callback）

pattern 语法

语法	写法	说明
连招	"W, W"	逗号分隔，依序按下
组合键	"CTRL+K"	+ 表示同一时间按下
按住	"F@300"	@ 后毫秒数，达到时触发
组合按住	"SHIFT+RMB@600"	支持组合 + 按住

回调 payload

回调收到对象结构：

字段	类型	说明
id	string	热键 ID
context	string	固定为 "ui"
trigger	string	"press" / "release" / "hold"
time	number	客户端触发时间戳（ms）
source	string	固定为 "ui"
pattern	string	匹配到的原始 pattern

{
  id: "panel:hotkey:1",
  context: "ui",
  trigger: "press",
  time: 1700000000000,
  source: "ui",
  pattern: "CTRL+K"
}

常见问题

1. UI 热键只在当前 UI 上下文生效，不会影响其他 UI。
2. allowWhenTyping = false 时，TextField/TextArea/TagField 聚焦下不会触发。
3. Hotkeys.clear() 仅清理当前 UI 上下文，不会删除服务端热键。