# Hotkey - 跨平台全局热键库

跨平台 Go 语言全局热键库，支持 Windows、Linux (X11) 和 macOS 操作系统。

## ✨ 特性

- **跨平台支持**：Windows、Linux (X11)、macOS 统一 API
- **线程安全**：所有公共 API 使用互斥锁保护
- **标准化错误**：提供统一的错误类型，便于错误处理
- **资源管理**：支持手动和自动（finalizer）资源清理
- **独立实现**：除系统库外无第三方 Go 依赖
- **状态查询**：提供 `IsRegistered()` 和 `IsClosed()` 方法

## 📦 安装

```bash
go get -u voidraft/internal/common/hotkey
```

### 平台特定依赖

#### Linux

需要安装 X11 开发库：

```bash
# Debian/Ubuntu
sudo apt install -y libx11-dev

# CentOS/RHEL
sudo yum install -y libX11-devel

# Arch Linux
sudo pacman -S libx11
```

**无界面环境（云服务器等）**：

```bash
# 安装虚拟显示服务器
sudo apt install -y xvfb

# 启动虚拟显示
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0
```

#### macOS

**GUI 应用**（Wails、Fyne、Cocoa 等）：框架管理主事件循环，直接使用即可。

**CLI 应用**：需要使用 `darwin.Init()` 启动 NSApplication 主事件循环，参见下文"macOS CLI 应用示例"。

#### Windows

无额外依赖，开箱即用。

## 📖 使用指南

### 基本用法

```go
package main

import (
    "fmt"
    "voidraft/internal/common/hotkey"
)

func main() {
    // 创建热键：Ctrl+Shift+S
    hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
    
    // 注册热键
    if err := hk.Register(); err != nil {
        panic(err)
    }
    defer hk.Close() // 确保资源清理
    
    fmt.Println("热键已注册，按 Ctrl+Shift+S 触发...")
    
    // 监听热键事件
    for {
        select {
        case <-hk.Keydown():
            fmt.Println("热键按下！")
        case <-hk.Keyup():
            fmt.Println("热键释放！")
        }
    }
}
```

### 完整示例：带错误处理

```go
package main

import (
    "errors"
    "fmt"
    "log"
    "os"
    "os/signal"
    "syscall"
    "voidraft/internal/common/hotkey"
)

func main() {
    // 创建热键
    hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModAlt}, hotkey.KeyQ)
    
    // 注册热键，处理可能的错误
    if err := hk.Register(); err != nil {
        switch {
        case errors.Is(err, hotkey.ErrHotkeyConflict):
            log.Fatal("热键冲突：该组合键已被其他程序占用")
        case errors.Is(err, hotkey.ErrPlatformUnavailable):
            log.Fatal("平台不支持：", err)
        case errors.Is(err, hotkey.ErrAlreadyRegistered):
            log.Fatal("热键已经注册")
        default:
            log.Fatal("注册热键失败：", err)
        }
    }
    defer hk.Close()
    
    fmt.Println("热键 Ctrl+Alt+Q 已注册")
    fmt.Println("按下热键触发，或按 Ctrl+C 退出...")
    
    // 优雅退出
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
    
    // 事件循环
    for {
        select {
        case <-hk.Keydown():
            fmt.Println("[事件] 热键按下")
            // 执行你的业务逻辑
            
        case <-hk.Keyup():
            fmt.Println("[事件] 热键释放")
            
        case <-sigChan:
            fmt.Println("\n正在退出...")
            return
        }
    }
}
```

### 防抖处理（应用层）

如果热键按住会持续触发，建议在应用层添加防抖：

```go
package main

import (
    "fmt"
    "log"
    "time"
    "voidraft/internal/common/hotkey"
)

func main() {
    hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl}, hotkey.KeyD)
    if err := hk.Register(); err != nil {
        log.Fatal(err)
    }
    defer hk.Close()
    
    // 防抖参数
    var lastTrigger time.Time
    debounceInterval := 800 * time.Millisecond // 推荐 800ms
    
    for {
        select {
        case <-hk.Keydown():
            now := time.Now()
            // 检查距离上次触发的时间
            if !lastTrigger.IsZero() && now.Sub(lastTrigger) < debounceInterval {
                fmt.Println("触发被忽略（防抖）")
                continue
            }
            lastTrigger = now
            
            fmt.Println("热键触发！")
            // 执行你的业务逻辑
        }
    }
}
```

