Python第三方PyAutoGUI库详解

        PyAutoGUI 是一个用于进行图形用户界面（GUI）自动化的 Python 库。它允许你在屏幕上进行鼠标和键盘的模拟操作，以及获取屏幕上的信息，其函数主要分为以下4类：

        1、屏幕图像操作：获取屏幕分辨率、检查坐标是否在屏幕上、截屏、定位图片在屏幕上的位置、获取屏幕某个像素点的RGB值

        2、鼠标控制：获取当前鼠标位置、移动鼠标、鼠标拖拽、鼠标点击

        3、键盘控制：输入字符串、组合按键（快捷键）、同时输入字符+按键

        4、消息弹窗：仅确认弹窗、确认取消弹窗、输入普通内容弹窗、输入密码弹窗

中文文档链接：Python中PyAutoGUI帮助文档(推荐!)_python_脚本之家

英文文档链接：Cheat Sheet — PyAutoGUI documentation

文中示例所用PyAutoGUI版本为: 0.9.54，2024.1.25

注意：从0.9.41版本开始若未找到指定图片的定位，会引发ImageNotFoundException异常而不是返回None。

一、简介

目的

PyAutoGUI是一个纯Python的GUI自动化工具，其目的是可以用程序自动控制鼠标和键盘操作，多平台支持。可以用pip安装，Github上有源代码。

PyAutoGUI可以模拟鼠标的移动、点击、拖拽，键盘按键输入、按住操作，以及鼠标+键盘的热键同时按住等操作，可以说手能动的都可以。

保护措施

每次调用PyAutoGui函数都延迟2.5秒

pyautogui.PAUSE = 2.5

当pyautogui.FAILSAFE = True时，如果把鼠标光标在屏幕左上角，PyAutoGUI函数就会产生pyautogui.FailSafeException异常。

import pyautogui

pyautogui.FAILSAFE = True

就像《魔法师的学徒》(Sorcerer’s Apprentice)会担水的扫帚，可以担水，却无力阻止水漫浴室。你的程序也可能会失控（即使是按照你的意思执行的），那时就需要中断。如果鼠标还在自动操作，就很难在程序窗口关闭它。

为了能够及时中断，PyAutoGUI提供了一个保护措施。当pyautogui.FAILSAFE = True时，如果把鼠标光标在屏幕左上角，PyAutoGUI函数就会产生pyautogui.FailSafeException异常。如果失控了，需要中断PyAutoGUI函数，就把鼠标光标在屏幕左上角。要禁用这个特性，就把FAILSAFE设置成False：

Import pyautogui

Pyautogui.FAILSAFE = False

通过把pyautogui.PAUSE设置成float或int时间（秒），可以为所有的PyAutoGUI函数增加延迟。默认延迟时间是0.1秒。在函数循环执行的时候，这样做可以让PyAutoGUI运行的慢一点，非常有用。例如：

import pyautogui

pyautogui.PAUSE = 2.5

pyautogui.moveTo(100,100); pyautogui.click()

所有的PyAutoGUI函数在延迟完成前都处于阻塞状态（block）。（未来计划增加一个可选的非阻塞模式来调用函数。）

建议PAUSE和FAILSAFE一起使用。

安装与依赖

PyAutoGUI支持Python 2.x和Python 3.x

Windows：PyAutoGUI没有任何依赖，因为它用Python的ctypes模块所以不需要pywin32

pip3 install pyautogui

二、鼠标控制函数

屏幕和鼠标位置

鼠标在屏幕上的位置由x和y的坐标表示，x的0点在屏幕的最左上角，往右滑动坐标增加；y坐标原点0也在屏幕左上角，右下滑坐标增加。

如你的屏幕分辨率是1920x1080，则最右下角的坐标是1919，1079（坐标从0开始计数）

——pyautogui.size()：获取屏幕分辨率

屏幕分辨率可以通过函数size()获取，返回一个2个整数的元组。

例：

import pyautogui

print(pyautogui.size()) # Size(width=1920, height=1080)

——pyautogui.position()：获取当前鼠标位置

例1：

import pyautogui

print(pyautogui.position()) # Point(x=1290, y=376)

例2：不间断输出当前光标位置

#! python3import pyautogui, sysprint('Press Ctrl-C to quit.')try:

    while True:

        x, y = pyautogui.position()

        positionStr = 'X: ' + str(x).rjust(4) + ' Y: ' + str(y).rjust(4)

        print(positionStr, end='')

        print('\b' * len(positionStr), end='', flush=True)except KeyboardInterrupt:

    print('\n')

——pyautogui.onScreen(x,y)：检查坐标是否在屏幕上

例：

import pyautogui, sys

# 当前屏幕分辨率

size = pyautogui.size()

# 检查坐标是否在屏幕上

