آموزش کامل PyAutoGUI در پایتون: اتوماسیون موش و کیبورد از صفر تا صد

خودکارسازی کارهای تکراری رایانه‌ای یکی از سریع‌ترین راه‌ها برای صرفه‌جویی در زمان و کاهش خطای انسانی است. اگر برنامه‌ای که با آن کار می‌کنید API اختصاصی ندارد، کتابخانه PyAutoGUI در پایتون به شما کنترل کامل ماوس و کیبورد را می‌دهد تا هر عملیاتی که انسان انجام می‌دهد را بازسازی کنید. در این راهنمای جامع، تمام ابزارها، قابلیت‌ها و چالش‌های واقعی استفاده از PyAutoGUI را بررسی خواهیم کرد.

PyAutoGUI چیست و چگونه کار می‌کند؟

PyAutoGUI یک کتابخانه پایتون برای اتوماسیون رابط کاربری گرافیکی (GUI) است که کنترل ماوس و کیبورد را بر عهده می‌گیرد. این ماژول با ارسال مستقیم دستورات به سیستم‌عامل، ورودی‌های فیزیکی کاربر را شبیه‌سازی می‌کند و روی تمام محیط‌های Windows، macOS و Linux کار می‌کند.

برخلاف ابزارهایی مانند Selenium که صرفاً محدود به مرورگر هستند، PyAutoGUI متکی به برنامه خاصی نیست. شما می‌توانید با آن نرم‌افزارهای دسکتاپ، فایل‌های اکسل، برنامه‌های گرافیکی یا حتی بازی‌ها را مدیریت کنید. اگر در کنار این ابزار به دنبال کدهای کاربردی برای توسعه بخش‌های مختلف هستید، مطالعه تکه‌کدهای کاربردی پایتون می‌تواند سرعت توسعه شما را دوچندان کند.

نصب و پیش‌نیازهای سیستم‌عامل‌های مختلف

برای نصب PyAutoGUI کافی است از مدیریت پکیج pip استفاده کنید. اما در برخی سیستم‌عامل‌ها نیاز به نصب وابستگی‌های جانبی وجود دارد.

1. ویندوز (Windows): دستور زیر به تنهایی تمام پکیج‌های لازم را نصب می‌کند:

pip install pyautogui

2. لینوکس (Linux): نیازمند ابزار scrot یا python3-tk برای اسکرین‌شات و عملکرد درست دیالوگ‌ها است:

sudo apt-get install python3-tk python3-dev
pip install pyautogui

3. مک (macOS): پس از نصب، باید در بخش System Preferences > Security & Privacy > Accessibility به ترمینال یا IDE خود دسترسی کنترل سیستم را بدهید.

مکانیزم‌های امنیتی حیاتی (Fail-Safe و Pause)

کنترل خودکار ماوس می‌تواند در صورت بروز خطا در کد، کنترلی خارج از دسترسی ایجاد کند و مانع بستن اسکریپت شود. PyAutoGUI دو ویژگی امنیتی برای جلوگیری از این مشکل دارد.

• قابلیت Fail-Safe: به‌صورت پیش‌فرض فعال است. اگر نشانگر ماوس را سریعاً به منتهی‌الیه گوشه بالا-چپ مانیتور (مختصات 0,0) ببرید، اسکریپت فوراً متوقف شده و خطای pyautogui.FailSafeException رخ می‌دهد.
• مکث بین دستورات (Pause): می‌توانید برای تمامی دستورات یک وقفه زمانی تعیین کنید تا سیستم فرصت پردازش داشته باشد.

import pyautogui

# ایجاد وقفه 0.5 ثانیه‌ای پس از هر دستور PyAutoGUI
pyautogui.PAUSE = 0.5

# فعال بودن مکانیزم خروج اضطراری (پیش‌فرض True است)
pyautogui.FAILSAFE = True

مدیریت و کنترل کامل ماوس (حرکت، کلیک، اسکرول)

برای کنترل ماوس ابتدا باید سیستم مختصات صفحه را بشناسید. نقطه (0,0) گوشه سمت چپ-بالا است. مقدار X با حرکت به سمت راست و مقدار Y با حرکت به سمت پایین افزایش می‌یابد.

۱. دریافت ابعاد صفحه و موقعیت ماوس

# دریافت رزولوشن صفحه
width, height = pyautogui.size()
print(f"رزولوشن صفحه: {width}x{height}")

# دریافت موقعیت فعلی نشانگر ماوس
current_x, current_y = pyautogui.position()
print(f"موقعیت ماوس: X={current_x}, Y={current_y}")

۲. حرکت دادن ماوس

برای جابه‌جایی ماوس دو روش اصلی وجود دارد: حرکت مستقیم به مختصات مطلق (moveTo) و حرکت به نسبت موقعیت فعلی (move).

# حرکت به نقطه X=500 و Y=500 در مدت زمان 2 ثانیه
pyautogui.moveTo(500, 500, duration=2)

# حرکت نسبی: 100 پیکسل به راست و 50 پیکسل به پایین نسبت به موقعیت فعلی
pyautogui.move(100, 50, duration=1)

۳. انجام کلیک، دابل کلیک و درگ کردن

