react-hotkeys 是 TanStack Hotkeys 为 React 提供的快捷键集成方案，用于在 React 应用中添加或修复键盘快捷键。
用途 它面向需要在组件挂载期间注册键盘快捷键的场景，支持单个和弦、按键序列以及应用级热键，并可通过 Provider 统一管理默认配置和生效范围。
主要能力 API 包括：useHotkey(hotkey, callback, options?) 在组件挂载期间注册单个快捷键；useHotkeys(definitions, commonOptions?) 一次注册多个快捷键或由数据生成的列表；<HotkeysProvider> 为内部组件设置默认选项、作用域（对话框可用 exclusive 独占键盘）、启用状态和应用热键；useHotkeysContext() 读取最近的 Provider 合并后的默认值与启用状态；useDefaultHotkeysOptions() 读取所有上层 Provider 合并的默认选项；useAppHotkeys()、useAppHotkeyList() 获取应用热键及列表状态；useCustomHotkeys() 读取、修改和重置用户自定义热键并检查冲突；useHotkeyRecorder(options) 录制用户按下的和弦或序列；useHotkeyRegistrations() 列出已注册热键及其选项、元信息和状态；useHotkeyScopesState() 获取活动作用域与独占作用域；useHotkeyHint、useKeyHold、useHeldKeys、useHeldKeyCodes 分别用于提示显示、单键按住状态、当前按住的所有键以及按键到物理 code 的映射。包还重新导出 formatForDisplay、matchesKeyboardEvent、defineAppHotkeys 等核心工具。
使用方式 示例中通过 useHotkey('Mod+S', () => onSave(), { meta: { name: 'Save' } }) 注册保存快捷键，并用 formatForDisplay 显示按键标签。Provider 非必需；在 React Server Components 框架中，需在客户端组件内使用这些 Hook 和 HotkeysProvider。开始前需加载 @tanstack/hotkeys#hotkeys-core 技能（npx @tanstack/intent@latest load @tanstack/hotkeys#hotkeys-core）。使用作用域时，应在 Provider 内部组件中注册快捷键，例如对话框的 Escape 需在 DialogBody 中注册，否则会落入被独占作用域挂起的外层作用域。
注意事项 传入 ref 而非 ref.current，因为首次渲染时 ref.current 为 null 会退化为 document 级热键；Hook 每次渲染读取最新参数，无需依赖数组或 useCallback；应直接调用 Hook，避免用字符串包装导致类型检查失效并丢失序列、选项等能力；matchesKeyboardEvent 需传入 DOM 事件（如 event.nativeEvent）；测试中可通过 <HotkeysProvider defaultOptions={{ hotkey: { platform: 'mac' } }}> 设置平台。声明应用热键、构建速查表或允许用户重绑快捷键时，需加载 @tanstack/hotkeys#app-hotkeys。签名可查看 node_modules/@tanstack/react-hotkeys/dist/*.d.ts，指南位于 https://tanstack.com/hotkeys/latest/docs/framework/react/guides/<page>.md，Devtools 可通过 @tanstack/react-hotkeys-devtools 的 hotkeysDevtoolsPlugin() 接入。