lowcode-engine hotkey 快捷键 API 完全指南绑定、组合语法与内置快捷键实现原理【免费下载链接】lowcode-engineAn enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系项目地址: https://gitcode.com/GitHub_Trending/lo/lowcode-engine本文基于 hotkey - 快捷键 API 展开结合 Hotkey 核心实现、类型定义 与 内置快捷键插件 的源码系统讲解 lowcode-engine 中 hotkey API 的用法、组合键语法、底层事件机制以及引擎内置快捷键的完整清单。lowcode-engine 的hotkey是挂在插件上下文IPublicModelPluginContext上的快捷键 API用于为低代码设计器自定义项目级快捷键。本文从bind方法的签名与返回类型讲起覆盖基础绑定、多组合键绑定、在插件中注册保存 schema 快捷键等官方示例并深入源码分析键名归一化、修饰键解析、keypress/keydown 事件选择与序列快捷键等底层原理最后给出引擎内置快捷键的完整实现清单帮助你快速上手并安全扩展自定义快捷键。模块简介hotkey API 是什么在 lowcode-engine 中hotkeyAPI 允许开发者为编辑器绑定自定义快捷键。官方文档docs/docs/api/hotkey.md给出的定位是绑定快捷键 API可以自定义项目快捷键使用。从源码角度hotkey 由两个层次组成内部实现packages/editor-core/src/hotkey.ts中的Hotkey类负责键盘事件的监听、键名解析与回调分发对外类型packages/types/src/shell/api/hotkey.ts中的IPublicApiHotkey接口定义了对外暴露的bind方法与callbacks属性。在引擎装配过程中packages/engine/src/engine-core.ts#L118-L119引擎会创建内部热键实例并将其包装为对外可用的 shell 层Hotkeyconst innerHotkey new InnerHotkey(); const hotkey new Hotkey(innerHotkey);随后通过context.hotkey hotkeypackages/engine/src/engine-core.ts#L143注入每个插件的上下文因此插件内可以直接解构使用const { hotkey } ctx;。bind 方法绑定快捷键方法签名与参数说明bind是IPublicApiHotkey暴露的核心方法签名如下packages/types/src/shell/api/hotkey.ts#L20-L24/** * 绑定快捷键 * bind hotkey/hotkeys, * param combos 快捷键格式如[command s] 、[ctrl shift s] 等 * param callback 回调函数 * param action */ bind( combos: string[] | string, callback: IPublicTypeHotkeyCallback, action?: string, ): IPublicTypeDisposable;参数说明参数类型说明combosstring \| string[]快捷键组合可传入单个字符串如commands或字符串数组如[commands, commandc]数组表示多个组合键共享同一回调callbackIPublicTypeHotkeyCallback快捷键触发时的回调函数接收键盘事件与组合键字符串actionstring \| undefined可选指定监听的事件类型取值通常为keydown、keypress或keyup不传时由引擎自动选择详见下文事件类型选择回调与返回类型回调类型定义于 packages/types/src/shell/type/hotkey-callback.tsexport type IPublicTypeHotkeyCallback (e: KeyboardEvent, combo?: string) any | false;即回调接收两个参数e原生KeyboardEvent可用于调用e.preventDefault()阻止默认行为combo触发本次回调的组合键字符串方便同一回调在绑定多个组合键时区分来源内置快捷键插件中大量使用了这个参数例如通过action.indexOf(x)判断是复制还是剪切。返回类型IPublicTypeDisposablepackages/types/src/shell/type/disposable.ts是一个可执行函数类型export interface IPublicTypeDisposable { (): void; }实现层面bind返回 Hotkey 实例本身packages/editor-core/src/hotkey.ts#L384-L387同时内部维护了callbacks注册表配合unbind方法可以按组合键与回调引用精确解绑packages/editor-core/src/hotkey.ts#L389-L402。使用示例基础示例单个组合键绑定按下commands时阻止浏览器默认的保存页面行为并执行自定义逻辑hotkey.bind(commands, (e) { e.preventDefault(); // commands 快捷键按下时需要执行的逻辑 });同时绑定多个快捷键传入字符串数组commands或commandc任一触发都会执行同一回调hotkey.bind([commands, commandc], (e) { e.preventDefault(); // commands 或者 commandc 快捷键按下时需要执行的逻辑 });保存快捷键配置插件内使用结合插件机制可以在插件init阶段注册快捷键将commands绑定到 schema 保存逻辑上import { hotkey, } from alilc/lowcode-engine; function saveSchema(schema) { // 保存 schema 相关操作 } const saveSampleHotKey (ctx: IPublicModelPluginContext) { return { name: saveSample, async init() { hotkey.bind(commands, (e) { e.preventDefault(); saveSchema(); }); }, }; } saveSampleHotKey.pluginName saveSampleHotKey; plugins.register(saveSampleHotKey);注意这里hotkey可以直接从alilc/lowcode-engine导入也可以在插件init(ctx)中通过ctx.hotkey获取——引擎装配时已将 hotkey 注入插件上下文packages/engine/src/engine-core.ts#L143两者指向同一实例。快捷键组合语法深入修饰键与别名Hotkey 实现中定义了修饰键别名表packages/editor-core/src/hotkey.ts#L97-L104const SPECIAL_ALIASES: CtrlKeyMap { option: alt, command: meta, return: enter, escape: esc, plus: , mod: /Mac|iPod|iPhone|iPad/.test(navigator.platform) ? meta : ctrl, };这意味着command等价于metamacOS 的 ⌘ 键option等价于altreturn等价于enterescape等价于escmod是一个跨平台快捷别名在 macOS 上解析为meta在 Windows/Linux 上解析为ctrl。需要同时兼容 Mac 与 Windows 用户的快捷键建议直接写mods引擎会自动适配平台。特殊功能键源码中的键码映射表packages/editor-core/src/hotkey.ts#L31-L54支持以下特殊键名backspace、tab、enter、shift、ctrl、alt、capslock、esc、space、pageup、pagedown、end、home、left、up、right、down、ins、del、meta。此外代码通过循环自动补充了f1至f19功能键packages/editor-core/src/hotkey.ts#L112-L114以及数字小键盘的0-9packages/editor-core/src/hotkey.ts#L119-L121。因此你可以直接绑定类似f2、altf4这样的组合。组合键写法组合键使用连接例如文档中的command s、ctrl shift s也可以省略空格写作commands。解析逻辑位于 packages/editor-core/src/hotkey.ts#L254-L261 的keysFromString它会按拆分并将连续两个归一化为plus用于单独绑定键。序列快捷键组合式连按除了单个组合键Hotkey 还支持序列快捷键用空格分隔多个按键按顺序依次按下才触发。例如g i表示先按g再按i。序列实现位于bindSequencepackages/editor-core/src/hotkey.ts#L571-L595且序列状态会在 1 秒无操作后自动重置packages/editor-core/src/hotkey.ts#L564-L569。底层实现原理事件监听与激活开关Hotkey构造时会通过mount(window)在document上同时监听keypress、keydown、keyup三类事件packages/editor-core/src/hotkey.ts#L371-L382并在handleKeyEvent入口处检查激活开关packages/editor-core/src/hotkey.ts#L544-L562private handleKeyEvent(e: KeyboardEvent): void { if (!this.isActivate) { return; } // ... }isActivate通过activate(activate: boolean)方法控制packages/editor-core/src/hotkey.ts#L367-L369可整体启用/停用快捷键响应。事件类型选择pickBestActionpackages/editor-core/src/hotkey.ts#L234-L246决定默认监听哪种事件若未显式传入action功能键如esc、f1默认走keydown普通字符键默认走keypress一旦组合中包含修饰键shift/ctrl/alt/metakeypress会自动切换为keydown因为修饰键在 keypress 下行为不一致。这也是bind的第三个参数action存在的意义需要监听keyup如某些拖拽结束手势时可显式传入keyup。回调触发与全局事件fireCallbackpackages/editor-core/src/hotkey.ts#L317-L340) 是回调执行的核心函数它的行为值得注意通过globalContext获取当前激活的 workspace 与 editor进而取得 designer 与当前选中节点拼出selected标识格式为package-componentName或组件名若回调返回false按 jQuery 惯例自动执行e.preventDefault()与e.stopPropagation()无论回调结果如何都会向编辑器事件总线发出hotkey.callback.call事件携带{ callback, e, combo, sequence, selected }参数——这意味着你可以监听该事件实现快捷键调用埋点或日志。内置快捷键的实现范式引擎内置的快捷键全部注册在 packages/engine/src/inner-plugins/builtin-hotkey.ts 的builtinHotkey插件中插件名为___builtin_hotkey___其统一范式是在init()中解构ctx后调用hotkey.bind。以下是完整的绑定清单组合键功能实现位置builtin-hotkey.tsbackspace/del删除当前选中的顶层节点L230escape清空当前选择L254commandc/ctrlc/commandx/ctrlx复制 / 剪切选中节点到剪贴板L271commandv/ctrlv粘贴剪贴板中的节点 schema 到合适插入位置L314commandz/ctrlz撤销history.backL351commandy/ctrly/commandshiftz重做history.forwardL369left/right选中上一个/下一个兄弟节点L386up/down按文档树顺序选中上/下相邻节点L405optionleft/optionright将选中节点前移/后移一个兄弟位置L430optionup将节点上移遇到容器节点时尝试移入其内部L464optiondown将节点下移遇到容器节点时尝试移入其内部L506所有内置回调开头都有一段防御性检查通过canvas.isInLiveEditing判断是否处于 live editing在线编辑态、通过isFormEvent(e)判断事件是否来自表单输入避免在输入框中按backspace误删节点并在确认安全后才执行e.preventDefault()与后续逻辑。其他可用能力callbacks 与 unbindIPublicApiHotkey还暴露了以下能力标注为experimental自 v1.1.0 起callbacksgetter返回当前所有已绑定的快捷键配置packages/types/src/shell/api/hotkey.ts#L11结构为IPublicTypeHotkeyCallbacks即以按键字符为 key、IPublicTypeHotkeyCallbackConfig[]为值的映射packages/types/src/shell/type/hotkey-callbacks.ts。每条配置包含callback、modifiers、action以及序列快捷键的seq/level/combo字段packages/types/src/shell/type/hotkey-callback-config.ts。该 getter 目前仅在类型层面声明属于实验性能力使用时建议先确认所在版本已实现。unbind(combos, callback, action?)按组合键与回调引用移除绑定实现会通过isEqual精确比对修饰键数组后从注册表中剔除packages/editor-core/src/hotkey.ts#L389-L402。最佳实践与注意事项优先使用mod而非硬编码command/ctrlmod会根据navigator.platform自动映射为 Mac 的meta或其它平台的ctrlpackages/editor-core/src/hotkey.ts#L103一份绑定即可覆盖全平台。引擎内置的复制粘贴、撤销重做快捷键都同时绑定了command与ctrl两套也是为了保证跨平台可用。在回调中主动调用e.preventDefault()低代码设计器页面内commands等组合键可能触发浏览器默认行为绑定后请按官方示例显式阻止默认事件。区分表单输入场景参考内置快捷键插件的写法绑定backspace、方向键等高频键时应先用isFormEvent(e)判断事件是否来自输入框/富文本编辑区避免影响正常输入packages/engine/src/inner-plugins/builtin-hotkey.ts#L238。利用回调第二参数区分组合来源当多个组合键共享回调时combo参数可以帮你判断当前触发的是哪一个如内置插件中通过action.indexOf(x) 0区分复制与剪切packages/engine/src/inner-plugins/builtin-hotkey.ts#L303。避免覆盖内置快捷键引擎已占用删除、复制粘贴、撤销重做、方向键选择、option方向键移动等组合完整清单见上文表格自定义快捷键时应尽量避开这些组合以免与设计器既有交互冲突。相关文件索引API 文档docs/docs/api/hotkey.md对外类型定义packages/types/src/shell/api/hotkey.ts、hotkey-callback.ts、disposable.ts核心实现packages/editor-core/src/hotkey.ts引擎装配与上下文注入packages/engine/src/engine-core.ts#L118-L143内置快捷键插件packages/engine/src/inner-plugins/builtin-hotkey.ts【免费下载链接】lowcode-engineAn enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系项目地址: https://gitcode.com/GitHub_Trending/lo/lowcode-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考