用途 app-hotkeys 用于为使用 TanStack Hotkeys 构建的应用提供统一的快捷键目录。它解决的场景包括：应用需要快捷键速查表或帮助对话框、命令面板中的命令可能带快捷键，以及需要让用户自定义按键时集中管理快捷键声明。官方资料建议用它替代单独的快捷键配置、上下文或手写速查表。
主要能力 在一个模块中通过 defineAppHotkeys 声明每一条快捷键，例如 doc.save、comment.post、theme.toggle 等条目，每条可包含 hotkey、meta.name 与 scope。根 provider 持有用户的自定义快捷键；组件将声明的 app hotkeys 与各自回调注册。若只需要反映当前已挂载内容的列表，使用带 meta 的普通 hotkeys 即可。资料示例中展示了 Mod+S 在 document 与 comments 两个作用域下的声明，以及 hotkey 为 null 的 theme.toggle。
使用方式 从 @tanstack/hotkeys 导入 defineAppHotkeys 并导出快捷键目录。在适配器模块中增强 Register 类型，例如 declare module '@tanstack/react-hotkeys' 里设置 appHotkeys 类型，以获得 id 类型提示。Lit、Alpine、Ember 没有 provider，需在启动时调用一次 provideAppHotkeys(appHotkeys, options)。注册时应传 appHotkeys['doc.save'] 而非其 .hotkey 值，否则用户改键不生效且列表中显示为 inactive。provider 只读取一次 customHotkeys；若自定义快捷键异步加载，应在数据到达后再渲染 provider 或按用户加 key。后续修改应通过适配器的 custom hotkeys API，而不是更新 prop。
注意事项与限制 保存 onCustomHotkeysChange 收到的内容，它只含用户改动过的快捷键，这样用户仍能获得新的默认值；保存全部生效快捷键会把当前默认值冻结进用户数据。id 是存储契约，保存数据按 id 键控，未知 id 会被丢弃并告警，因此重命名 id 会丢弃用户定制。setCustomHotkey 返回冲突且在有冲突时不作任何更改，应在报告成功前检查结果，或在录制器的 validate 中调用 findConflicts 提前拒绝。共享按键的 app hotkeys 应声明 scope，无 scope 或属于 global 的条目会与同键的其他条目冲突，导致改键被拒。冲突检查将物理与逻辑绑定视为不同，录制的 Mod+[KeyP] 与声明的 Mod+P 不冲突，但 Command+P 会同时触发两者；在录制器表单中以 Mod+[KeyP] 这类形式声明可重绑默认值可使二者可比。速查表对话框通常使用独占作用域，并应在对话框内也注册打开它的快捷键，使同一组按键可关闭。构建“按下新快捷键”控件时需参阅 recording 相关文档。