速查表

这是使用PyAutoGUI的快速入门参考指南。PyAutoGUI是一个跨平台的GUI自动化模块，支持Python 2和3版本。您可以通过控制鼠标键盘以及执行基本图像识别功能，来实现计算机任务的自动化操作。

本页示例中的所有关键字参数均为可选参数。

>>> import pyautogui

PyAutoGUI 支持 Windows/Mac/Linux 系统以及 Python 2 和 3 版本。可通过 pip install pyautogui 从 PyPI 安装。

通用函数

>>> pyautogui.position()  # current mouse x and y
(968, 56)
>>> pyautogui.size()  # current screen resolution width and height
(1920, 1080)
>>> pyautogui.onScreen(x, y)  # True if x & y are within the screen.
True

安全防护机制

在每次PyAutoGUI调用后设置2.5秒的暂停：

>>> import pyautogui
>>> pyautogui.PAUSE = 2.5

当故障保护模式设为True时，将鼠标移动到左上角会触发pyautogui.FailSafeException异常，该异常可终止程序运行：

>>> import pyautogui
>>> pyautogui.FAILSAFE = True

鼠标功能

屏幕坐标系的XY原点(0,0)位于屏幕左上角。X轴向右递增，Y轴向下递增。

>>> pyautogui.moveTo(x, y, duration=num_seconds)  # move mouse to XY coordinates over num_second seconds
>>> pyautogui.moveRel(xOffset, yOffset, duration=num_seconds)  # move mouse relative to its current position

如果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

调用click()仅会在鼠标当前位置用左键单击一次，但关键字参数可以改变此行为：

>>> pyautogui.click(x=moveToX, y=moveToY, clicks=num_of_clicks, interval=secs_between_clicks, button='left')

button关键字参数可以是'left'、'middle'或'right'。

所有点击操作都可以通过click()完成，但以下函数的存在是为了提高代码可读性。关键字参数是可选的：

>>> pyautogui.rightClick(x=moveToX, y=moveToY)
>>> pyautogui.middleClick(x=moveToX, y=moveToY)
>>> pyautogui.doubleClick(x=moveToX, y=moveToY)
>>> pyautogui.tripleClick(x=moveToX, y=moveToY)

正向滚动会向上滚动，负向滚动会向下滚动：

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

可以分别调用单独的按钮按下和释放事件：

>>> pyautogui.mouseDown(x=moveToX, y=moveToY, button='left')
>>> pyautogui.mouseUp(x=moveToX, y=moveToY, button='left')

键盘功能

按键操作会发送到调用函数时键盘光标所在的位置。

>>> pyautogui.typewrite('Hello world!\n', interval=secs_between_keys)  # useful for entering text, newline is Enter

也可以传递一个按键名称列表：

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

完整的按键名称列表位于pyautogui.KEYBOARD_KEYS中。

键盘快捷键如Ctrl-S或Ctrl-Shift-1可以通过将按键名称列表传递给hotkey()来实现：

>>> pyautogui.hotkey('ctrl', 'c')  # ctrl-c to copy
>>> pyautogui.hotkey('ctrl', 'v')  # ctrl-v to paste

可以分别调用单独的按钮按下和释放事件：

>>> pyautogui.keyDown(key_name)
>>> pyautogui.keyUp(key_name)

消息框功能

如果您需要暂停程序直到用户点击确认按钮，或者想向用户显示某些信息，消息框函数的命名方式与JavaScript类似：

>>> pyautogui.alert('This displays some text with an OK button.')
>>> pyautogui.confirm('This displays text and has an OK and Cancel button.')
'OK'
>>> pyautogui.prompt('This lets the user type in a string and press OK.')
'This is what I typed in.'

如果用户点击了取消按钮，prompt()函数将返回None。

屏幕截图功能

PyAutoGUI使用Pillow/PIL处理图像相关数据。

在Linux系统上，您需要运行sudo apt-get install scrot才能使用截图功能。

>>> pyautogui.screenshot()  # returns a Pillow/PIL Image object
<PIL.Image.Image image mode=RGB size=1920x1080 at 0x24C3EF0>
>>> pyautogui.screenshot('foo.png')  # returns a Pillow/PIL Image object, and saves it to a file
<PIL.Image.Image image mode=RGB size=1920x1080 at 0x31AA198>

如果您有一个想要点击的图像文件，可以使用locateOnScreen()在屏幕上找到它。

>>> pyautogui.locateOnScreen('looksLikeThis.png')  # returns (left, top, width, height) of first place it is found
(863, 417, 70, 13)

locateAllOnScreen() 函数将返回一个生成器，包含屏幕上所有匹配位置：

>>> for i in pyautogui.locateAllOnScreen('looksLikeThis.png')
...
...
(863, 117, 70, 13)
(623, 137, 70, 13)
(853, 577, 70, 13)
(883, 617, 70, 13)
(973, 657, 70, 13)
(933, 877, 70, 13)

>>> list(pyautogui.locateAllOnScreen('looksLikeThis.png'))
[(863, 117, 70, 13), (623, 137, 70, 13), (853, 577, 70, 13), (883, 617, 70, 13), (973, 657, 70, 13), (933, 877, 70, 13)]

locateCenterOnScreen() 函数仅返回屏幕上找到图像中心位置的XY坐标：

>>> pyautogui.locateCenterOnScreen('looksLikeThis.png')  # returns center x and y
(898, 423)

如果在屏幕上找不到图像，这些函数将返回None。

注意：定位函数运行较慢，可能需要1-2秒的完整时间。