# gkeyboard

**Repository Path**: shaoninghouse/gkeyboard

## Basic Information

- **Project Name**: gkeyboard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gkeyboard

跨平台原生键盘控制 Go 库。支持 macOS、Windows、Linux，使用各平台原生 API 实现键盘事件模拟。

## 特性

- **零外部依赖**: 只依赖 Go 标准库和平台系统框架
- **跨平台**: 支持 macOS、Windows、Linux
- **原生实现**: 使用各平台原生 API（CoreGraphics/SendInput/XTest）
- **完整修饰键支持**: Shift, Control, Alt/Option, Command/Meta
- **简单易用**: 统一的 Go API，平台间代码兼容

## 安装

```bash
go get gitee.com/shaoninghouse/gkeyboard
```

## 系统要求

- **macOS**: 10.14+
- **Windows**: Windows 7+
- **Linux**: X11 with XTest extension
- Go 1.18+

## 快速开始

```go
package main

import (
    "time"
    "gitee.com/shaoninghouse/gkeyboard"
)

func main() {
    kb := gkeyboard.New()

    // 按下单个键
    kb.Press(gkeyboard.KeyA)

    // 按组合键 (Ctrl+C 复制 / Cmd+V 粘贴 / Super+V)
    kb.PressWithModifiers(gkeyboard.KeyC, gkeyboard.ModifierControl)

    // 输入字符串
    kb.Type("Hello, World!")

    time.Sleep(100 * time.Millisecond)
}
```

## 跨平台快捷键

修饰键在不同平台有不同名称：

| 平台 | Command/Meta 键 | Option/Alt 键 |
|------|-----------------|---------------|
| macOS | Command (⌘) | Option (⌥) |
| Windows | Win | Alt |
| Linux | Super/Win | Alt |

```go
// 使用通用修饰键名称
gkeyboard.ModifierCommand  // Cmd/Win/Super
gkeyboard.ModifierOption    // Option/Alt
gkeyboard.ModifierAlt       // Option/Alt 的别名
gkeyboard.ModifierMeta      // Command 的别名
```

## API 文档

### 按键

```go
// 字母键
gkeyboard.KeyA ~ KeyZ

// 数字键
gkeyboard.Key0 ~ Key9

// 功能键
gkeyboard.KeyF1 ~ KeyF12

// 控制键
gkeyboard.KeyReturn, KeyEnter   // 回车
gkeyboard.KeyTab               // Tab
gkeyboard.KeySpace             // 空格
gkeyboard.KeyEscape            // Esc
gkeyboard.KeyBackspace         // 退格
gkeyboard.KeyDelete            // 删除
gkeyboard.KeyForwardDelete     // Forward Delete (macOS)

// 方向键
gkeyboard.KeyUpArrow
gkeyboard.KeyDownArrow
gkeyboard.KeyLeftArrow
gkeyboard.KeyRightArrow

// 导航键
gkeyboard.KeyHome, KeyEnd
gkeyboard.KeyPageUp, KeyPageDown
```

### 修饰键

```go
gkeyboard.ModifierNone     // 无修饰键
gkeyboard.ModifierShift    // Shift
gkeyboard.ModifierControl  // Control (Ctrl)
gkeyboard.ModifierOption   // Option / Alt
gkeyboard.ModifierAlt      // Option / Alt 的别名
gkeyboard.ModifierCommand  // Command (macOS) / Win (Windows) / Super (Linux)
gkeyboard.ModifierMeta     // Command 的别名
gkeyboard.ModifierSuper    // Command 的别名
```

### 方法

```go
kb := gkeyboard.New()

kb.Press(KeyA)                    // 按下并释放单个键
kb.PressWithModifiers(KeyS, ModifierCommand)  // 按组合键
kb.Type("text")                   // 输入文本

kb.KeyDown(KeyShift)              // 按下并保持
kb.KeyUp(KeyShift)                // 释放

kb.Sleep(100)                     // 等待 100ms
gkeyboard.Wait()                  // 让出 CPU 时间片
```

### 包级别函数

```go
gkeyboard.PressKey(KeyEnter)
gkeyboard.PressKeyWithModifiers(KeyS, ModifierCommand)
gkeyboard.TypeString("Hello!")
gkeyboard.Platform()  // 返回 "darwin", "windows" 或 "linux"
```

### 预定义快捷键

```go
gkeyboard.Copy       // Ctrl+C / Cmd+C / Super+C
gkeyboard.Cut        // Ctrl+X
gkeyboard.Paste      // Ctrl+V
gkeyboard.Undo       // Ctrl+Z
gkeyboard.Redo       // Ctrl+Shift+Z
gkeyboard.SelectAll  // Ctrl+A
gkeyboard.Save       // Ctrl+S
gkeyboard.Find       // Ctrl+F
gkeyboard.NewTab     // Ctrl+T
gkeyboard.CloseTab   // Ctrl+W
gkeyboard.Refresh    // Ctrl+R
```

### 创建自定义快捷键

```go
// 方式1: 使用 NewShortcut
shortcut := gkeyboard.NewShortcut(
    gkeyboard.KeyP,
    gkeyboard.ModifierCommand,
    gkeyboard.ModifierShift,
)
shortcut.Press()

// 方式2: 直接调用
gkeyboard.PressKeyWithModifiers(
    gkeyboard.KeyP,
    gkeyboard.ModifierCommand|gkeyboard.ModifierShift,
)
```

## 示例

### 自动化文本输入

```go
kb := gkeyboard.New()

kb.Type("Hello, World!")
kb.Press(gkeyboard.KeyReturn)
```

### 自动化快捷操作

```go
kb := gkeyboard.New()

gkeyboard.SelectAll.Press()  // 全选
gkeyboard.Copy.Press()       // 复制
gkeyboard.Paste.Press()      // 粘贴
```

### 跨平台兼容代码

```go
import "gitee.com/shaoninghouse/gkeyboard"

func main() {
    platform := gkeyboard.Platform()
    
    // 根据平台选择不同的快捷键
    switch platform {
    case "darwin":
        gkeyboard.PressKeyWithModifiers(gkeyboard.KeyC, gkeyboard.ModifierCommand)
    case "windows":
        gkeyboard.PressKeyWithModifiers(gkeyboard.KeyC, gkeyboard.ModifierControl)
    case "linux":
        gkeyboard.PressKeyWithModifiers(gkeyboard.KeyC, gkeyboard.ModifierControl)
    }
}
```

## 平台特定说明

### macOS

- 使用 CoreGraphics CGEvent API
- 需要授予"辅助功能"权限
- 路径: 系统偏好设置 → 隐私与安全性 → 辅助功能

### Windows

- 使用 user32.dll 的 SendInput API
- 需要管理员权限（某些情况）

### Linux

- 需要 X11 和 XTest 扩展
- 不支持 Wayland 会话
- 安装依赖: `sudo apt install libx11-dev libxtst-dev` (Debian/Ubuntu)

## License

MIT