SuperAPI AI 工具集

hotkeys-core

编程与开发

查看项目

更新于 10-28 20:34

技能介绍

TanStack Hotkeys 的核心理念是“由库接管键盘”。添加、修复或审查键盘快捷键时,应通过所用框架适配器的快捷键 API(如 useHotkey、createHotkey、injectHotkey 或 @hotkey)在拥有该动作的组件中注册每个快捷键,所有导入均来自适配器包,适配器会重新导出 @tanstack/hotkeys。API 的准确签名可查阅已安装的声明文件:适配器的 dist/*.d.ts,以及核心包的 hotkey.types.d.ts(快捷键字符串)和 hotkey-manager.d.ts(HotkeyOptions)。

主要能力与替代方案:使用已注册快捷键(如 'Mod+S')替代检查 event.key、metaKey 或 ctrlKey 的 keydown 监听器;在控件自身按键处理中可用 matchesKeyboardEvent(event, 'Mod+Enter')。用快捷键中的 Mod 和 formatForDisplay(hotkey) 生成显示标签,替代 isMac 判断与 ⌘/Ctrl 标签映射。默认行为已处理文本字段事件跳过与 preventDefault:单键和 Shift/Alt 组合在输入时跳过,Mod 组合与 Escape 仍会触发,匹配的按键会被阻止默认行为。用适配器 API 替代自建注册表、服务、上下文或包装 hook;需要集中列出全部快捷键时加载 @tanstack/hotkeys。用 scope(作用域)及 exclusive 处理对话框置顶;用 meta: { name } 与适配器注册列表生成帮助对话框快捷键清单;用适配器持有的按键与提示 API 替代 keydown/keyup 状态跟踪;用适配器的记录器捕获下一次按键以用于设置界面。

快捷键的开启与关闭按以下顺序选择第一种合适机制:生命周期,组件挂载期间快捷键存在,对话框的 Escape 应由对话框自身注册;enabled,在已挂载组件内按条件启用;scope,一组同时开关的作用域(如对话框、面板、标签页),exclusive 作用域激活时会挂起其他所有作用域(含全局快捷键);target,仅当焦点位于某个可聚焦元素(tabindex="0")内时生效。嵌套作用域、堆叠对话框或需在 exclusive 作用域期间保留部分快捷键时,应查阅作用域相关说明。

常见陷阱:禁用快捷键并不阻止浏览器,enabled: false 时 Mod+S 会打开“保存页面”对话框,需要阻止时加 preventDefault: 'always';为把按键交还浏览器而关闭的快捷键(如 Mod+C、Mod+Z、Tab 或用户关闭开关后的单键)不应加。不要保持快捷键启用却在回调中提前返回,否则它仍会出现在应用快捷键列表并显示提示。修饰键需精确匹配,Shift 按住时 ArrowDown 永不触发,应注册 Shift+ArrowDown;符号所需的 Shift 是例外,如 ? 匹配 Shift+/。组合键按住会重复触发,开关类应设 requireReset: true。字母按输入字符匹配,WASD 等位置型控件应使用物理绑定如 '[KeyW]',助记命令如 Mod+S 保留字母。每个打开的 exclusive 作用域需各自名称,可复用对话框用固定作用域名在嵌套时会冲突。序列首键上的组合键每次序列开始都会执行,G 与 ['G','G'] 并存时首个 G 会触发该组合键;要显示“等待下一个键”可读取适配器注册列表的 matchedStepCount。单字符快捷键需有开关,WCAG 2.1.4 要求 K、? 和 ['G','H'] 需用户设置传入 enabled 或提供可重映射的应用快捷键。react-hotkeys-hook 名称不迁移,useHotkeys 与 HotkeysProvider 仅共享名称而非签名,需移除旧库以免两个库处理相同按键;只安装适配器,单独安装其他版本的 @tanstack/hotkeys 会形成第二份副本,作用域不跨副本生效。为快捷键编写测试时查阅 testing 相关内容。