resolution1 = pyautogui.onScreen(1920, 1080)

# 坐标是从0开始，因为右下角坐标是1920-1，1080-1

resolution2 = pyautogui.onScreen(1919, 1079)

print(size,resolution1,resolution2)

# Size(width=1920, height=1080) False True

鼠标移动

1、pyautogui.moveTo(x, y, duration=seconds, tween=pyautogui.linear)

用于将鼠标光标移动到屏幕上的指定位置。

如果使用None值，则表示使用当前光标的坐标值。

参数：

x 和 y: 目标位置的横纵坐标。

duration: 鼠标移动到目标位置的持续时间（秒）。可选参数，默认为0.1s，表示鼠标瞬间移动到目标位置。。

tween: 缓动函数，用于控制鼠标移动的速度曲线。可选参数，默认为线性缓动 (pyautogui.linear)。

例：

import pyautogui

# 将鼠标移动到屏幕的坐标 (100, 100)，持续时间为1秒

pyautogui.moveTo(100, 100, duration=1)

# 如果使用None值，则表示使用当前光标的坐标值。

pyautogui.moveTo(None,100,duration=1)

pyautogui.moveTo(100,None,duration=1)

2、pyautogui.move(x, y, duration=seconds, tween=pyautogui.linear)

相对于鼠标当前位置进行移动。参数与moveTo一样。

例：

import pyautogui, sys

# 相对鼠标当前坐标向右移动100像素

pyautogui.move(100,0,duration=1,tween=pyautogui.linear)

# 相对鼠标当前坐标向下移动100像素

pyautogui.move(0,100,duration=1,tween=pyautogui.linear)

pyautogui.move(0,-100,duration=1,tween=pyautogui.linear)

pyautogui.move(-10,0,duration=1,tween=pyautogui.linear)

鼠标拖拽

dragTo()和drag()函数和moveTo()及move()函数参数类似，另外，他们还有'button'参数可以设置为'left','middle','right'，用于设置用哪个鼠标按键拖拽。

1、pyautogui.dragTo(x, y, duration=seconds, button='left', tween=pyautogui.linear)

用于模拟鼠标拖拽操作（还可以用mouseDown和moveTo、mouseUp函数模拟拖拽操作）。

参数说明：

x 和 y: 拖拽的目标位置的横纵坐标。

duration: 拖拽操作的持续时间（秒）。可选参数，默认为0，表示鼠标瞬间拖拽到目标位置。

button: 鼠标按钮，可以是 'left'、'middle' 或 'right'。可选参数，默认为 'left'。

tween: 缓动函数，用于控制鼠标拖拽的速度曲线。可选参数，默认为线性缓动 (pyautogui.linear)。

示例：

import pyautogui

# 模拟鼠标左键拖拽到屏幕的坐标 (200, 200)，持续时间为2秒

pyautogui.dragTo(200, 200, duration=2, button='left')

PS：duration参数必须要设置大于0.2（默认是0.1s），否则会拖拽失败。

2、pyautogui.drag(x, y, duration=seconds, button='left', tween=pyautogui.linear)

相对鼠标当前位置拖拽指定距离。参数同dragTo()函数。

缓动/渐变函数

Tween是鼠标移动过程中一个额外参数，如果你不在乎鼠标的移动方式，可以跳本节。

缓动/渐变函数可以改变光标移动过程的速度和方向。通常鼠标是匀速直线运动，这就是线性缓动/渐变函数。

31种可用缓动/渐变函数列表

• 'linear'：匀速。
• 'easeInQuad'：加速。
• 'easeOutQuad'：减速。
• 'easeInOutQuad'：先加速后减速。
• 'easeInCubic'：立方缓入。
• 'easeOutCubic'：立方缓出。
• 'easeInOutCubic'：立方缓入缓出。
• 'easeInQuart'：四次方缓入。
• 'easeOutQuart'：四次方缓出。
• 'easeInOutQuart'：四次方缓入缓出。
• 'easeInQuint'：五次方缓入。
• 'easeOutQuint'：五次方缓出。
• 'easeInOutQuint'：五次方缓入缓出。
• 'easeInSine'：正弦波缓入。
• 'easeOutSine'：正弦波缓出。
• 'easeInOutSine'：正弦波缓入缓出。
• 'easeInExpo'：指数函数缓入。
• 'easeOutExpo'：指数函数缓出。
• 'easeInOutExpo'：指数函数缓入缓出。
• 'easeInCirc'：圆圈缓入。

