PyAutoGUI Python 桌面自动化框架实战指南

• 指定按键点击：支持左键（left）、右键（right）、中键（middle）

# 右键单击
pyautogui.click(x=100, y=200, button='right', duration=0.2)
# 中键单击
pyautogui.click(x=100, y=200, button='middle', duration=0.2)

• 双击/三击：快速执行多次点击

# 左键双击
pyautogui.doubleClick(x=100, y=200, duration=0.2)
# 左键三击
pyautogui.tripleClick(x=100, y=200, duration=0.2)

鼠标拖拽

模拟鼠标按住并拖动的行为，常用于文件拖拽、窗口调整等场景：

# 从 (x1, y1) 拖拽到 (x2, y2)，按住左键拖拽
pyautogui.dragTo(x=300, y=400, duration=0.8, button='left')
# 相对拖拽：基于当前位置偏移拖拽
pyautogui.dragRel(dx=100, dy=50, duration=0.5, button='left')

鼠标滚轮

模拟滚轮滚动行为，clicks 参数指定滚动幅度（正数向上滚，负数向下滚）：

# 向下滚动 5 格（负数表示向下）
pyautogui.scroll(clicks=-5, x=100, y=200)
# 向上滚动 3 格（正数表示向上）
pyautogui.scroll(clicks=3, x=100, y=200)

键盘操作：模拟输入与快捷键

普通文本输入

使用 typewrite() 方法输入字符串，支持指定输入间隔（模拟人工输入速度）：

# 直接输入文本
pyautogui.typewrite("Hello, PyAutoGUI!")
# 带间隔输入（每个字符间隔 0.2 秒）
pyautogui.typewrite("Hello, PyAutoGUI!", interval=0.2)

特殊按键输入

对于回车键、空格键、快捷键等特殊按键，需使用按键名称（封装在 PyAutoGUI 中）。核心方法包括 press()（单次按下并释放）、keyDown()（按住不释放）和 keyUp()（释放按住的按键）。

# 单个特殊按键：按下并释放回车键
pyautogui.press('enter')

# 组合快捷键：Ctrl + C（复制）
pyautogui.keyDown('ctrl')
pyautogui.press('c')
pyautogui.keyUp('ctrl')

# 简化组合快捷键：使用 hotkey() 方法（推荐）
pyautogui.hotkey('ctrl', 'c')  # 复制
pyautogui.hotkey('ctrl', 'v')  # 粘贴
pyautogui.hotkey('ctrl', 'a')  # 全选

常用特殊按键名称包括：enter（回车）、space（空格）、backspace（删除）、tab（制表符）、shift、ctrl、alt 等。

屏幕与图像识别：定位目标元素

屏幕基础信息获取

获取屏幕分辨率（用于确定坐标范围）：

# 获取屏幕宽度和高度
screen_width, screen_height = pyautogui.size()
print(f"屏幕分辨率：{screen_width} × {screen_height}")

# 获取当前鼠标位置坐标
mouse_x, mouse_y = pyautogui.position()
print(f"当前鼠标位置：({mouse_x}, {mouse_y})")

图像定位：查找屏幕上的目标图像

PyAutoGUI 支持通过目标图像（如按钮截图、图标截图），自动查找其在屏幕上的坐标，核心方法是 locateOnScreen()。

操作步骤：

1. 先截取目标元素的截图（保存为 PNG 格式，推荐使用截图工具精准截取）
2. 使用 locateOnScreen() 查找图像位置，返回目标区域的坐标和尺寸
3. 通过 center() 方法获取目标区域的中心坐标（便于点击等操作）

import pyautogui
import time

# 等待 3 秒，预留时间切换到目标屏幕
time.sleep(3)

try:
    # 查找目标图像（image.png 为目标截图路径）
    # confidence：匹配精度（0-1，默认 1，降低精度可提高查找成功率，需安装 opencv-python 支持）
    target_location = pyautogui.locateOnScreen('image.png', confidence=0.8)
    
    if target_location:
        # 获取目标图像的中心坐标
        target_center = pyautogui.center(target_location)
        print(f"目标图像位置：{target_location}，中心坐标：{target_center}")
        # 点击目标中心
        pyautogui.click(target_center.x, target_center.y, duration=0.2)
    else:
        print("未找到目标图像")
except Exception as e:
    print(f"查找失败：{e}")

注意：使用 confidence 参数时，需额外安装 opencv-python：pip install opencv-python

屏幕截图

# 截取整个屏幕并保存为文件
pyautogui.screenshot('full_screen.png')

# 截取指定区域屏幕（x1, y1, 宽度，高度）
pyautogui.screenshot('partial_screen.png', region=(100, 100, 300, 200))

安全机制：防止自动化失控

PyAutoGUI 提供了关键的安全保护机制，避免自动化操作失控（如鼠标移到屏幕边缘无法找回、无限循环操作等）。

故障安全触发

默认开启：当鼠标移动到屏幕左上角（坐标 (0, 0)）时，会立即抛出 FailSafeException 异常，终止所有自动化操作：

# 若操作失控，快速将鼠标移到屏幕左上角即可停止程序
try:
    while True:
        pyautogui.moveRel(10, 0, duration=0.1)
except pyautogui.FailSafeException:
    print("故障安全机制触发，程序终止")

操作延迟

通过 PAUSE 属性设置所有 PyAutoGUI 操作的默认间隔时间（秒），便于观察操作过程，也可防止操作过快导致程序异常：

# 设置所有操作间隔 0.5 秒
pyautogui.PAUSE = 0.5

实战示例：简单自动化操作

下面是一个完整的脚本示例，演示了打开记事本并输入文本的过程：

import pyautogui
import time

# 安全设置
pyautogui.PAUSE = 0.5  # 操作间隔 0.5 秒
pyautogui.FAILSAFE = True  # 开启故障安全机制

# 1. 等待 5 秒，预留时间打开记事本
print("5 秒后开始操作，请打开记事本...")
time.sleep(5)

# 2. 输入文本
pyautogui.typewrite("Python 自动化 - PyAutoGUI 实战", interval=0.1)

# 3. 换行
pyautogui.press('enter')

# 4. 输入第二行文本
pyautogui.typewrite("这是一个简单的自动化演示", interval=0.1)

# 5. 全选文本（Ctrl + A）
pyautogui.hotkey('ctrl', 'a')

# 6. 复制文本（Ctrl + C）
pyautogui.hotkey('ctrl', 'c')

# 7. 弹窗提示操作完成
pyautogui.alert("自动化操作完成！")