useKeyPress

概览

useKeyPress 订阅键盘事件，支持现代 key 名称、旧式数字键码、候选数组、谓词，以及 ctrl+s 或 ctrl.s 形式的字符串组合键。

函数签名

function useKeyPress(
  keyFilter: KeyFilter,
  handler: KeyPressHandler,
  options?: UseKeyPressOptions,
): void;

参数

默认监听 keydown。可通过 events 监听 keyup 或 keypress，通过 target/ref 限定 EventTarget，通过 exactMatch 严格匹配修饰键，并用 enabled 暂停。onError 可观察谓词或处理函数错误。

返回值

无返回值。原生订阅会跟随 target、事件和 enabled 选项，并在清理时移除。

行为

键过滤器可以是字符串、数字、候选数组或谓词。数组始终表示彼此独立的候选项；组合键应写成 'ctrl+s' 或 'ctrl.s'，不能写成 ['ctrl', 's']。启用 exactMatch 后，事件包含未声明的修饰键时不会匹配。处理函数会收到事件和实际匹配到的字符串或数字过滤值；谓词也可以显式返回这个值。匹配回调的错误会先通过 onError 报告，然后继续抛出，不会被吞掉。

SSR / RSC

当 window 或配置的 target 不可用时不会添加监听器。请在 Client Component 中使用此 Hook。

示例

组合使用

键盘触发 mutation 时可以配合 useLockFn，模态框和命令面板快捷键可以配合 useBoolean。

源码

在 GitHub 查看实现。