PyAutoGUI 是一个纯 Python 编写的图形用户界面自动化库,它允许程序控制鼠标和键盘,并能够识别屏幕上的图像,从而实现跨平台的桌面自动化。该库的设计目标是简单直观,开发者只需几行代码即可模拟人类与计算机的交互行为。下面将详细讲解 PyAutoGUI 的核心功能、使用方法、注意事项以及实际应用案例,并辅以大量代码示例。
1. PyAutoGUI 概述
PyAutoGUI 基于屏幕坐标系进行操作,坐标原点 (0, 0) 位于屏幕左上角,x 轴向右增加,y 轴向下增加。它支持 Windows、macOS 和 Linux 三大主流操作系统,提供了统一的 API,使得自动化脚本无需修改即可在不同平台上运行。其主要特性包括:
模拟鼠标移动、点击、拖拽、滚动
模拟键盘按键、组合键、文本输入
截取屏幕图像,分析像素颜色
在屏幕中查找指定图像的位置
显示简单的消息弹窗,与用户交互
内置故障安全机制,防止失控
2. 安装与依赖
安装 PyAutoGUI 只需通过 pip 执行以下命令:
该库会自动安装 Pillow(图像处理库)等必要依赖。在 Linux 系统上,截图功能可能需要额外安装 scrot 工具,键盘和鼠标模拟可能需要 python3-xlib 或 python-xlib。可以通过包管理器安装:
# Debian/Ubuntusudo apt-get install scrot python3-xlib
macOS 用户需注意:从 macOS Catalina 开始,系统对辅助功能有严格限制。运行 PyAutoGUI 脚本的终端或 IDE 需要在“系统偏好设置 > 安全性与隐私 > 隐私 > 辅助功能”中勾选允许。
3. 鼠标控制
PyAutoGUI 提供了丰富的鼠标操作函数,所有操作都可以通过可选参数控制速度(duration)和动作平滑度。
3.1 获取屏幕信息
import pyautogui# 获取屏幕分辨率screen_width, screen_height = pyautogui.size()print(f"屏幕宽度: {screen_width}, 屏幕高度: {screen_height}")# 获取当前鼠标位置current_x, current_y = pyautogui.position()print(f"当前鼠标坐标: ({current_x}, {current_y})")
3.2 鼠标移动
moveTo(x, y) 将鼠标移动到绝对坐标;moveRel(xOffset, yOffset) 相对当前位置移动。
# 瞬间移动到 (100, 200)pyautogui.moveTo(100, 200)# 用 2 秒时间平滑移动到 (500, 500)pyautogui.moveTo(500, 500, duration=2)# 相对当前位置向右移动 50 像素,向下移动 100 像素pyautogui.moveRel(50, 100, duration=1)
3.3 鼠标点击
点击操作包含按下和释放两个动作,PyAutoGUI 提供了组合函数和单独控制。
# 左键单击当前位置pyautogui.click()# 在指定位置右键单击pyautogui.rightClick(200, 300)# 双击左键pyautogui.doubleClick(x=400, y=500)# 中键点击pyautogui.middleClick()# 按下左键不放pyautogui.mouseDown(button='left')# 释放左键pyautogui.mouseUp(button='left')
3.4 鼠标拖拽
拖拽操作可以用于文件移动、绘图等场景。
# 从当前位置拖拽到 (600, 400),持续 1 秒pyautogui.dragTo(600, 400, duration=1)# 相对当前位置向右拖拽 100 像素,向下拖拽 200 像素pyautogui.dragRel(100, 200, duration=0.5)
3.5 鼠标滚轮
通过 scroll() 可以模拟滚轮滚动,正数向上滚动,负数向下滚动。
# 向上滚动 10 个单位pyautogui.scroll(10)# 向下滚动 5 个单位pyautogui.scroll(-5)
4. 键盘控制
键盘操作包括输入文本、按下特定键和组合键。按键名称遵循 PyAutoGUI 定义的常量,如 'enter'、'esc'、'f1' 等。
4.1 输入文本
write() 函数可以逐个字符地输入字符串,通过 interval 参数设置每个字符之间的间隔(秒)。
import pyautogui# 输入 "Hello World!",每个字符间隔 0.1 秒pyautogui.write('Hello World!', interval=0.1)# 输入中文(取决于当前输入法状态)pyautogui.write('你好') # 如果输入法是中文,则可能输出拼音或汉字
4.2 按下和释放按键
press() 模拟一次按下并释放按键;keyDown() 和 keyUp() 分别控制按下和释放,可用于实现长按效果。
# 按下回车键pyautogui.press('enter')# 长按 Shift 键,然后按字母 a,然后释放 Shiftpyautogui.keyDown('shift')pyautogui.press('a')pyautogui.keyUp('shift')# 上述操作相当于输入大写字母 A
4.3 组合键
hotkey() 函数可以方便地按下组合键,它会按照顺序按下所有键,再反向释放。
# 全选 (Ctrl+A)pyautogui.hotkey('ctrl', 'a')# 复制 (Ctrl+C)pyautogui.hotkey('ctrl', 'c')# 粘贴 (Ctrl+V)pyautogui.hotkey('ctrl', 'v')# 保存 (Ctrl+S)pyautogui.hotkey('ctrl', 's')# 在 macOS 上 Command 键对应 'command'pyautogui.hotkey('command', 'c')
4.4 特殊键列表
常用按键名称:'enter'、'esc'、'shift'、'ctrl'、'alt'、'tab'、'backspace'、'delete'、'up'、'down'、'left'、'right'、'home'、'end'、'pageup'、'pagedown'、'f1'...'f12'。
5. 屏幕截图与图像识别
图像识别是 PyAutoGUI 的一大亮点,它可以在屏幕上查找指定的图片,并返回其位置,非常适合点击动态变化的 GUI 元素。
5.1 屏幕截图
screenshot() 可以截取全屏或指定区域,并返回一个 Pillow 图像对象,也可以直接保存到文件。
import pyautogui# 截取全屏full_screen = pyautogui.screenshot()full_screen.save('full.png')# 截取指定区域 (left, top, width, height)region = pyautogui.screenshot(region=(100, 100, 300, 200))region.save('region.png')# 获取某个像素点的颜色pixel_color = pyautogui.pixel(500, 300)print(pixel_color) # 输出 RGB 元组,如 (255, 255, 255)# 判断像素点是否匹配某个颜色is_white = pyautogui.pixelMatchesColor(500, 300, (255, 255, 255))print(is_white) # True 或 False
5.2 查找图像
locateOnScreen() 在屏幕中查找给定图像,返回第一个匹配位置的 Box 对象(包含 left, top, width, height 属性);如果未找到则返回 None。locateAllOnScreen() 返回所有匹配位置的生成器。
# 查找屏幕上是否有某个按钮图像button_location = pyautogui.locateOnScreen('button.png')if button_location: # 获取图像中心点 center_x, center_y = pyautogui.center(button_location) pyautogui.click(center_x, center_y)else: print("未找到按钮")# 查找所有匹配位置for pos in pyautogui.locateAllOnScreen('icons.png'): print(pos)
5.3 图像匹配精度与模糊匹配
默认情况下,locateOnScreen 要求像素完全匹配。如果图像有轻微变化或不同分辨率,可以安装 OpenCV(pip install opencv-python)后使用 confidence 参数进行模糊匹配(基于灰度匹配)。
# 需要安装 opencv-pythonlocation = pyautogui.locateOnScreen('button.png', confidence=0.8)if location: pyautogui.click(pyautogui.center(location))
注意:confidence 参数会显著增加计算时间,并且要求图像具有足够的特征。
5.4 图像识别的高级用法
有时需要连续查找直到图像出现,或者超时处理。可以结合循环和 time.sleep 实现等待机制。
import timetimeout = 10 # 最多等待 10 秒start_time = time.time()while True: location = pyautogui.locateOnScreen('loading_done.png') if location: print("加载完成") break if time.time() - start_time > timeout: print("超时") break time.sleep(0.5)
6. 消息弹窗
PyAutoGUI 提供了一些简单的弹窗函数,用于与用户交互,例如显示信息、警告或获取输入。
# 显示提示信息,用户点击 OK 后继续pyautogui.alert('这是一个提示框')# 显示确认对话框,用户点击 OK 或 Cancel,返回文本 'OK' 或 'Cancel'result = pyautogui.confirm('是否继续?')if result == 'OK': print("用户选择了继续")# 显示带输入框的对话框,返回用户输入的字符串user_input = pyautogui.prompt('请输入你的名字')print(f"你好,{user_input}")# 显示密码输入框,输入内容显示为掩码password = pyautogui.password('请输入密码')
这些弹窗是阻塞的,即脚本会暂停直到用户响应。
7. 安全机制与故障恢复
为了防止自动化脚本失控,PyAutoGUI 提供了两个重要的安全特性:
7.1 故障安全(Failsafe)
当 pyautogui.FAILSAFE = True(默认值)时,如果在脚本运行过程中将鼠标快速移动到屏幕左上角(坐标 (0,0)),PyAutoGUI 会抛出 pyautogui.FailSafeException 异常,从而终止脚本。这是紧急停止的常用方法。
import pyautoguitry: # 一些可能失控的操作 while True: pyautogui.moveRel(1, 0)except pyautogui.FailSafeException: print("触发了故障安全,脚本已停止")
如果希望禁用此功能,可以设置 pyautogui.FAILSAFE = False,但不推荐。
7.2 暂停设置
设置 pyautogui.PAUSE 可以为每个 PyAutoGUI 函数调用之间添加一个固定的延迟(秒),避免操作过快导致程序来不及响应。
pyautogui.PAUSE = 0.5 # 每个操作后暂停 0.5 秒
这样在连续调用 moveTo、click 等函数时,会自动等待指定时间。
8. 实际应用案例
下面通过几个完整的示例展示 PyAutoGUI 的实战用法。
8.1 自动打开记事本并输入内容
import pyautoguiimport time# 打开运行对话框pyautogui.hotkey('win', 'r')time.sleep(1)# 输入 "notepad" 并回车pyautogui.write('notepad')pyautogui.press('enter')# 等待记事本窗口打开time.sleep(2)# 输入一段文字pyautogui.write('Hello, PyAutoGUI!', interval=0.1)pyautogui.press('enter')pyautogui.write('This is an automated input.')# 保存文件pyautogui.hotkey('ctrl', 's')time.sleep(1)# 输入文件名并保存pyautogui.write('automated.txt')pyautogui.press('enter')
8.2 屏幕像素颜色检测自动点击
假设一个游戏或应用中,当某个区域变为红色时表示需要点击,可以通过检测颜色变化来触发点击。
import pyautoguiimport timetarget_color = (255, 0, 0) # 红色region = (500, 300, 100, 100) # 监控区域print("开始监控...")while True: # 截取区域图像 img = pyautogui.screenshot(region=region) # 获取区域中心点的颜色(也可以遍历像素,此处简化) center_x = region[0] + region[2] // 2 center_y = region[1] + region[3] // 2 if pyautogui.pixelMatchesColor(center_x, center_y, target_color, tolerance=10): pyautogui.click(center_x, center_y) print("检测到红色,已点击") break time.sleep(0.1)
8.3 图像识别自动登录
假设有一个应用程序启动后需要点击“登录”按钮,然后输入用户名和密码。
import pyautoguiimport timedef wait_and_click(image_path, timeout=10, confidence=0.8): """等待图像出现并点击,超时返回 False""" start = time.time() while time.time() - start < timeout: location = pyautogui.locateOnScreen(image_path, confidence=confidence) if location: pyautogui.click(pyautogui.center(location)) return True time.sleep(0.5) return False# 等待应用界面加载,点击登录按钮if wait_and_click('login_button.png'): time.sleep(1) # 输入用户名 pyautogui.write('my_username') pyautogui.press('tab') # 输入密码 pyautogui.write('my_password') pyautogui.press('enter')else: print("未找到登录按钮")
9. 跨平台注意事项
macOS 权限:在 macOS 上运行需要辅助功能权限,且可能需要为 Python 解释器(如 /usr/bin/python 或虚拟环境中的 python)单独授权。
Linux 显示服务器:在 Wayland 上可能无法正常工作,因为 Wayland 限制了跨应用输入模拟。建议切换到 X11 或使用 Xvfb 虚拟显示器。
屏幕缩放:如果系统启用了屏幕缩放(如 Windows 125% 缩放),PyAutoGUI 的坐标依然基于逻辑像素,可能与图像识别中的像素坐标不一致。可以在截图中考虑缩放比例,或使用图像识别时基于图像本身。
多显示器:坐标系统会跨越所有显示器,主显示器左上角为 (0,0),向右下延伸覆盖所有显示器。鼠标移动可能进入其他显示器。
10. 与其他库的结合
PyAutoGUI 经常与以下库搭配使用,以增强功能:
OpenCV:用于更复杂的图像处理、特征匹配,或者提高 locateOnScreen 的识别率。
Pillow:PyAutoGUI 已经依赖 Pillow,可以直接利用其图像处理功能(如裁剪、滤镜)预处理截图。
pynput:用于监听鼠标和键盘事件,可以结合 PyAutoGUI 实现更复杂的交互。
schedule:用于定时执行自动化任务。
logging:记录自动化过程,便于调试。
例如,使用 OpenCV 调整图像大小后再进行匹配:
import cv2import numpy as npimport pyautogui# 截取屏幕screenshot = pyautogui.screenshot()# 转换为 OpenCV 格式cv_image = cv2.cvtColor(np.array(screenshot), cv2.COLOR_RGB2BGR)# 读取模板图像template = cv2.imread('button.png')# 使用模板匹配(此处仅示例,实际还是用 locateOnScreen 更方便)result = cv2.matchTemplate(cv_image, template, cv2.TM_CCOEFF_NORMED)# ... 处理结果
11. 性能优化与常见问题
11.1 提高图像识别速度
缩小搜索区域:尽量指定 region 参数,只搜索可能出现的区域。
降低图像分辨率:如果不需要高精度匹配,可以预先缩小屏幕截图和模板图像。
使用 grayscale=True 进行灰度匹配(需安装 OpenCV),速度更快。
location = pyautogui.locateOnScreen('button.png', region=(0, 0, 800, 600), grayscale=True)
11.2 处理不同屏幕分辨率
如果脚本要在不同分辨率的机器上运行,最好使用相对坐标或图像识别。相对坐标可基于屏幕尺寸计算:
screen_w, screen_h = pyautogui.size()pyautogui.click(screen_w * 0.5, screen_h * 0.5) # 点击屏幕中央
11.3 异常处理与重试
自动化过程中可能因为各种原因失败(如弹窗未出现),建议添加重试机制。
def click_with_retry(image_path, retries=3, delay=1): for i in range(retries): location = pyautogui.locateOnScreen(image_path) if location: pyautogui.click(pyautogui.center(location)) return True time.sleep(delay) raise Exception(f"在 {retries} 次尝试后仍未找到图像 {image_path}")
11.4 防止误操作
在运行可能影响系统稳定性的脚本前,可以弹出确认框让用户确认:
if pyautogui.confirm('即将开始自动化,是否继续?') != 'OK': exit()
12. 总结
PyAutoGUI 是一个功能全面且易于上手的 GUI 自动化库,通过简洁的 Python 代码即可模拟复杂的鼠标键盘操作,并结合屏幕截图与图像识别实现自适应交互。无论是个人效率工具、软件测试还是业务流程自动化,PyAutoGUI 都能发挥重要作用。在使用过程中,合理运用故障安全机制、图像识别参数和异常处理,可以使脚本更加健壮可靠。希望本文的详细介绍和代码示例能够帮助你快速掌握 PyAutoGUI,并将其应用于实际项目中。