1. 'easeOutCirc'：圆圈缓出。
2. 'easeInOutCirc'：圆圈缓入缓出。
3. 'easeInElastic'：弹性缓入。
4. 'easeOutElastic'：弹性缓出。
5. 'easeInOutElastic'：弹性缓入缓出。
6. 'easeInBack'：后置回退缓入。
7. 'easeOutBack'：后置回退缓出。
8. 'easeInOutBack'：后置回退缓入缓出。
9. 'easeInBounce'：反弹缓入。
10. 'easeOutBounce'：反弹缓出。
11. 'easeInOutBounce'：反弹缓入缓出。

示例：

import pyautogui

# 加速向右移动300像素

pyautogui.move(300,0,duration=1,tween=pyautogui.easeInQuad)

这些效果函数是模仿Al Sweigart的PyTweening模块，可以直接使用，不需要额外安装。

如果你想创建自己的效果，也可以定义一个函数，其参数是(0.0,1.0)，表示起点和终点，返回值是介于[0.0,1.0]之间的数。

鼠标点击函数

XY坐标起始值为屏幕左上角0，0，X坐标随着鼠标右移增加，Y坐标随着鼠标下移增加。

import time

import pyautogui

x,y = pyautogui.position(100,100)

num_seconds = 1

# 用1秒的时间将鼠标移至x,y坐标上

pyautogui.moveTo(x, y, duration=num_seconds)  

xOffset, yOffset = 100,100

# 将鼠标从当前位置偏移xOffset, yOffset像素

pyautogui.moveRel(xOffset, yOffset, duration=num_seconds)  

若duration参数（时长）为0或未指定，则鼠标指针会瞬间移到目标点上。注：拖动操作在Mac上不能被立即执行。

>>> pyautogui.dragTo(x, y, duration=num_seconds)  # drag mouse to XY

>>> pyautogui.dragRel(xOffset, yOffset, duration=num_seconds)  # drag mouse relative to its current position

1、pyautogui.click(x=None, y=None, clicks=1, interval=0.0, button='left', duration=0.0, tween=pyautogui.linear)

用于模拟鼠标点击操作。

参数说明：

x：鼠标点击的目标横坐标。如果未指定，则使用当前鼠标位置。

y：鼠标点击的目标纵坐标。如果未指定，则使用当前鼠标位置。

clicks：点击的次数，默认为1次。

interval：两次点击之间的时间间隔，默认为0秒。

button：指定点击的鼠标按钮，可选值为 'left'、'middle'、'right'。默认为 'left'。

duration：模拟点击的持续时间，默认为0秒。

tween：设置点击的缓动函数，默认为线性缓动。

示例：

import pyautogui

# 模拟左键单击

pyautogui.click()

# 模拟右键双击，点击坐标为(100, 200)

pyautogui.click(100, 200, clicks=2, button='right')

# 模拟中键单击，点击坐标为(300, 400)，间隔0.5秒

pyautogui.click(300, 400, button='middle', interval=0.5)

2、pyautogui.leftClick(x=None, y=None, clicks=1, interval=0.0, duration=0.0, tween=pyautogui.linear)

用于模拟鼠标左键点击。参数功能同click()函数。

例：

import pyautogui

# 模拟左键单击

pyautogui.leftClick()

# 模拟左键双击，点击坐标为(100, 200)

pyautogui.leftClick(100, 200, clicks=2)

# 模拟左键单击，点击坐标为(300, 400)，间隔0.5秒

pyautogui.leftClick(300, 400, interval=0.5)

3、pyautogui.middleClick(x=None, y=None, clicks=1, interval=0.0, duration=0.0, tween=pyautogui.linear)

        用于模拟鼠标中键点击。        

4、pyautogui.rightClick(x=None, y=None, clicks=1, interval=0.0, duration=0.0, tween=pyautogui.linear)

        用于模拟鼠标右键点击。

5、pyautogui.doubleClick(x=None, y=None, interval=0.0, duration=0.0, tween=pyautogui.linear)

用于模拟鼠标左键双击。

6、pyautogui.tripleClick(x=None, y=None, interval=0.0, duration=0.0, tween=pyautogui.linear)

用于模拟鼠标左键三次点击。

鼠标按下和松开函数

1、pyautogui.mouseDown(x=None, y=None, button='left')

用于模拟鼠标按下操作。

参数说明：

x：鼠标按下的目标横坐标。如果未指定，则使用当前鼠标位置。

y：鼠标按下的目标纵坐标。如果未指定，则使用当前鼠标位置。

button：指定按下的鼠标按钮，可选值为 'left'、'middle'、'right'。默认为 'left'。

示例：

import pyautogui

# 模拟左键按下，按下位置为当前鼠标位置

pyautogui.mouseDown()

# 模拟右键按下，按下位置为(100, 200)

pyautogui.mouseDown(100, 200, button='right')

需要注意的是，按下操作后，通常需要调用 pyautogui.mouseUp() 函数来模拟鼠标释放的动作，以完成整个鼠标点击操作。

2、pyautogui.mouseUp(x=None, y=None, button='left')

