tanstack-hotkeys

TanStack Hotkeys

概述

TanStack Hotkeys 是一个适用于 React 的类型安全键盘快捷键库，提供模板字符串绑定、跨平台的 Mod 键抽象（macOS 上为 Cmd，Windows/Linux 上为 Ctrl）以及适用于 SSR 的实用工具。它提供用于单个快捷键、多键序列、快捷键录制和实时按键状态跟踪的钩子，还支持感知平台的显示格式化。

适用场景： 为 React 应用添加键盘快捷键、录制用户自定义快捷键、检测按住的修饰键、显示特定平台的快捷键标签、实现 Vim 风格的按键序列。

不适用场景： 没有包装器的非 React 应用（虽然有核心包，但主要面向 React），需要完整按键映射管理的复杂输入处理（可考虑专用按键映射库）。

快速参考

模式	API	要点
单个快捷键	useHotkey	Mod 抽象 Cmd/Ctrl；组合键会自动阻止默认行为
多键序列	useHotkeySequence	Vim 风格序列，例如 g g；超时时间可配置
录制快捷键	useHotkeyRecorder	用户自定义快捷键；可开始、停止或取消录制
检测按住的按键	useKeyHold	获取特定按键的布尔状态；优化重新渲染
跟踪所有按住的按键	useHeldKeys	当前按下的按键名称数组
跟踪按住按键的代码	useHeldKeyCodes	按键名称到物理 event.code 值的映射
全局默认值	HotkeysProvider	为所有钩子设置默认选项；各钩子的选项会覆盖默认值
格式化以供显示	formatForDisplay	感知平台：macOS 符号与 Windows/Linux 文本
限定到元素	target 选项 + ref	目标元素需要设置 tabIndex 才能获得焦点
条件快捷键	enabled 选项	动态启用/禁用，无需卸载

常见错误

错误	正确做法
限定目标元素缺少 tabIndex	为使用 target ref 获取焦点的元素添加 tabIndex={-1}（或 0）
使用 Ctrl 而不是 Mod	使用 Mod 以实现跨平台支持；它会映射为 Cmd（Mac）或 Ctrl（Win/Linux）
认为快捷键会在输入框内触发	ignoreInputs 默认会智能检测；设为 false 可强制触发
未配置就重复注册快捷键	设置 conflictBehavior: 'replace' 以覆盖，或设为 'error' 以捕获冲突
忘记 preventDefault 会自动启用	修饰键组合会自动阻止默认行为；设置 preventDefault: false 可允许默认行为
使用 keyup 却未设置 requireReset	将 eventType: 'keyup' 与 requireReset: true 配合使用，以便只触发一次

委派

如果有 tanstack-pacer 技能，请将节流和防抖任务委派给它。TanStack Pacer 适用于限制快捷键回调的触发频率。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s tanstack-pacer -a claude-code -y

如果有 tanstack-devtools 技能，请将 DevTools 设置委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s tanstack-devtools -a claude-code -y

• 键盘快捷键和热键：使用此技能
• 快捷键回调的节流/防抖：委派给 tanstack-pacer
• DevTools 集成：委派给 tanstack-devtools

参考资料

• React 钩子和配置
• 序列和录制
• 格式设置和显示