# کلیک چپ ساده در موقعیت فعلی
pyautogui.click()

# کلیک در مختصات مشخص با دکمه راست
pyautogui.click(x=200, y=300, button='right')

# دابل کلیک چپ
pyautogui.doubleClick(x=200, y=300)

# درگ کردن (بستن و کشیدن) آیتم از موقعیت فعلی به نقطه جدید
pyautogui.dragTo(800, 600, duration=1.5, button='left')

# اسکرول کردن (عدد مثبت به بالا، عدد منفی به پایین)
pyautogui.scroll(-500)

مدیریت کیبورد، تایپ و کلیدهای ترکیبی

PyAutoGUI امکان تایپ متن و فشردن کلیدهای خاص سیستم (مثل Enter، Tab، Ctrl) را فراهم می‌آورد.

تایپ متن و فشردن کلیدها

# تایپ یک رشته متن با فاصله زمانی 0.1 ثانیه بین هر کاراکتر
pyautogui.write('Hello World!', interval=0.1)

# فشردن یک کلید خاص
pyautogui.press('enter')

# فشردن متوالی چند کلید
pyautogui.press(['left', 'left', 'delete', 'backspace'])

میانبرهای ترکیبی (Hotkeys)

برای فشردن هم‌زمان چند کلید (مثلاً Ctrl+C یا Alt+Tab) می‌توانید از تابع hotkey استفاده کنید:

# شبیه‌سازی کپی کردن (Ctrl + C)
pyautogui.hotkey('ctrl', 'c')

# شبیه‌سازی تعویض پنجره (Alt + Tab)
pyautogui.hotkey('alt', 'tab')

بینایی ماشین و پردازش تصویر (Locate On Screen)

یکی از قدرتمندترین ویژگی‌های PyAutoGUI، توانایی پیدا کردن عناصر روی مانیتور بر اساس یک عکس کوچک است. اگر نمی‌دانید یک دکمه دقیقا در چه مختصاتی قرار دارد، از الگوی تصویری آن استفاده کنید.

# پیدا کردن مرکز دکمه ارسال در صفحه
location = pyautogui.locateCenterOnScreen('submit_button.png', confidence=0.8)

if location is not None:
    print(f"دکمه در مختصات {location} پیدا شد.")
    pyautogui.click(location)
else:
    print("دکمه پیدا نشد!")

نکته فنی: برای استفاده از پارامتر confidence (درصد شباهت تصویر)، باید کتابخانه opencv-python را نیز در محیط پایتون خود نصب کرده باشید (pip install opencv-python).

ایجاد دیالوگ‌باکس‌ها و پیام‌های هشدار

PyAutoGUI ماژول‌های ساده‌ای برای نمایش پنجره‌های پاپ‌آپ دارد تا بتوانید در طول اجرای اسکریپت با کاربر تعامل داشته باشید یا تاییدیه بگیرید.

# پیام هشدار ساده
pyautogui.alert(text='عملیات اتوماسیون آغاز می‌شود.', title='هشدار', button='باشه')

# پنجره تایید دو گزینه‌ای
response = pyautogui.confirm(text='آیا مایل به ادامه هستید؟', title='تایید', buttons=['بله', 'خیر'])

# گرفتن ورودی متنی از کاربر
user_input = pyautogui.prompt(text='نام کاربری خود را وارد کنید:', title='ورودی')

مقایسه PyAutoGUI با سایر ابزارهای اتوماسیون

برای انتخاب درست ابزار، باید ویژگی‌های PyAutoGUI را با گزینه‌های مشابه مقایسه کنید:

سناریوی کاربردی: ساخت یک اسکریپت اتوماسیون اداری

در این سناریو، یک برنامه فرضی می‌نویسیم که برنامه Notepad را باز کرده، متنی را درون آن درج می‌کند و سپس فایل را ذخیره می‌سازد. این الگوی اجرایی برای کارهای پیچیده‌تر، اتوماسیون ارسال گزارش و حتی سناریوهایی مانند ساخت ربات ایتا با پایتون که نیازمند تعامل با نسخه‌های دسکتاپی برنامه‌ها هستند نیز کاربرد دارد.

import pyautogui
import time

# 1. باز کردن منوی Run در ویندوز
pyautogui.hotkey('win', 'r')
time.sleep(1)

# 2. تایپ عبارت notepad و باز کردن آن
pyautogui.write('notepad')
pyautogui.press('enter')
time.sleep(1.5)

# 3. تایپ متن گزارش
pyautogui.write('Automated Report Generated Successfully!nDate: 2026-03-30', interval=0.05)

# 4. میانبر ذخیره فایل (Ctrl + S)
pyautogui.hotkey('ctrl', 's')
time.sleep(1)

# 5. نام‌گذاری فایل و ذخیره
pyautogui.write('report_output.txt')
pyautogui.press('enter')

همچنین اگر در پروژه‌های اتوماسیون تحلیل داده فعالیت می‌کنید و قصد دارید نتایج را به‌صورت دیداری ذخیره کنید، استفاده از راهنمای رسم نمودار با داده‌ها در کنار این اسکریپت‌ها خروجی کاملی ارائه می‌دهد.

عیب‌یابی سریع و رفع خطاهای رایج

پرسش‌های متداول