### 动态修改热键

```go
// 注销旧热键
if err := hk.Unregister(); err != nil {
    log.Printf("注销失败：%v", err)
}

// 修改热键组合
hk = hotkey.New([]hotkey.Modifier{hotkey.ModCtrl}, hotkey.KeyF1)

// 重新注册
if err := hk.Register(); err != nil {
    log.Printf("注册失败：%v", err)
}

// 重要：重新获取通道引用！
keydownChan := hk.Keydown()
keyupChan := hk.Keyup()
```

### 状态检查

```go
// 检查热键是否已注册
if hk.IsRegistered() {
    fmt.Println("热键已注册")
}

// 检查热键是否已关闭
if hk.IsClosed() {
    fmt.Println("热键已关闭，无法再使用")
}
```

### 资源管理最佳实践

```go
func registerHotkey() error {
    hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl}, hotkey.KeyH)
    
    // 使用 defer 确保资源释放
    defer hk.Close()
    
    if err := hk.Register(); err != nil {
        return err
    }
    
    // ... 使用热键 ...
    
    return nil
}

// Close() 是幂等的，多次调用是安全的
hk.Close()
hk.Close() // 不会 panic
```

## 🔑 支持的修饰键

### 所有平台通用

```go
hotkey.ModCtrl   // Ctrl 键
hotkey.ModShift  // Shift 键
hotkey.ModAlt    // Alt 键（Linux: 通常映射到 Mod1）
```

### Linux 额外支持

```go
hotkey.Mod1  // 通常是 Alt
hotkey.Mod2  // 通常是 Num Lock
hotkey.Mod3  // (较少使用)
hotkey.Mod4  // 通常是 Super/Windows 键
hotkey.Mod5  // (较少使用)
```

### 组合使用

```go
// Ctrl+Shift+Alt+S
hk := hotkey.New(
    []hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift, hotkey.ModAlt},
    hotkey.KeyS,
)
```

## ⌨️ 支持的按键

### 字母键

```go
hotkey.KeyA - hotkey.KeyZ  // A-Z
```

### 数字键

```go
hotkey.Key0 - hotkey.Key9  // 0-9
```

### 功能键

```go
hotkey.KeyF1 - hotkey.KeyF20  // F1-F20
```

### 特殊键

```go
hotkey.KeySpace    // 空格
hotkey.KeyReturn   // 回车
hotkey.KeyEscape   // ESC
hotkey.KeyDelete   // Delete
hotkey.KeyTab      // Tab
hotkey.KeyLeft     // 左箭头
hotkey.KeyRight    // 右箭头
hotkey.KeyUp       // 上箭头
hotkey.KeyDown     // 下箭头
```

### 自定义键码

如果需要的键未预定义，可以直接使用键码：

```go
// 使用自定义键码 0x15
hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl}, hotkey.Key(0x15))
```

## ⚠️ 错误类型

```go
// 检查特定错误类型
if errors.Is(err, hotkey.ErrAlreadyRegistered) {
    // 热键已经注册
}

if errors.Is(err, hotkey.ErrNotRegistered) {
    // 热键未注册
}

if errors.Is(err, hotkey.ErrClosed) {
    // 热键已关闭，无法再使用
}

if errors.Is(err, hotkey.ErrHotkeyConflict) {
    // 热键冲突，已被其他程序占用
}

if errors.Is(err, hotkey.ErrPlatformUnavailable) {
    // 平台不可用（如 Linux 无 X11）
}

if errors.Is(err, hotkey.ErrFailedToRegister) {
    // 注册失败（其他原因）
}

if errors.Is(err, hotkey.ErrFailedToUnregister) {
    // 注销失败
}
```

## 🎯 平台特定注意事项

### Linux

#### 1. AutoRepeat 行为

Linux 的 X11 会在按键持续按下时重复发送 `KeyPress` 事件。如果你的应用对此敏感，需要做防抖处理：

```go
var lastTrigger time.Time
debounceInterval := 500 * time.Millisecond

for {
    select {
    case <-hk.Keydown():
        now := time.Now()
        if now.Sub(lastTrigger) < debounceInterval {
            continue // 忽略重复触发
        }
        lastTrigger = now
        
        // 处理热键事件
        fmt.Println("热键触发！")
    }
}
```

#### 2. 键位映射差异