用于模拟鼠标释放操作。参数同mouseDown()。

鼠标滚轮滚动函数

1、pyautogui.scroll(amount_to_scroll, x=moveToX, y=moveToY)

用于模拟鼠标滚滚动操作。

参数说明：

amount：滚动的距离，正值表示向上滚动，负值表示向下滚动。

x：滚轮滚动的横坐标。如果未指定，则使用当前鼠标位置。

y：滚轮滚动的纵坐标。如果未指定，则使用当前鼠标位置。

PS：此处x,y指定从屏幕哪个位置开始滚动，并不会改变鼠标的位置。

示例：

import pyautogui

# 向上滚动鼠标滚轮，滚动距离为3

pyautogui.scroll(3)

# 向下滚动鼠标滚轮，滚动距离为-2，滚轮滚动位置为(100, 200)

pyautogui.scroll(-2, x=100, y=200)

三、键盘控制函数

键盘上可以按的键都可以调用。

1、pyautogui.typewrite(message, interval=0.0, pause=None, logScreenshot=None, _pause=True)

用于模拟键盘输入。

参数：

message (必需): 要输入的文本字符串。

interval (可选): 每个按键之间的时间间隔。默认为0，表示没有间隔。如果需要模拟更自然的键入速度，可以设置一个小的时间间隔。

pause (可选): 在输入不同的消息之间的暂停时间。如果设置为None，则使用默认值，即2.5秒。如果设置为数字，则表示暂停的秒数。

logScreenshot (可选): 如果设置为True，将在每个按键后创建一个屏幕截图。默认为None。

_pause (可选): 如果设置为True，将在每个按键之后等待，以确保按键被正确处理。默认为True。

message参数是字符串时将被当作要键入的字符，如：'abc'；如为列表时键盘常量被视键盘按下，非键盘常量被视为键入字符，如['a','b','left']，其中'ab'被视为键入的字符串，'left'被视为按键的左箭头。

示例1：键入文本

import pyautogui

# 获取当前鼠标坐标

x,y = pyautogui.position()

# 鼠标左键单击

pyautogui.click(x=x,y=y)

# 键入文本

pyautogui.typewrite("hello,world!")

示例2：用列表键入字符串和按键，按键常量将被识别为按键操作

import pyautogui

# 先模拟输入字符串'a,b,c'，然后模拟按下键盘的left、backspace、enter、f1键

pyautogui.typewrite(['a', 'b', 'c', 'left', 'backspace', 'enter', 'f1'], interval=secs_between_keys)

——查看键盘常量：pyautogui.KEYBOARD_KEYS

2、pyautogui.write(message, interval=0.0)

用于模拟键盘输入。主要用来输入字符串。

当message参数为单个字符串，输入的是字符串；当参数为列表时，可以模拟按键。

参数说明：

message: 要输入的文本字符串或列表。

interval: 模拟键盘输入的间隔时间（秒）。可选参数，默认为0.0。

示例：

import pyautogui  

  

# 使用列表参数键入 "hello"并按下“enter”键, 

# 注：用列表键入字符串时每次只能键入单个字母

pyautogui.write(['h', 'e', 'l', 'l','o','enter'],interval=0.25)  

  

# 键入字符串

pyautogui.write('world!',interval=0.25)

3、pyautogui.press(keys, presses=1, interval=0.0)

用于模拟按下和释放键盘按键。

参数说明：

keys: 要按下和释放的按键，可以是字符串或字符串列表。例如，'a' 表示按下和释放键盘上的 'a' 键，['ctrl', 'c'] 表示按下和释放 Ctrl + C。

presses: 模拟按下和释放按键的次数。可选参数，默认为1。

interval: 连续按键之间的间隔时间（秒）。可选参数，默认为0.0。

例：

import pyautogui  

  

# 模拟按下'a'键一次

pyautogui.press('a',presses=1,interval=0.0)

# 模拟按下和释放Ctrl,c，重复3次，每次按键间隔0.5秒

pyautogui.press(['ctrl','c'],presses=3,interval=0.5)

4、pyautogui.keyDown(key, args...)

用于模拟按下键盘上的一个键。

参数：

key: 要按下的键的字符串表示，可以是字母、数字、特殊字符或键盘上的其他按键。例如，'a'表示按下'A'键，'ctrl'表示按下Ctrl键。你还可以同时按下多个键，例如'ctrlleft'表示按下左Ctrl键。

args: 可选的附加参数，用于指定按键时的一些额外操作。这些参数可以是字符串或整数。一些可能的参数包括：

interval: 按键之间的时间间隔，以秒为单位。指定按下键之后等待的时间，默认为0。

logScreenshot: 如果为True，将在按键之前记录当前屏幕的截图。默认为False。

