tanstack-hotkeys

TanStack Hotkeys

当工作涉及 TanStack Hotkeys 时使用此技能，尤其是 React 键盘快捷键、命令面板、快捷键设置 UI、作用域快捷键、Vim 风格序列或按键按住状态。

工作流

1. 修改代码前，检查本地快捷键技术栈：
   • @tanstack/react-hotkeys（0.12.x）、@tanstack/hotkeys（0.10.x）、devtools、React、框架适配器和测试工具的包版本。针对 core 0.8 或更早版本编写的代码可能依赖 0.9 之前的录制器和类型行为。
   • 快捷键形式：单次热键、动态快捷键列表、元素作用域快捷键、全局默认项、序列、用户录制的绑定或快捷键面板。
   • 交互限制：聚焦的输入框、模态框、命令面板、浏览器原生快捷键、应用模式、禁用状态和无障碍性。
2. 当行为或版本很重要时，查阅最新文档和包的相关证据。从 source-map.md 开始。
3. 有关安装、ESM/运行时要求、逻辑绑定与物理绑定、HotkeysProvider、useHotkey、useHotkeys、默认项、选项、作用域目标和注册，请参阅 setup-core.md。
4. 有关 useHotkeySequence、useHotkeySequences、useHotkeyRecorder、useHotkeySequenceRecorder、录制器验证/冲突、按住按键的钩子、useHotkeyHint 和动态用户快捷键，请参阅 sequences-recording-state.md。
5. 有关显示格式、快捷键面板、devtools、SSR 注意事项、无障碍性和测试，请参阅 display-production.md。

实现判断

• 跨平台应用快捷键优先使用 Mod；它在 macOS 上映射为 Command，在 Windows/Linux 上映射为 Control。
• 将此库视为 alpha（0.x）。依赖边缘行为时，尤其是录制器选项、绑定类型和序列处理，应先核对当前文档。自 core 0.10 起，包仅支持 ESM。
• 对助记快捷键使用逻辑绑定（Mod+S），对基于位置的控件使用物理绑定（Mod+[KeyS]、{ code: 'KeyS', mod: true }）。绑定只能包含 key 或 code，不能两者兼有。
• 固定快捷键使用 useHotkey，动态或长度可变的列表使用 useHotkeys。不要在循环中调用钩子来注册菜单数据。
• 使用 target refs 将热键限定在面板、编辑器和模态框内。确保目标可以接收焦点，通常需要设置 tabIndex。
• 有意识地设置 preventDefault 和 stopPropagation。它们默认值为 true，适用于 Mod+S 这类应用快捷键，但若应保留浏览器原生行为，则不适用。
• 尊重常规输入行为。强制单键快捷键在文本输入框中触发前，先了解智能默认项 ignoreInputs。
• 使用 enabled 控制模式/状态。禁用的热键仍会注册，并在 devtools 中显示；只是不会执行。
• 对于会显示在帮助页面、命令面板或 devtools 中的快捷键，添加 meta 名称、描述和 group。
• 仅在用户可自定义快捷键的设置 UI 中使用录制器钩子。录制器默认使用 recordBy: 'code'（例如 Mod+[KeyS] 这样的物理字符串）；清除时只会调用 onClear。使用 validate、detectConflicts 和 onReject，而不是手动编写重复项检查。持久化经过规范化的 Hotkey 或 HotkeySequence 值，而不是显示标签。

验证

优先使用仓库现有的检查。对于有实际意义的 TanStack Hotkeys 更改，请包含相关子集：

• 对热键字符串、Hotkey/HotkeySequence 值、RawHotkey/ParsedHotkey 联合类型、目标 ref 和适配器导入进行类型检查。
• 执行单元测试或组件测试（使用同时包含 key 和 code 的合成事件），验证回调触发、enabled、ignoreInputs、preventDefault、stopPropagation、目标焦点以及卸载时的清理。
• 在浏览器中进行冒烟测试，验证跨平台显示标签、聚焦输入框时的行为、模态框作用域、命令面板快捷键以及序列超时。
• 使用伪计时器测试序列超时、录制器空闲提交，以及围绕快捷键捕获的防抖 UI。
• 检查开发者工具，验证重复注册、已禁用的注册、按住的按键、目标作用域以及冲突行为。