初期設定と安全機構

PyAutoGUIを使用した自動化スクリプトを作成する際、予期せぬ動作や無限ループによるシステムロックを防ぐために、事前に安全機構と操作のタイミングを制御する設定を行うことが重要です。

import pyautogui

# フェイルセーフ機能の有効化（デフォルトでTrue）
# マウスカーソルを画面の左上隅に移動させると、KeyboardInterruptを発生させてプログラムを強制停止します
pyautogui.FAILSAFE = True

# 操作間のポーズ（待機時間）設定
# 各GUI操作の後に指定秒数だけ待機します。UIの描画遅延や読み込み待ちに対応するために有用です
pyautogui.PAUSE = 0.5

# 座標の妥当性検証
# 指定したX, Y座標が現在のスクリーン解像度内に収まっているかを確認します
target_x, target_y = 800, 600
if pyautogui.onScreen(target_x, target_y):
    print("指定座標は有効な画面範囲内です。")

マウス制御と座標操作

マウスの移動、クリック、ドラッグ、スクロールなどの操作をプログラムから精密に制御できます。絶対座標指定と相対座標指定の両方がサポートされています。

# スクリーン解像度と現在のカーソル位置の取得
screen_width, screen_height = pyautogui.size()
current_x, current_y = pyautogui.position()

# 絶対座標への移動と相対移動
pyautogui.moveTo(x=150, y=250, duration=0.8) # 0.8秒かけて指定座標へ移動
pyautogui.move(x_offset=100, y_offset=0, duration=0.3) # 現在の位置から右方向に100ピクセル移動

# クリック操作のバリエーション
pyautogui.click(x=200, y=300, clicks=2, interval=0.1, button='left') # 左ボタンでダブルクリック
pyautogui.rightClick(x=400, y=500) # 右クリック
pyautogui.middleClick() # 現在のカーソル位置で中クリック

# ドラッグ＆ドロップ操作
pyautogui.mouseDown(button='left')
pyautogui.moveTo(x=600, y=600, duration=0.5)
pyautogui.mouseUp(button='left')

# dragToを使用したより簡潔なドラッグ操作
pyautogui.dragTo(x=700, y=700, duration=0.5, button='left')

# マウスホイールのスクロール
# 正の値で上方向、負の値で下方向にスクロールします
pyautogui.scroll(clicks=-5, x=300, y=300) # 指定座標に移動してから下に5ノッチスクロール

キーボード入力とショートカット

文字列の自動入力や、単一キーの押下、修飾キーを組み合わせたショートカット操作を実現できます。日本語の入力にはクリップボード経由のアプローチが推奨されます。

# 文字列の自動入力（ASCII文字のみ対応。タイピング速度の調整が可能）
pyautogui.write('Hello PyAutoGUI', interval=0.05)

# 単一キーのタップと連続入力
pyautogui.press('enter')
pyautogui.press(['tab', 'tab', 'enter']) # リストを使用して複数キーを順に押下

# 修飾キーとの組み合わせ（ホットキー）
pyautogui.hotkey('ctrl', 'c') # コピー
pyautogui.hotkey('ctrl', 'v') # ペースト
pyautogui.hotkey('alt', 'f4') # ウィンドウを閉じる

# キーの長押し状態の制御（KeyDown / KeyUp）
pyautogui.keyDown('shift')
pyautogui.press(['left', 'left', 'left']) # Shiftを押しながら左キーでテキストを範囲選択
pyautogui.keyUp('shift')

モーダルダイアログの生成

ユーザーへの確認や入力促しを行うための、OSネイティブなモーダルダイアログを簡単に生成できます。戻り値としてユーザーのアクションを取得可能です。

# 情報通知（アラート）ダイアログ
response_alert = pyautogui.alert(
    text='バッチ処理が正常に完了しました。',
    title='完了通知',
    button='OK'
)

# 確認ダイアログ（複数ボタン）
user_choice = pyautogui.confirm(
    text='この操作を取り消すことはできません。本当に実行しますか？',
    title='警告',
    buttons=['実行', 'キャンセル']
)
if user_choice == '実行':
    print("処理を開始します...")

# テキスト入力ダイアログ
user_input = pyautogui.prompt(
    text='保存先のファイル名を入力してください:',
    title='ファイル保存',
    default='output_data.csv'
)

# パスワード入力（マスク文字付き）
secret_key = pyautogui.password(
    text='API認証キーを入力してください:',
    title='セキュリティ',
    mask='*'
)

スクリーンキャプチャと画像認識

画面のスクリーンショット取得、特定ピクセルの色判定、そしてテンプレートマッチングを用いた画面上の画像検索（UI要素の特定）が可能です。

from PIL import Image

# 特定領域のスクリーンショット取得
# (left, top, width, height) のタプルで範囲を指定します
capture_region = (100, 100, 800, 600)
screenshot_img = pyautogui.screenshot(region=capture_region)
screenshot_img.save('partial_capture.png')

# 特定座標のピクセル色取得
rgb_color = pyautogui.pixel(x=400, y=300)
print(f"対象ピクセルのRGB値: {rgb_color}")

# 色の一致確認（許容誤差あり）
is_match = pyautogui.pixelMatchesColor(
    x=400, y=300,
    expectedRGB=(255, 255, 255),
    tolerance=15 # RGBそれぞれの値の許容誤差
)

# 画面上の画像検索（テンプレートマッチング）
target_image_path = 'submit_button.png'

# 最初に見つかった領域のバウンディングボックスを取得
# confidenceパラメータでマッチングの厳密さを調整できます（OpenCVが必要）
box_location = pyautogui.locateOnScreen(target_image_path, confidence=0.8)
if box_location:
    # 見つかった領域の中心座標を計算してクリック
    center_x, center_y = pyautogui.center(box_location)
    pyautogui.click(center_x, center_y)
    print(f"ボタンを clicks しました: ({center_x}, {center_y})")

# 画面上のすべての一致箇所を取得
all_matches = pyautogui.locateAllOnScreen(target_image_path, confidence=0.8)
for box in all_matches:
    print(f"発見された要素の座標: {box}")