pause: 在按下键之前的延迟时间，以秒为单位。默认为pyautogui.PAUSE的值。

示例：

import pyautogui

# 按下'A'键

pyautogui.keyDown('a')

# 可选：等待一段时间

pyautogui.sleep(1)

# 松开'A'键

pyautogui.keyUp('a')

5、pyautogui.keyUp(key, args...)

用于模拟释放键盘上的一个键。

参数：

args: 可选的附加参数，用于指定释放键时的一些额外操作。这些参数可以是字符串或整数。一些可能的参数包括：

interval: 释放键之间的时间间隔，以秒为单位。指定释放键之后等待的时间，默认为0。

logScreenshot: 如果为True，将在释放键之前记录当前屏幕的截图。默认为False。

pause: 在释放键之前的延迟时间，以秒为单位。默认为pyautogui.PAUSE的值。

示例：

import pyautogui

# 按住ctrl键

pyautogui.keyDown('ctrl')

# 按下并松开一次a键

pyautogui.press('a')

# 松开ctrl键

pyautogui.keyUp('ctrl') # 相当于Ctrl+A全选的作用

——hold(pyautogui.KEYBOARD_KEYS)

为了使按住某个键更加方便，hold()函数可以用作传递某个pyautogui.KEYBOARD_KEYS中的某个键作为上下文管理器，在with上下文管理器中这个键将被一直按住。

例：

import pyautogui

with pyautogui.hold('shift'):

    # 相当于按Shift+左箭头3次

    pyautogui.press(['left'],presses=3)

6、pyautogui.hotkey(key1, key2, ..., keys, interval=0.0, logScreenshot=False, pause=None)

用于模拟按下多个按键组合，类似于按下快捷键的操作。

参数：

key1, key2, ..., keys: 要按下的按键，可以是字符串表示的单个按键，也可以是多个按键组合。例如，'ctrl'、'c'、'v'，或者像('ctrl', 'c')表示同时按下Ctrl和C键。

interval: 按键之间的时间间隔，以秒为单位。指定按下每个按键之间的时间间隔，默认为0。

logScreenshot: 如果为True，将在按键之前记录当前屏幕的截图。默认为False。

pause: 在按下每个按键之前的延迟时间，以秒为单位。如果指定了，它将覆盖模块级别的全局PAUSE变量。默认为pyautogui.PAUSE的值。

示例：

import pyautogui

pyautogui.click()

# 选中所有内容

pyautogui.hotkey('ctrl', 'a')

# 复制

pyautogui.hotkey('ctrl', 'c')

# 因前面全选了内容，此处要再次单击获取光标，否则复制一次的内容覆盖了之前的内容，就看不出有复制成功

pyautogui.click()

# 粘贴

pyautogui.hotkey('ctrl', 'v')

也可以用keyDown()和keyUp()来组合模拟组合快捷键功能。

——pyautogui.KEYBOARD_KEYS

['\t', '\n', '\r', ' ', '!', '"', '#', '$', '%', '&', "'", '(', ')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', ':', ';', '<', '=', '>', '?', '@', '[', '\\', ']', '^', '_', '`', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '{', '|', '}', '~', 'accept', 'add', 'alt', 'altleft', 'altright', 'apps', 'backspace', 'browserback', 'browserfavorites', 'browserforward', 'browserhome', 'browserrefresh', 'browsersearch', 'browserstop', 'capslock', 'clear', 'convert', 'ctrl', 'ctrlleft', 'ctrlright', 'decimal', 'del', 'delete', 'divide', 'down', 'end', 'enter', 'esc', 'escape', 'execute', 'f1', 'f10', 'f11', 'f12', 'f13', 'f14', 'f15', 'f16', 'f17', 'f18', 'f19', 'f2', 'f20', 'f21', 'f22', 'f23', 'f24', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'final', 'fn', 'hanguel', 'hangul', 'hanja', 'help', 'home', 'insert', 'junja', 'kana', 'kanji', 'launchapp1', 'launchapp2', 'launchmail', 'launchmediaselect', 'left', 'modechange', 'multiply', 'nexttrack', 'nonconvert', 'num0', 'num1', 'num2', 'num3', 'num4', 'num5', 'num6', 'num7', 'num8', 'num9', 'numlock', 'pagedown', 'pageup', 'pause', 'pgdn', 'pgup', 'playpause', 'prevtrack', 'print', 'printscreen', 'prntscrn', 'prtsc', 'prtscr', 'return', 'right', 'scrolllock', 'select', 'separator', 'shift', 'shiftleft', 'shiftright', 'sleep', 'space', 'stop', 'subtract', 'tab', 'up', 'volumedown', 'volumemute', 'volumeup', 'win', 'winleft', 'winright', 'yen', 'command', 'option', 'optionleft', 'optionright']