不同的 Linux 发行版和桌面环境可能有不同的键位映射。建议：

- 使用标准的 `ModCtrl`、`ModShift`、`ModAlt`
- 避免依赖 `Mod2`、`Mod3`、`Mod5`（映射不一致）
- `Mod4` 通常是 Super/Windows 键，但也可能不同

#### 3. Wayland 支持

当前版本仅支持 X11。在 Wayland 环境下：

- 需要运行在 XWayland 兼容层
- 或设置 `GDK_BACKEND=x11` 环境变量
- 原生 Wayland 支持正在开发中

#### 4. Display 连接复用

本库已优化 Linux 实现，在热键注册期间保持 X11 Display 连接：

```
注册时：    XOpenDisplay → XGrabKey → 保持连接
事件循环：  使用相同连接 → XNextEvent
注销时：    XUngrabKey → XCloseDisplay
```

这大幅降低了资源开销和延迟。

### Windows

#### 1. 热键按下事件

Windows 使用 `RegisterHotKey` API 注册系统级热键，通过 `WM_HOTKEY` 消息接收按键事件。

**实现细节**：
- 使用 `PeekMessageW` (Unicode) 轮询消息队列
- 10ms 轮询间隔，CPU 占用约 0.3-0.5%
- `isKeyDown` 状态标志防止重复触发
- 按下事件延迟通常 < 10ms

#### 2. 热键释放事件

Windows `RegisterHotKey` API 不提供键释放通知，本库使用 `GetAsyncKeyState` 轮询检测：

```go
// 检测键释放（每 10ms 检查一次）
if isKeyDown && GetAsyncKeyState(key) == 0 {
    keyupIn <- struct{}{}
    isKeyDown = false
}
```

**特性**：
- 释放检测延迟：通常 10-20ms
- 仅在按键按下后激活检测
- 依赖于 `GetAsyncKeyState` 的精度

#### 3. 持续按住行为

Windows 在持续按住热键时会重复发送 `WM_HOTKEY` 消息。本库通过 `isKeyDown` 标志防止同一次按住重复触发 Keydown 事件。

如果需要防止快速连续按键，建议在应用层添加防抖：

```go
var lastTrigger time.Time
debounceInterval := 100 * time.Millisecond

for {
    <-hk.Keydown()
    now := time.Now()
    if now.Sub(lastTrigger) < debounceInterval {
        continue  // 忽略
    }
    lastTrigger = now
    // 处理事件...
}
```

#### 4. 系统保留热键

某些热键被 Windows 系统保留，无法注册：

- `Win+L`：锁定屏幕
- `Ctrl+Alt+Del`：安全选项
- `Alt+Tab`：切换窗口
- `Alt+F4`：关闭窗口
- `Win+D`：显示桌面

尝试注册这些热键会返回 `ErrFailedToRegister`。

#### 5. 热键冲突

如果热键已被其他应用注册，`RegisterHotKey` 会失败。常见冲突来源：

- 游戏快捷键
- 输入法快捷键
- 快捷键管理工具（AutoHotkey 等）
- 其他全局热键应用

返回错误为 `ErrFailedToRegister`（Windows 不区分冲突和其他失败）。

#### 6. 线程模型

- 热键注册和消息循环运行在同一个 OS 线程上
- 使用 `runtime.LockOSThread()` 确保线程亲和性
- 不要求是主线程（与 macOS 不同）
- `ph.funcs` channel 用于在事件循环线程中执行注册/注销操作

---

### macOS

#### 1. 主事件循环要求

macOS 的 Carbon 事件 API 通过 GCD（Grand Central Dispatch）调度到主队列执行。

**GUI 应用（Wails、Cocoa 等）**：
- ✅ 框架已自动管理主事件循环
- ✅ 热键功能开箱即用，无需额外配置

**纯 CLI 应用**：
- ⚠️ 需要手动启动 macOS 运行循环
- 参见下文"macOS 纯 CLI 应用示例"

#### 2. 权限问题

macOS 可能需要辅助功能权限。如果热键无法注册，请检查：

```
系统偏好设置 → 安全性与隐私 → 隐私 → 辅助功能
```

将你的应用添加到允许列表。

#### 3. Carbon vs Cocoa

当前实现使用 Carbon API（稳定且兼容性好）。未来版本可能会迁移到更现代的 Cocoa API。

#### 4. macOS 纯 CLI 应用示例

