第05章 - 键盘控制与文本输入

键盘自动化与鼠标同样重要：填写表单、触发快捷键、输入文本、控制媒体音量等都离不开它。RobotGo 的键盘 API 既能输入任意 Unicode 文本，也能精确模拟单键、组合键以及按键的按下/松开状态。本章将完整讲解键盘相关函数、按键名称表以及实战要点。

5.1 输入文本：Type

Type 是最常用的文本输入函数，它会把字符串逐字“打”出来，支持英文、数字、符号以及中日韩等 Unicode 字符：

robotgo.Type("Hello World")
robotgo.Type("你好，世界")
robotgo.Type("こんにちは世界")
robotgo.Type("だんしゃり")

Type 还支持额外参数。例如官方示例中的：

robotgo.Type("だんしゃり", 0, 1)

后续参数可用于指定目标进程 PID 等高级用法（向特定窗口发送输入），这部分会在第 10 章“进程与窗口管理”中结合 FindIds 一起讲解。

性能提示：Type 是逐字符输入，对于很长的文本会比较慢。如果要输入大段文本，更高效的做法是先用 WriteAll 写入剪贴板，再用 KeyTap("v", "ctrl") 粘贴（详见第 9 章）。

5.2 Unicode 输入

对于需要按 Unicode 码点输入的特殊场景，RobotGo 提供了 UnicodeType 与 CharCodeAt：

// 取字符串 "Test" 中索引 0 处字符的 Unicode 码点
ustr := uint32(robotgo.CharCodeAt("Test", 0))
robotgo.UnicodeType(ustr)

CharCodeAt(str, index) 返回指定位置字符的码点，UnicodeType 则按码点直接输入字符。这在处理某些输入法环境下普通 Type 失效的字符时很有用。

5.3 敲击按键：KeyTap

KeyTap 用于“按下并立即松开”一个按键，是触发快捷键的主力函数。它的第一个参数是主键，后面可跟随任意数量的修饰键：

// 单个按键
robotgo.KeyTap("enter")
robotgo.KeyTap("a")

// 组合键：主键 + 修饰键
robotgo.KeyTap("a", "ctrl")          // Ctrl + A
robotgo.KeyTap("i", "alt", "cmd")    // Alt + Cmd + I

// 修饰键也可以用字符串切片传入
arr := []string{"alt", "cmd"}
robotgo.KeyTap("i", arr)

修饰键的传入方式很灵活：既可以作为多个独立参数，也可以打包成一个 []string。两种写法等价。

5.4 切换按键状态：KeyToggle

当你需要“按住某键不放”或精确控制按下/松开时机时，使用 KeyToggle：

robotgo.KeyToggle("a")        // 按下 a 键
robotgo.KeyToggle("a", "up")  // 松开 a 键

省略第二个参数（或传 "down"）表示按下，"up" 表示松开。这对于游戏中“持续按住某方向键移动”之类的场景非常有用。

5.5 控制键盘节奏：KeySleep

与鼠标的 MouseSleep 对应，键盘有 KeySleep 全局变量，用于在每次键盘操作后自动等待指定毫秒数：

robotgo.KeySleep = 100 // 每次按键操作后等待 100 毫秒
robotgo.KeyTap("enter")
robotgo.KeyTap("i", "alt", "cmd")

合理设置 KeySleep 可以避免目标程序“跟不上”输入速度而丢键。

5.6 按键名称完整参考

RobotGo 支持非常丰富的按键名称。下面按类别整理（来自官方 keys 文档）。

5.6.1 基础字符键

A-Z a-z 0-9

字母和数字直接用对应字符表示。

5.6.2 控制与编辑键

backspace  delete  enter  tab  esc / escape
up  down  left  right          （方向键）
home  end  pageup  pagedown
insert  space  print  printscreen（macOS 不支持 printscreen）
menu（仅 Windows）

5.6.3 功能键

f1 f2 f3 ... f24

支持 F1 到 F24 共 24 个功能键。

5.6.4 修饰键

cmd      在 Windows 上即 "win" 键
cmdl     左 command       cmdr  右 command
alt      altl 左 alt       altr  右 alt
ctrl     ctrll 左 ctrl      ctrlr 右 ctrl
control
shift    shiftl 左 shift    shiftr 右 shift
capslock