共194个KEYBOARD_KEYS键盘常量。

消息弹窗函数

PyAutoGUI通过Tkinter实现了4种纯Python的消息弹窗函数，和JavaScript类似。

1、pyautogui.alert(text='', title='', button='OK')

显示一个简单的带文字和OK按钮的消息弹窗。用户点击后返回button的文字。

参数说明：

text（可选）: 弹出框中显示的文本内容，可以是字符串。默认为空字符串。

title（可选）: 弹出框的标题，可以是字符串。默认为空字符串。

button（可选）: 弹出框上显示的按钮文本，可以是字符串。默认为 'OK'。

示例：

import pyautogui

# 显示一个简单的弹出框

pyautogui.alert('这是一个示例弹出框', '提示', '好的')

2、pyautogui.confirm(text='', title='', buttons=['OK', 'Cancel'])

显示一个简单的带文字、OK和Cancel按钮的消息弹窗，用户点击后返回被点击button的文字，支持自定义数字、文字的列表。

参数说明：

text（可选）: 确认框中显示的文本内容，可以是字符串。默认为空字符串。

title（可选）: 确认框的标题，可以是字符串。默认为空字符串。

buttons（可选）: 确认框上显示的按钮文本，是一个列表，其中包含要显示的按钮文本。默认为 ['OK', 'Cancel']。

示例：

import pyautogui

# 显示一个简单的弹出框