如果你的应用**不是 GUI 应用**，需要启动主事件循环。

**最简单的方法：使用 darwin.Init()（推荐）**

```go
//go:build darwin

package main

import (
    "fmt"
    "voidraft/internal/common/hotkey"
    "voidraft/internal/common/hotkey/darwin"
)

func main() {
    // 使用 darwin.Init 启动主事件循环
    darwin.Init(run)
}

func run() {
    hk := hotkey.New([]hotkey.Modifier{hotkey.ModCmd, hotkey.ModShift}, hotkey.KeyA)
    if err := hk.Register(); err != nil {
        fmt.Printf("注册失败: %v\n", err)
        return
    }
    defer hk.Close()
    
    fmt.Println("热键已注册: Cmd+Shift+A")
    
    for {
        <-hk.Keydown()
        fmt.Println("热键触发！")
    }
}
```

**高级用法：使用 darwin.Call() 在主线程执行操作**

```go
darwin.Init(func() {
    hk := hotkey.New(...)
    hk.Register()
    
    for {
        <-hk.Keydown()
        // 在主线程执行 macOS API 调用
        darwin.Call(func() {
            // 例如调用 Cocoa/AppKit API
            fmt.Println("这段代码在主线程执行")
        })
    }
})
```

**注意**：
- GUI 应用无需调用 `darwin.Init()`，框架已处理
- `darwin.Call()` 用于需要主线程的特定 macOS API
- 热键注册本身已通过 `dispatch_get_main_queue()` 自动调度到主线程

## 🔬 架构设计

### 目录结构

```
internal/common/hotkey/
├── hotkey.go              # 统一的公共 API
├── hotkey_windows.go      # Windows 平台适配器
├── hotkey_darwin.go       # macOS 平台适配器
├── hotkey_linux.go        # Linux 平台适配器
├── hotkey_nocgo.go        # 非 CGO 平台占位符
├── windows/
│   ├── hotkey.go          # Windows 核心实现
│   └── mainthread.go      # Windows 线程管理
├── darwin/
│   ├── hotkey.go          # macOS 核心实现
│   ├── hotkey.m           # Objective-C/Carbon 代码
│   └── mainthread.go      # macOS 线程管理
└── linux/
    ├── hotkey.go          # Linux 核心实现
    ├── hotkey.c           # X11 C 代码
    └── mainthread.go      # Linux 线程管理
```

### 设计原则

1. **平台隔离**：每个平台的实现完全独立，通过构建标签分离
2. **统一接口**：所有平台提供相同的 Go API
3. **资源安全**：自动资源管理，防止泄漏
4. **并发安全**：所有公共方法都是线程安全的
5. **错误透明**：标准化错误类型，便于处理

### 事件流程

```
用户按键
    ↓
操作系统捕获
    ↓
平台特定 API（Win32/X11/Carbon）
    ↓
C/Objective-C 回调
    ↓
Go channel（类型转换）
    ↓
用户应用代码
```

### 并发模型

```
主 Goroutine              事件 Goroutine            转换 Goroutine
    │                          │                          │
Register() ────启动──────→ eventLoop()                    │
    │                          │                          │
    │                      等待 OS 事件                    │
    │                          │                          │
    │                          ├────发送────→ 类型转换      │
    │                          │              │            │
    │                          │              └─→ Keydown()/Keyup()
    │                          │                          │
Unregister() ──停止信号──→ 退出循环                       │
    │                          │                          │
    └──────等待清理─────────────┴──────────────────────────┘
```

## 📊 性能特性

### 资源占用

- **内存**：每个热键约 1-2 KB（包括 goroutines、channels、CGO handles）
- **Goroutines**：每个热键 3 个
  - 1 个事件循环 goroutine
  - 2 个通道转换 goroutine (interface{} → Event)
- **CPU**：
  - **Windows**：10ms 轮询，约 0.3-0.5% CPU（单核，空闲时）
  - **Linux**：事件驱动 (`XNextEvent` 阻塞)，几乎无 CPU 占用
  - **macOS**：事件驱动 (GCD 调度)，几乎无 CPU 占用
- **线程**：
  - 每个热键 1 个 OS 线程（通过 `runtime.LockOSThread()` 锁定）

### 延迟

**按下事件 (Keydown)**：
- Windows: < 10ms（取决于轮询间隔）
- Linux: < 10ms（X11 事件延迟）
- macOS: < 5ms（Carbon 事件延迟）

