第03章 - 快速入门：第一个自动化程序

环境就绪后，本章我们将通过一系列由简到繁的小程序，快速建立对 RobotGo 的整体手感。你将看到鼠标、键盘、屏幕、剪贴板、提示框等核心能力如何用极少的代码组合起来，最终完成一个“记事本自动化”小例子。本章重在“跑通”和“体感”，每个 API 的细节会在后续章节深入展开。

3.1 程序骨架

所有 RobotGo 程序的结构都非常简单：导入包，然后调用函数。下面是最小骨架：

package main

import (
    "fmt"

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

func main() {
    fmt.Println("RobotGo 启动")
}

3.2 移动鼠标并点击

让我们从最直观的鼠标控制开始。下面的程序会把鼠标移动到屏幕坐标 (500, 300)，然后点击一次左键：

package main

import (
    "fmt"

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

func main() {
    // 移动到指定坐标
    robotgo.Move(500, 300)

    // 读取当前鼠标位置确认
    x, y := robotgo.Location()
    fmt.Println("当前位置:", x, y)

    // 点击左键
    robotgo.Click()

    // 点击右键
    robotgo.Click("right")

    // 双击左键
    robotgo.Click("left", true)
}

这里需要理解几个要点：

• 坐标系原点 (0, 0) 通常位于主显示器的左上角，x 向右增大，y 向下增大。
• robotgo.Move 是瞬间移动；如果想要平滑（带动画轨迹）移动，可使用 robotgo.MoveSmooth。
• robotgo.Click 不带参数默认点击左键，可传入 "right"、"center"（中键）等。

3.3 控制鼠标移动节奏

很多时候我们希望操作之间有一点延迟，让目标程序有时间响应。RobotGo 提供了全局变量 MouseSleep 来统一控制鼠标操作后的等待毫秒数：

robotgo.MouseSleep = 300 // 每次鼠标操作后等待 300 毫秒

robotgo.Move(100, 100)
robotgo.MoveSmooth(300, 300) // 平滑移动
robotgo.Move(100, -200)      // 支持多屏：负坐标可落到主屏左侧的副屏

类似地，键盘操作有 KeySleep 变量。这两个变量是控制自动化“节奏”的利器，后续章节会反复用到。

3.4 输入文本与按键

接下来体验键盘控制。robotgo.Type 用于输入一段文本（支持中英文、日文等 Unicode），robotgo.KeyTap 用于敲击单个按键或组合键：

package main

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

func main() {
    // 输入英文
    robotgo.Type("Hello, RobotGo!")

    // 输入中文（Unicode 文本同样支持）
    robotgo.Type("你好，世界")

    // 敲击回车键
    robotgo.KeyTap("enter")

    // 组合键：Ctrl + A 全选（macOS 上可用 "cmd"）
    robotgo.KeyTap("a", "ctrl")

    // 组合键：Ctrl + C 复制
    robotgo.KeyTap("c", "ctrl")
}

KeyTap 的第一个参数是主键，后面跟随任意数量的修饰键（如 ctrl、alt、shift、cmd）。完整的按键名称列表会在第 5 章详细列出。

3.5 读写剪贴板

RobotGo 内置了简单的剪贴板读写函数 WriteAll 与 ReadAll：

package main

import (
    "fmt"

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

func main() {
    // 写入剪贴板
    robotgo.WriteAll("通过 RobotGo 写入剪贴板的内容")

    // 读取剪贴板
    text, err := robotgo.ReadAll()
    if err != nil {
        fmt.Println("读取失败:", err)
        return
    }
    fmt.Println("剪贴板内容:", text)
}

剪贴板配合 KeyTap("v", "ctrl") 粘贴，是实现“批量输入大段文本”的高效方式（比逐字 Type 更快、更稳）。

3.6 读取屏幕信息与像素颜色

自动化往往需要“看见”屏幕。下面的程序读取屏幕尺寸，并获取某个坐标点的像素颜色：

package main

import (
    "fmt"

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

func main() {
    sx, sy := robotgo.GetScreenSize()
    fmt.Println("屏幕尺寸:", sx, sy)

    // 获取坐标 (100, 200) 处像素的颜色，返回十六进制字符串，如 "ffffff"
    color := robotgo.GetPixelColor(100, 200)
    fmt.Println("像素颜色:", color)
}

GetPixelColor 返回的是不带 # 的十六进制颜色字符串。通过比对像素颜色，可以判断界面是否处于某个预期状态（例如某个按钮是否变绿）。

3.7 截图保存

将屏幕区域截图保存为图片是图像识别的基础。RobotGo 提供了便捷的 SaveCapture：

package main

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

func main() {
    // 截取整个屏幕并保存
    robotgo.SaveCapture("full.png")

    // 截取从 (10, 10) 开始、宽 300 高 200 的区域
    robotgo.SaveCapture("region.png", 10, 10, 300, 200)
}

更底层的 CaptureScreen / CaptureImg 以及位图查找会在第 7、8 章详细讲解。

3.8 弹出系统提示框

RobotGo 还能弹出原生的系统对话框，用于交互或调试：

package main

import (
    "fmt"

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

func main() {
    ok := robotgo.Alert("RobotGo", "这是一个提示框，点击确定继续")
    if ok {
        fmt.Println("用户点击了确定")
    } else {
        fmt.Println("用户取消了")
    }
}

3.9 综合示例：自动化记事本

现在把上面的能力组合起来，做一个简单但完整的小例子：打开（假设已手动打开）一个文本编辑器后，自动输入文本、全选、复制，并读取剪贴板验证。

package main

import (
    "fmt"

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

func main() {
    // 设置操作节奏，给目标程序留出响应时间
    robotgo.MouseSleep = 200
    robotgo.KeySleep = 100

    // 给用户 3 秒时间切换到目标编辑器窗口
    fmt.Println("请在 3 秒内切换到文本编辑器窗口...")
    robotgo.Sleep(3)

    // 输入多行文本
    robotgo.Type("第一行：RobotGo 自动化演示")
    robotgo.KeyTap("enter")
    robotgo.Type("第二行：你好，世界")
    robotgo.KeyTap("enter")
    robotgo.Type("第三行：Hello, World")

    // 全选并复制（Windows/Linux 用 ctrl，macOS 用 cmd）
    robotgo.KeyTap("a", "ctrl")
    robotgo.KeyTap("c", "ctrl")

    // 从剪贴板读取并打印
    text, err := robotgo.ReadAll()
    if err != nil {
        fmt.Println("读取剪贴板失败:", err)
        return
    }
    fmt.Println("------ 编辑器中的内容 ------")
    fmt.Println(text)
}

运行这段程序时，请先打开一个文本编辑器（记事本、TextEdit、gedit 等），运行后迅速点进编辑器窗口。3 秒后程序会自动输入三行文字、全选复制，并把内容打印到控制台。

跨平台提示：复制粘贴的修饰键在 macOS 上通常是 cmd 而非 ctrl。编写跨平台脚本时，可以根据 runtime.GOOS 选择修饰键，第 13 章会演示这种写法。

3.10 延时与节奏控制函数一览

在自动化脚本中，合理的等待至关重要。RobotGo 提供了多种延时方式：

robotgo.Sleep(1)        // 秒级休眠：休眠 1 秒
robotgo.MilliSleep(100) // 毫秒级休眠：休眠 100 毫秒
robotgo.MouseSleep = 50 // 每次鼠标操作后自动等待 50 毫秒
robotgo.KeySleep = 30   // 每次键盘操作后自动等待 30 毫秒

Sleep / MilliSleep 是显式的“等一会儿”，而 MouseSleep / KeySleep 是隐式地为每一次操作附加固定延迟，二者结合使用能让脚本既稳定又可控。

3.11 小结

本章我们用一连串短小的示例快速体验了 RobotGo 的核心能力：移动点击鼠标、输入文本与按键、读写剪贴板、读取屏幕尺寸与像素、截图、弹出提示框，并通过一个“自动化记事本”综合示例把它们串联起来。你现在应该对 RobotGo 的编程风格有了直观感受。从下一章开始，我们将逐个模块深入，先从鼠标控制讲起。