pyautogui.confirm('这是一个示例弹出框', '提示', range(10)

3、pyautogui.prompt(text='', title='', default='')

可以输入的消息弹窗，带OK和Cancel按钮。用户点击OK按钮返回输入的文字，点击Cancel按钮返回None。

参数说明：

text（可选）: 提示框中显示的文本内容，可以是字符串。默认为空字符串。

title（可选）: 提示框的标题，可以是字符串。默认为空字符串。

default（可选）: 提示框中文本输入框的默认值，可以是字符串。默认为空字符串。

示例：

import pyautogui

# 获取用户输入的用户名

username = pyautogui.prompt('请输入用户名：', '输入', default='')

# 根据用户输入进行相应的操作

if username:

    print('用户输入的用户名是:', username)

else:

    print('用户点击了取消按钮')

4、pyautogui.password(text='', title='', default='', mask='*')

样式同prompt()，用于输入密码，消息用*表示。带OK和Cancel按钮。用户点击OK按钮返回输入的文字，点击Cancel按钮返回None。

参数说明：

text（可选）: 提示框中显示的文本内容，可以是字符串。默认为空字符串。

title（可选）: 提示框的标题，可以是字符串。默认为空字符串。

default（可选）: 提示框中密码输入框的默认值，可以是字符串。默认为空字符串。

mask（可选）: 用于掩盖用户输入的掩码字符，可以是单个字符。默认为 '*'。

示例：

import pyautogui

# 获取用户输入的密码

password = pyautogui.password('请输入密码：', '输入', mask='A')

# 根据用户输入进行相应的操作

if password:

    print('用户输入的密码是:', password)

else:

    print('用户点击了取消按钮')

截屏函数

PyAutoGUI可以截屏并保存为图片文件，然后定位这些截屏在屏幕上的位置。与sikuli类似，把屏幕上的按键截取下来，然后定位，就可以执行点击等操作了。

截屏功能需要安装Pillow模块。OS X用screencapture命令，是系统自带的。Linux用户用scrot命令，可以通过sudo apt-get install scrot安装。

1、pyautogui.screenshot(region=(left, top, width, height))

用于获取屏幕上的截图并可保存为文件。

参数说明：

region（可选）: 指定截图的区域，是一个包含左上角坐标 (left, top) 和宽度高度 (width, height) 的元组。默认为整个屏幕的区域。

返回值：

返回一个 PIL.Image 对象，可以使用 PIL（Python Imaging Library）中的方法进行进一步的处理和保存。

示例1：screenshot()函数会返回Image对象（参考Pillow或PIL模块文档），也可以设置文件名

import pyautogui

img1= pyautogui.screenshot()

img2= pyautogui.screenshot('img2.png')

示例2：在一个$1920 \times 1080$的屏幕上，screenshot()函数要消耗100微秒——不快也不慢。

如果你不需要截取整个屏幕，还有一个可选的region参数。你可以把截取区域的左上角XY坐标值和宽度、高度传入截取。

import pyautogui

img1= pyautogui.screenshot()

img2= pyautogui.screenshot('img.png',region=(0,0,300,300))

示例3：

import pyautogui

# 获取整个屏幕的截图

screenshot = pyautogui.screenshot()

# 保存截图

screenshot.save('screenshot.png')

# 获取屏幕某个区域的截图

region_screenshot = pyautogui.screenshot(region=(100, 100, 300, 300))

# 显示截图

region_screenshot.show()

定位函数

从0.9.41版本开始若未找到指定图片的定位，会引发ImageNotFoundException异常而不是返回None。

你可以用图片来定位你在屏幕上看到的东西，如查找屏幕上是否打开了计算器：

如果你不知道计算器按钮在屏幕上的具体坐标，就无法调用moveTo()和click()函数来操作它。不管计算器位于屏幕哪个位置，或随时会变换位置，只要你有计算器按钮的图片就可以实时定位它的位置，如按钮7：

你可以调用locateOnScreen('calc7key.png')函数来定位它的坐标。函数会返回一个包含4个整数的元组。这个元组可以传递给center()函数以获取在这个区域中心点的x和y坐标，如果屏幕中无法定位到这个图片则会引发图片未找到异常。

1、pyautogui.locateOnScreen(image, grayscale=False, confidence=0.8)

用于在屏幕上定位给定图像的第一个匹配项的位置。

这对于图形用户界面（GUI）自动化特别有用，因为它允许脚本通过识别屏幕上的图像来找到并点击按钮、图标或其他界面元素。

参数：

image (str 或 PIL.Image.Image)：要查找的图像的文件路径或 Pillow (PIL) Image 对象。

grayscale (bool, 可选)：是否将图像转换为灰度格式以加速查找过程。默认为 False，即使用彩色图像进行匹配。

confidence (float, 可选)：图像匹配的置信度水平，范围从 0.0 到 1.0。只有 OpenCV 安装后才可用，并且 image 参数必须是一个文件路径（不能是 PIL Image 对象）。此参数允许函数在找到匹配项时具有一定的容错性。默认为 0.8，但如果未安装 OpenCV，则忽略此参数。

PS：务必使用confidence参数，否则很难匹配到指定图像的位置

使用 confidence 参数，还需要安装 opencv-python 库。你可以使用 pip 来安装它们：

pip install pyautogui opencv-python

返回值：

如果找到匹配项，则返回一个四元素的元组，表示匹配图像区域的左上角坐标 (x, y) 和其宽度和高度 (width, height)。

如果未找到匹配项，则返回 None。或者直接报错：pyautogui.ImageNotFoundException

示例：

import pyautogui  

  

# 假设你有一个名为 'button.png' 的图像文件，你想要在屏幕上找到它  

# PS：务必使用confidence参数，否则很难匹配到指定图像的位置

location = pyautogui.locateOnScreen('user.png',confidence=0.8)  

  

if location is not None:  

    # 如果找到了图像，获取其坐标，并可以执行点击等操作  

    x, y, width, height = location  

    print(f'找到图像，位置：{x}, {y}, 宽度：{width}, 高度：{height}')  

    pyautogui.click(x + width // 2, y + height // 2)  # 点击图像的中心  

else:  

    print('未在屏幕上找到图像')

——pyautogui.center(coords)

 获取一个坐标区域中中心点x和y的坐标。

参数说明：

coords：一个包含4个整数的元组（可以先用locateOnScreen()获取指定图片的位置区域，再传递给center()获取区域的中心点）

例：

import pyautogui

# 输出计算器按钮7的中心点x和y坐标

print(pyautogui.center(pyautogui.locateOnScreen('calc7key.png',confidence=0.8)))

# Point(x=275, y=647)

2、locateCenterOnScreen(image, grayscale=False, confidence=0.8)

用于找到屏幕上特定图像的中心位置。

参数：

image (str 或 PIL.Image.Image)：要查找的图像的文件路径或 Pillow (PIL) Image 对象。

grayscale (bool, 可选)：是否将图像转换为灰度格式以加速查找过程。默认为 False，即使用彩色图像进行匹配。

confidence (float, 可选)：图像匹配的置信度水平，范围从 0.0 到 1.0。只有 OpenCV 安装后才可用，并且 image 参数必须是一个文件路径（不能是 PIL Image 对象）。此参数允许函数在找到匹配项时具有一定的容错性。默认为 0.8，但如果未安装 OpenCV，则忽略此参数。

返回值：

如果找到匹配项，则返回一个四元素的元组，表示匹配图像区域的左上角坐标 (x, y) 和其宽度和高度 (width, height)。

如果未找到匹配项，则返回 None。或者直接报错：pyautogui.ImageNotFoundException

示例：

import pyautogui

location = pyautogui.locateCenterOnScreen('111.png', grayscale=False, confidence=0.8)

print(location)

输出：

Point(x=115, y=233)

3、locateAllOnScreen(image, grayscale=False, confidence=0.8)

用于在给定的图像或屏幕上找到所有匹配的子图像或目标。

参数：

image (str 或 PIL.Image.Image)：要查找的图像的文件路径或 Pillow (PIL) Image 对象。

grayscale (bool, 可选)：是否将图像转换为灰度格式以加速查找过程。默认为 False，即使用彩色图像进行匹配。

confidence (float, 可选)：图像匹配的置信度水平，范围从 0.0 到 1.0。只有 OpenCV 安装后才可用，并且 image 参数必须是一个文件路径（不能是 PIL Image 对象）。此参数允许函数在找到匹配项时具有一定的容错性。默认为 0.8，但如果未安装 OpenCV，则忽略此参数。

返回值：

locations：一个列表，包含所有屏幕中找到的图像的位置（例如，坐标）。如果没有找到任何匹配项，则可能返回一个空列表。

示例：

import pyautogui

for i in pyautogui.locateAllOnScreen('111.png', grayscale=False,confidence=0.8):

    print(i)

输出：

Box(left=92, top=207, width=46, height=52) # print(i.left) = 92

Box(left=168, top=207, width=46, height=52)

Box(left=168, top=308, width=46, height=52)

Box(left=92, top=409, width=46, height=52)

Box(left=522, top=589, width=46, height=52)

Box(left=602, top=589, width=46, height=52)

4、locate(needleImage, haystackImage, grayscale=False)

返回找到的第一个截图Image对象在haystackImage里面的坐标(left, top, width, height)，如果没找到引发ImageNotFoundException异常。

参数：

needleImage：要定位的图片路径（如计算器按钮7）

haystackImage：被定位的图片路径（如屏幕截图）

示例：

import pyautogui

# 保存当前屏幕截图

pyautogui.screenshot('current.png')

# 查找按钮7在前面保存截图中的位置

print(pyautogui.locate('7.png','current.png'))

5、locateAll(needleImage, haystackImage, grayscale=False)

返回找到的所有相同截图Image对象在haystackImage里面的坐标(left, top, width, height)的生成器

locate all函数都可以用for循环或list()列表输出：

>>> import pyautogui

>>> for pos in pyautogui.locateAllOnScreen('someButton.png')

...   print(pos)...(1101, 252, 50, 50)(59, 481, 50, 50)(1395, 640, 50, 50)(1838, 676, 50, 50)

>>> list(pyautogui.locateAllOnScreen('someButton.png'))[(1101, 252, 50, 50), (59, 481, 50, 50), (1395, 640, 50, 50), (1838, 676, 50, 50)]

这些'locate'函数都很消耗资源，他们会用4秒来运行。最好的办法是指定一个区域参数，以避免在整个屏幕中搜索。

>>> import pyautogui

>>> pyautogui.locateOnScreen('someButton.png', region=(0,0, 300, 400))

灰度值匹配

可以把grayscale参数设置为True来加速定位（大约提升30%），默认为False。这种去色（desaturate）方法可以加速定位，但是也可能导致假阳性（false-positive）匹配：

>>> import pyautogui

>>> button7location = pyautogui.locateOnScreen('calc7key.png', grayscale=True)

>>> button7location(1416, 562, 50, 41)

像素匹配

要获取截屏某个位置像素点的RGB颜色值，可以用Image对象的getpixel()方法：

>>> import pyautogui

>>> im = pyautogui.screenshot()

>>> im.getpixel((100, 200))

(130, 135, 144)

也可以用PyAutoGUI的pixel()函数，是之前调用的包装：

>>> import pyautogui

>>> pix = pyautogui.pixel(100, 200)

>>> pix

RGB(red=130, green=135, blue=144)

>>> pix[0]

130

>>> pix.red

130

1、pyautogui.pixel(x, y)

用于获取屏幕上的指定像素点的颜色值。

参数说明：

x 和 y：表示像素点的坐标。

示例：

import pyautogui

rgb = pyautogui.pixel(100,200)

print(rgb) # (239, 235, 239)

如果你只是要检验一下指定位置像素点的RGB颜色值，可以用pixelMatchesColor()函数，把X、Y和RGB元组值穿入即可：

2、pyautogui.pixelMatchesColor(x, y, expected_red, expected_green, expected_blue[, tolerance])

用于检查屏幕上的指定像素点的RGB颜色是否与指定的RGB颜色值匹配。

参数说明：

x 和 y：表示像素点的坐标。

expected_red、expected_green 和 expected_blue：分别表示期望的像素点的 RGB 颜色值中的红色、绿色和蓝色分量。

tolerance（可选参数）：一个整数，表示颜色匹配的容差范围。默认值为 0。

示例：

import pyautogui

isMatch = pyautogui.pixelMatchesColor(100, 200, (130, 135, 144),tolerance=0.9)

print(isMatch) # False

四、其他函数

1、pyautogui.sleep(seconds)

        休眠秒数，同time.sleep()函数功能。

到此Python中PyAutoGUI的帮助文档就介绍完了。