---
title: "Global Shortcut"
description: "注册与注销系统级快捷键。"
---


> 注册与注销系统级快捷键。

## 模块边界

`globalShortcut` 只声明前端调用和协议边界；全局按键注册依赖原生窗口消息循环，宿主要是
没有实现 `RegisterGlobalShortcut` / `UnregisterGlobalShortcut`，命令不会生效。

| 方法 | 协议命令 | Windows | Android |
| --- | --- | --- | --- |
| `KSM.globalShortcut.register({ shortcut })` | `globalShortcut.register` | 支持 | 不支持 |
| `KSM.globalShortcut.unregister({ shortcut })` | `globalShortcut.unregister` | 支持 | 不支持 |

Android 调用这些命令返回 `NOT_SUPPORTED`。

## 参数与返回值

`shortcut` 是宿主约定的快捷键描述字符串，例如 `"Ctrl+Shift+K"`。格式由宿主决定，
前端只做非空校验。

`register` 返回 `{ registered: boolean }`，`unregister` 返回
`{ unregistered: boolean }`。

## 示例

```ts
import { KSM } from 'kasumi-bridge';

const { registered } = await KSM.globalShortcut.register({
  shortcut: 'Ctrl+Shift+K'
});
if (!registered) {
  console.warn('The shortcut could not be registered.');
}
```

## 当前实现状态

- Windows 宿主已挂载命令，但默认实现返回 `false`，不会真正占用系统热键。
- 需要生产使用时，应在宿主服务层实现 `RegisterGlobalShortcut`，并在窗口销毁时注销。

## 错误与边界

- `shortcut` 为空字符串：`INVALID_ARGS`。
- Android：`NOT_SUPPORTED`。
- 注册失败应返回 `{ registered: false }`，不能抛 `IO_ERROR` 伪装成功。

## 排查

| 现象 | 优先检查 |
| --- | --- |
| 返回 `false` | 快捷键格式、注册热键冲突、宿主是否实现 |
| Android 返回 `NOT_SUPPORTED` | 这是预期行为，不是故障 |