useKeyPress

用于检测特定按键的按下状态的 hook，支持单个按键或按键组合，提供按键状态监听、事件回调等功能。

基础用法

最简单的用法是监听单个按键的按下状态。

🎯Enter 键状态: 释放

请按下 Enter 键试试

显示代码

监听多个按键

可以同时监听多个按键，任意一个按键按下时都会触发。

🎮方向键状态: 释放

请按下 ↑ ↓ ← → 方向键试试

显示代码

带回调的用法

可以在按键按下或释放时执行回调函数。

⌨️空格键状态: 释放

按下次数:

0

请按下 Space 键试试

显示代码

动态控制

可以动态启用或禁用按键监听。

📋Tab 键状态: 释放

🔧监听状态: 启用

请按下 Tab 键试试

显示代码

自定义过滤器

可以使用自定义函数来过滤按键事件。

🔢数字键状态: 释放

最后按下的数字:

无

请按下数字键 0-9 试试

显示代码

事件类型控制

可以指定只监听 keydown 或 keyup 事件。

⬇️只监听按下: CTRL释放

⬆️只监听释放: 等待CTRL按下

请按下 Ctrl 键试试

显示代码

API 参考

参数

参数	类型	默认值	说明
keyFilter	KeyFilter	-	按键过滤器，可以是字符串、字符串数组或自定义函数
options	UseKeyPressOptions	{}	配置选项

KeyFilter

type KeyFilter = KeyType | KeyType[] | ((event: KeyboardEvent) => boolean);

UseKeyPressOptions

属性	类型	默认值	说明
eventType	'keydown' | 'keyup' | 'both'	'both'	监听的事件类型
target	Target	window	监听的目标元素
enabled	MaybeRefOrGetter<boolean>	true	是否启用监听
preventDefault	boolean	false	是否阻止默认行为
stopPropagation	boolean	false	是否阻止事件冒泡
exactMatch	boolean	false	是否精确匹配（区分大小写）
onKeyDown	(event: KeyboardEvent) => void	-	按键按下时的回调
onKeyUp	(event: KeyboardEvent) => void	-	按键释放时的回调

返回值

type UseKeyPressReturn = [
  Ref<boolean>, // isPressed - 按键是否被按下
  () => void, // enable - 启用监听
  () => void, // disable - 禁用监听
];

类型定义

type KeyType = string;

interface UseKeyPressOptions {
  eventType?: "keydown" | "keyup" | "both";
  target?: Target;
  enabled?: MaybeRefOrGetter<boolean>;
  preventDefault?: boolean;
  stopPropagation?: boolean;
  exactMatch?: boolean;
  onKeyDown?: (event: KeyboardEvent) => void;
  onKeyUp?: (event: KeyboardEvent) => void;
}

type UseKeyPressReturn = [Ref<boolean>, () => void, () => void];

function useKeyPress(keyFilter: KeyFilter, options?: UseKeyPressOptions): UseKeyPressReturn;

注意事项

• 组件卸载时会自动清理事件监听器
• 支持响应式的 enabled 控制
• 按键名称不区分大小写（除非设置 exactMatch: true）
• 某些浏览器快捷键可能无法被拦截
• 在输入框中可能会触发事件冒泡
• 移动设备的虚拟键盘行为可能不一致