# useHotkeys

## 使用方法

注册全局快捷键。每个 hook 实例只在 window 上挂一个 `keydown` 监听。快捷键列表从一个 ref 或 getter 读，列表变化不会重新订阅。焦点在输入控件里（`input`、`textarea`、`select`、`contenteditable`）时默认不触发，除非这一条写了 `allowInInputs`；已经 `defaultPrevented` 的事件跳过，输入法组合中用到的键也跳过；命中时调用 `preventDefault()`。SSR 安全：监听只在挂载时装上。

```ts
import { useHotkeys } from '@astryx-vue/core'
```

监听在组件卸载时摘掉，列表变化时不会重挂。

## 建议

| 指引 | 实践 |
| --- | --- |
| 推荐 | 用于应用级快捷键：命令面板（`mod+k`）、帮助浮层（`shift+/`）、导航键。 |
| 推荐 | 用 `Kbd` 组件把同一条组合显示出来；两边对 `mod` 的平台判断是同一套。 |
| 推荐 | 弹窗或向导占用键盘时，用 `isDisabled` 暂时停掉快捷键，而不是把 hook 卸掉。 |
| 避免 | 用它做控件内部的焦点导航；那种场景用 `useListFocus` 或 `useGridRovingFocus`。 |

## 参数

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `hotkeys` | `MaybeRefOrGetter<readonly Hotkey[]>` | — | 快捷键登记表。普通数组、ref、getter 都行，每次按键时重新读。必填。 |
| `hotkeys[].keys` | `string` | — | 用 `"+"` 串起来的组合，例如 `"mod+k"`、`"shift+/"`、`"escape"`。`mod` 在 macOS 上是 ⌘，其他平台是 Ctrl。别名有 `esc`、`space`、`up`、`down`、`left`、`right`、`return`，字面量 `+` 写成 `plus`。组合里不写 `shift` 时忽略 shift 状态，所以单个字母不区分大小写。 |
| `hotkeys[].onPress` | `(event: KeyboardEvent) => void` | — | 命中组合时调用，调用前已经 `preventDefault()`。 |
| `hotkeys[].allowInInputs` | `boolean` | `false` | 焦点在输入框、文本域、下拉框或可编辑区域里时也触发这条快捷键。 |
| `hotkeys[].isDisabled` | `boolean` | `false` | 暂时停用这一条，不需要摘掉监听。 |

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| — | `void` | 没有返回值。组件卸载时 window 上的监听会被摘掉。 |