注意 cmd 在 Windows 上对应 Win 键，在 macOS 上对应 Command 键。

5.6.5 多媒体音量键

audio_mute       静音
audio_vol_down   降低音量
audio_vol_up     提高音量
audio_play
audio_stop
audio_pause
audio_prev       上一曲
audio_next       下一曲
audio_rewind     （仅 Linux）
audio_forward    （仅 Linux）
audio_repeat     （仅 Linux）
audio_random     （仅 Linux）

5.6.6 小键盘（Numpad）

num0 num1 ... num9   num_lock
num.  num+  num-  num*  num/
num_clear  num_enter  num_equal

5.6.7 其他特殊键

scroll_lock  pause_break

lights_mon_up     调高显示器亮度    （Windows 不支持）
lights_mon_down   调低显示器亮度    （Windows 不支持）
lights_kbd_toggle 切换键盘背光      （Windows 不支持）
lights_kbd_up     调高键盘背光      （Windows 不支持）
lights_kbd_down   调低键盘背光      （Windows 不支持）

部分按键存在平台差异，使用前请留意上表中的平台限制说明。

5.7 常用快捷键示例

下面是一些跨场景的常用快捷键写法（Windows/Linux 用 ctrl，macOS 通常用 cmd）：

robotgo.KeyTap("a", "ctrl") // 全选
robotgo.KeyTap("c", "ctrl") // 复制
robotgo.KeyTap("v", "ctrl") // 粘贴
robotgo.KeyTap("x", "ctrl") // 剪切
robotgo.KeyTap("z", "ctrl") // 撤销
robotgo.KeyTap("s", "ctrl") // 保存
robotgo.KeyTap("f", "ctrl") // 查找
robotgo.KeyTap("w", "ctrl") // 关闭标签/窗口
robotgo.KeyTap("t", "ctrl") // 新建标签
robotgo.KeyTap("tab", "alt") // 切换窗口（Windows）

5.8 完整示例

下面是官方键盘示例的整理版：

package main

import (
    "fmt"

    "github.com/go-vgo/robotgo"
)

func main() {
    robotgo.Type("Hello World")
    robotgo.Type("だんしゃり", 0, 1)

    robotgo.Type("Hi, Seattle space needle, Golden gate bridge.")
    robotgo.Type("こんにちは世界.")
    robotgo.Sleep(1)

    // 按 Unicode 码点输入
    ustr := uint32(robotgo.CharCodeAt("Test", 0))
    robotgo.UnicodeType(ustr)

    robotgo.KeySleep = 100
    robotgo.KeyTap("enter")
    robotgo.KeyTap("i", "alt", "cmd")

    arr := []string{"alt", "cmd"}
    robotgo.KeyTap("i", arr)

    robotgo.MilliSleep(100)
    robotgo.KeyToggle("a")
    robotgo.KeyToggle("a", "up")

    // 剪贴板配合
    robotgo.WriteAll("Test")
    text, err := robotgo.ReadAll()
    if err == nil {
        fmt.Println(text)
    }
}

5.9 实战技巧与注意事项

1. 跨平台修饰键：复制粘贴等操作 macOS 用 cmd、Windows/Linux 用 ctrl。可根据 runtime.GOOS 动态选择修饰键，写出真正跨平台的脚本。
2. 大段文本走剪贴板：长文本用 Type 既慢又容易丢字，改用剪贴板粘贴更稳。
3. 输入法干扰：在中文输入法激活状态下，Type 英文有时会被输入法拦截或转换。自动化前可先切换到英文输入法，或使用 UnicodeType。
4. 防丢键：高频按键时适当增大 KeySleep，给目标程序留出处理时间。
5. 务必松开：使用 KeyToggle 按下按键后，要确保有对应的 "up" 调用松开，否则会出现“按键卡住”的现象。

5.10 小结

本章我们完整梳理了 RobotGo 的键盘能力：用 Type / UnicodeType 输入文本，用 KeyTap 敲击按键与组合键，用 KeyToggle 控制按键状态，并用 KeySleep 调节节奏。我们还提供了完整的按键名称参考表和常用快捷键示例。下一章将进入屏幕与像素操作，让你的自动化程序具备“看见屏幕”的能力。