Back to Details

tanstack-hotkeys

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TanStack Hotkeys

TanStack Hotkeys

Overview

概述

TanStack Hotkeys is a type-safe keyboard shortcuts library for React with template-string bindings, cross-platform 
Mod
key abstraction (Cmd on macOS, Ctrl on Windows/Linux), and SSR-friendly utilities. It provides hooks for single hotkeys, multi-key sequences, shortcut recording, and real-time key state tracking, plus platform-aware display formatting.
When to use: Adding keyboard shortcuts to React apps, recording user-defined hotkeys, detecting held modifier keys, displaying platform-specific shortcut labels, implementing Vim-style key sequences.
When NOT to use: Non-React apps without a wrapper (core package exists but React is the primary target), complex input handling that needs full keymap management (consider a dedicated keymap library).
TanStack Hotkeys 是一款面向React的类型安全键盘快捷键库，支持模板字符串绑定、跨平台
Mod
键抽象（macOS上为Cmd，Windows/Linux上为Ctrl），以及兼容SSR的工具集。它提供了用于单热键、多键序列、快捷键录制和实时按键状态追踪的Hooks，还支持适配平台的显示格式化功能。
适用场景： 为React应用添加键盘快捷键、录制用户自定义热键、检测修饰键按住状态、显示适配平台的快捷键标签、实现类Vim风格的按键序列。
不适用场景： 无包装层的非React应用（核心包存在，但React是主要目标场景）、需要完整按键映射管理的复杂输入处理（建议使用专用的按键映射库）。

Quick Reference

快速参考

PatternAPIKey Points
Single hotkey
useHotkey
Mod
abstracts Cmd/Ctrl; auto-prevents default on combos
Multi-key sequence
useHotkeySequence
Vim-style sequences like 
g g
; configurable timeout
Record shortcuts
useHotkeyRecorder
User-defined shortcuts; start/stop/cancel recording
Detect key held
useKeyHold
Boolean for specific key; optimized re-renders
Track all held keys
useHeldKeys
Array of currently pressed key names
Track held key codes
useHeldKeyCodes
Map of key names to physical 
event.code
values
Global defaults
HotkeysProvider
Set default options for all hooks; per-hook overrides apply
Format for display
formatForDisplay
Platform-aware: macOS symbols vs Windows/Linux text
Scope to element
target
option + ref		Requires 
tabIndex
on target element for focus
Conditional hotkeys
enabled
option		Dynamically enable/disable without unmounting
模式API关键点
单热键
useHotkey
Mod
抽象Cmd/Ctrl；组合键自动阻止默认行为
多键序列
useHotkeySequence
类Vim风格序列如
g g
；支持配置超时时间
录制快捷键
useHotkeyRecorder
用户自定义快捷键；支持开始/停止/取消录制
检测按键按住
useKeyHold
返回指定按键的布尔值；优化重渲染逻辑
追踪所有按住按键
useHeldKeys
当前按下的按键名称数组
追踪按住按键编码
useHeldKeyCodes
按键名称到物理
event.code
值的映射表
全局默认配置
HotkeysProvider
为所有Hooks设置默认选项；支持单个Hook覆盖默认配置
格式化显示
formatForDisplay
适配平台：macOS使用符号，Windows/Linux使用文本
作用于指定元素
target
选项 + ref		目标元素需要设置
tabIndex
以获取焦点
条件式热键
enabled
选项		无需卸载即可动态启用/禁用热键

Common Mistakes

常见误区

MistakeCorrect Pattern
Missing 
tabIndex
on scoped target element		Add 
tabIndex={-1}
(or 
0
) to elements using 
target
ref for focus
Using 
Ctrl
instead of 
Mod
Use 
Mod
for cross-platform; it maps to Cmd (Mac) or Ctrl (Win/Linux)
Assuming hotkeys fire inside inputs
ignoreInputs
defaults to smart detection; set 
false
to force firing
Duplicate hotkey registrations without configSet 
conflictBehavior: 'replace'
to override, or 
'error'
to catch
Forgetting 
preventDefault
is auto-enabled		Modifier combos auto-prevent; set 
preventDefault: false
to allow default
Using 
keyup
without 
requireReset
Combine 
eventType: 'keyup'
with 
requireReset: true
to fire once
误区正确做法
作用域目标元素缺少
tabIndex
为使用
target
ref的元素添加
tabIndex={-1}
（或
0
）以使其可获取焦点
使用
Ctrl
而非
Mod
使用
Mod
实现跨平台兼容；它会自动映射为Mac上的Cmd或Win/Linux上的Ctrl
假设热键在输入框内会触发
ignoreInputs
默认启用智能检测；设置为
false
可强制触发热键
重复注册热键未配置冲突处理设置
conflictBehavior: 'replace'
覆盖原有配置，或设为
'error'
捕获冲突
忘记组合键自动启用
preventDefault
修饰键组合会自动阻止默认行为；设置
preventDefault: false
可允许默认行为
使用
keyup
事件未搭配
requireReset
需将
eventType: 'keyup'
与
requireReset: true
结合使用以确保只触发一次

Delegation

职责分工

If the 
tanstack-pacer
skill is available, delegate throttling and debouncing tasks to it. TanStack Pacer is useful for rate-limiting hotkey callbacks. Otherwise, recommend: 
pnpm dlx skills add oakoss/agent-skills -s tanstack-pacer -a claude-code -y
If the 
tanstack-devtools
skill is available, delegate devtools setup to it. Otherwise, recommend: 
pnpm dlx skills add oakoss/agent-skills -s tanstack-devtools -a claude-code -y
  • Keyboard shortcuts and hotkeys: Use this skill
  • Throttling/debouncing hotkey callbacks: Delegate to 
    tanstack-pacer
  • DevTools integration: Delegate to 
    tanstack-devtools
如果
tanstack-pacer
技能可用，将节流和防抖任务委托给它。TanStack Pacer可用于对热键回调进行速率限制。 否则，建议执行：
pnpm dlx skills add oakoss/agent-skills -s tanstack-pacer -a claude-code -y
如果
tanstack-devtools
技能可用，将开发者工具设置任务委托给它。 否则，建议执行：
pnpm dlx skills add oakoss/agent-skills -s tanstack-devtools -a claude-code -y
  • 键盘快捷键与热键： 使用本技能
  • 热键回调的节流/防抖： 委托给
    tanstack-pacer
  • 开发者工具集成： 委托给
    tanstack-devtools

References

参考资料

  • React hooks and configuration
  • Sequences and recording
  • Formatting and display
  • React Hooks与配置
  • 序列与录制
  • 格式化与显示