**释放事件 (Keyup)**：
- Windows: 10-20ms（`GetAsyncKeyState` 轮询检测）
- Linux: < 15ms（X11 KeyRelease 事件）
- macOS: < 10ms（Carbon 事件延迟）

### 使用建议

1. **资源管理**：
   - 使用 `defer hk.Close()` 确保资源释放
   - 不需要时及时调用 `Unregister()` 或 `Close()`
   - 避免频繁创建/销毁热键对象

2. **事件处理**：
   - 热键事件处理应快速返回，避免阻塞 channel
   - 复杂逻辑应在新 goroutine 中处理
   - 考虑应用层防抖（特别是 Linux AutoRepeat）

3. **错误处理**：
   - 始终检查 `Register()` 返回的错误
   - 使用 `errors.Is()` 判断错误类型
   - 处理热键冲突场景（提供备用方案或用户提示）

4. **平台差异**：
   - Windows Keyup 事件有轻微延迟（正常现象）
   - Linux 可能需要防抖处理 AutoRepeat
   - macOS CLI 应用需要启动主事件循环

## 🐛 故障排查

### Linux: "Failed to initialize the X11 display"

**问题**：无法连接到 X11 显示服务器

**解决方案**：
```bash
# 检查 DISPLAY 环境变量
echo $DISPLAY

# 如果为空，设置它
export DISPLAY=:0

# 或使用虚拟显示
Xvfb :99 -screen 0 1024x768x24 &
export DISPLAY=:99
```

### macOS: 热键不触发

**问题**：注册成功但热键无响应

**解决方案**：
1. 检查辅助功能权限（见上文）
2. 如果是纯 CLI 应用，确保启动了主运行循环（见上文示例）
3. 检查其他应用是否占用了该热键

### Windows: ErrFailedToRegister

**问题**：热键注册失败

**可能原因**：
1. 热键已被其他应用占用（AutoHotkey、游戏、输入法等）
2. 尝试注册系统保留热键（Win+L、Ctrl+Alt+Del 等）
3. 热键 ID 冲突（极少见）

**解决方案**：
1. 检查任务管理器，关闭可能冲突的应用
2. 使用不同的热键组合
3. 在应用中提供热键自定义功能，让用户选择可用组合
4. 提供友好的错误提示，说明热键被占用

**调试方法**：
```go
if err := hk.Register(); err != nil {
    if errors.Is(err, hotkey.ErrFailedToRegister) {
        log.Printf("热键注册失败: %v", err)
        log.Printf("提示：该热键可能已被其他应用使用")
        // 尝试备用热键...
    }
}
```

### Windows: Keyup 事件延迟

**问题**：释放事件比预期晚 10-20ms

**原因**：Windows API 限制，`RegisterHotKey` 不提供释放通知，需要轮询检测。

**这是正常行为**：
- 10ms 轮询间隔导致的固有延迟
- 对大多数应用场景影响很小
- 如果需要精确的释放时机，考虑使用底层键盘钩子（复杂度更高）

### 所有平台: Keyup 事件丢失

**问题**：只收到 Keydown，没有 Keyup

**可能原因**：
1. 在接收 Keyup 前调用了 `Unregister()`
2. 通道缓冲区满（不太可能，使用了无缓冲通道）
3. Windows 上正常（有轻微延迟）

**解决方案**：
```go
// 确保在处理完事件后再注销
for {
    select {
    case <-hk.Keydown():
        // 处理...
    case <-hk.Keyup():
        // 处理...
        // 现在可以安全注销
        hk.Unregister()
        return
    }
}
```

## 🤝 贡献

欢迎贡献！请遵循以下原则：

1. **保持简洁**：不要过度优化
2. **平台一致**：确保 API 在所有平台表现一致
3. **测试充分**：在所有支持的平台测试
4. **文档完善**：更新相关文档

## 📄 许可证

本项目是 Voidraft 的一部分，遵循项目主许可证。

## 🙏 致谢

本库的设计和实现参考了多个开源项目的经验：

- `golang.design/x/hotkey` - 基础架构设计
- `github.com/robotn/gohook` - 跨平台事件处理思路

特别感谢所有为跨平台 Go 开发做出贡献的开发者们！

---

**如有问题或建议，欢迎提交 Issue！** 🚀