用途:在 React 应用中实现类型安全的键盘快捷键功能,包名为 @tanstack/react-hotkeys。所有框架包会重新导出 @tanstack/hotkeys 核心内容,无需单独安装核心包。
主要能力:useHotkey(hotkey, callback, options?) 是主 Hook,接受字符串(如 'Mod+S')或 RawHotkey 对象({ key: 'S', mod: true });回调接收 (event, context),每次渲染自动同步回调以避免闭包过期,卸载时自动清理。Mod 在 macOS 解析为 Meta(Cmd),在 Windows/Linux 解析为 Control。useHotkeySequence 支持 Vim 风格多键序列,按键需在 timeout(默认 1000ms)内按顺序输入,重叠前缀可独立跟踪。useHotkeyRecorder 用于录制自定义快捷键,返回 isRecording、recordedHotkey、startRecording、stopRecording、cancelRecording,Escape 取消录制,Backspace/Delete 清除,并自动转换为可移植的 Mod 格式。
按键状态与显示:useHeldKeys 返回所有按住的键,useKeyHold 检查单个键(仅在该键变化时重渲染),useHeldKeyCodes 提供键到 code 的映射以区分左右修饰键。formatForDisplay 与 formatWithLabels 可按平台生成符号或文本标签,例如 formatForDisplay('Mod+S') 在 Mac 显示 ⌘S、Windows 显示 Ctrl+S。
使用方式:默认选项包括 enabled=true、preventDefault=true、stopPropagation=true、eventType='keydown'、requireReset=false、ignoreInputs 智能判断、target=document、conflictBehavior='warn'。可通过 HotkeysProvider 设置全局默认值,单个 Hook 选项可覆盖。作用域快捷键需传入 target: ref 并确保元素可聚焦(添加 tabIndex)。
开发工具:可安装 @tanstack/react-devtools 与 @tanstack/react-hotkeys-devtools,通过 TanStackDevtools 与 hotkeysDevtoolsPlugin 接入,生产构建默认排除,如需包含可使用 @tanstack/react-hotkeys-devtools/production 导入。
适用场景:快捷键设置界面、按住修饰键显示提示浮层、条件启用快捷键、多快捷键独立注册等。限制:资料未提供浏览器兼容范围、包体积、版本要求及收费信息。