メインコンテンツへスキップ

🖱️ PyAutoGUI マウス操作

📖 はじめに

PyAutoGUIでは、マウスカーソルの移動やクリック、ドラッグなど、人が行うマウス操作をPythonから実行できます。

GUI自動化では最も基本となる機能であり、多くの処理は「マウスを移動する」「クリックする」という操作の組み合わせで実現できます。

この記事では、PyAutoGUIで利用できる代表的なマウス操作を紹介します。

📦 PyAutoGUIの読み込み

最初にライブラリをインポートします。

import pyautogui

📍 現在のマウス座標を取得する

現在のマウスカーソルの位置は position() で取得できます。

import pyautogui

x, y = pyautogui.position()

print(x, y)

実行すると、現在のマウス座標が表示されます。

例えば

640 360

のように表示されます。

画面左上が原点（0,0）です。右へ行くほどX座標が大きくなり、下へ行くほどY座標が大きくなります。

🎯 マウスを指定座標へ移動する

指定した座標へ移動するには moveTo() を使用します。

import pyautogui

pyautogui.moveTo(500, 300)

この例では座標 (500, 300) へカーソルが移動します。

⏱️ 移動時間を指定する

移動時間を指定すると、人が操作しているように滑らかに移動します。

pyautogui.moveTo(500, 300, duration=1)

この例では約1秒かけて移動します。

デバッグ中は移動時間を指定すると、カーソルの動きを目で確認しやすくなります。

➡️ 現在位置から相対移動する

現在位置から移動したい場合は move() を使用します。

pyautogui.move(100, 0)

右へ100ピクセル移動します。

pyautogui.move(0, 100)

下へ100ピクセル移動します。

負の値を指定すると反対方向へ移動します。

🖱️ 左クリック

左クリックは click() を使用します。

pyautogui.click()

現在位置でクリックします。

座標を指定することもできます。

pyautogui.click(500, 300)

この場合は指定座標へ移動してクリックします。

🖱️🖱️ ダブルクリック

ダブルクリックは doubleClick() を使用します。

pyautogui.doubleClick()

座標指定も可能です。

pyautogui.doubleClick(500, 300)

🖱️ 右クリック

右クリックは rightClick() を使用します。

pyautogui.rightClick()

🖱️ 中クリック

ホイールボタンのクリックは middleClick() を使用します。

pyautogui.middleClick()

👆 マウスボタンを押す・離す

クリックではなく、「押す」「離す」を個別に制御することもできます。

ボタンを押します。

pyautogui.mouseDown()

ボタンを離します。

pyautogui.mouseUp()

これらはドラッグ処理などで利用されます。

📦 ドラッグする

指定座標までドラッグします。

pyautogui.dragTo(700, 400, duration=1)

現在位置から相対移動する場合は drag() を使用します。

pyautogui.drag(200, 0, duration=1)

ドラッグは左ボタン以外にも右ボタンや中央ボタンで実行できます。用途に応じてボタンを指定できます。

🎡 スクロール

マウスホイールを回転させるには scroll() を使用します。

上へスクロールします。

pyautogui.scroll(500)

下へスクロールします。

pyautogui.scroll(-500)

スクロール量は環境によって体感速度が異なる場合があります。

🎬 イージング（滑らかな移動）

moveTo() や dragTo() では、移動方法を変更できます。

例えば、ゆっくり加速して止まる動きを指定できます。

pyautogui.moveTo(
    800,
    400,
    duration=1,
    tween=pyautogui.easeInOutQuad
)

主なイージングには次のようなものがあります。

イージング 動き
linear 一定速度
easeInQuad 徐々に加速
easeOutQuad 徐々に減速
easeInOutQuad 加速後に減速
easeInBounce 跳ねるような動き
easeOutBounce 着地時に跳ねるような動き

GUI自動化では通常はlinearまたはeaseInOutQuadが利用されます。

⚙️ 共通設定

PAUSE

すべての操作後に待機時間を設定できます。

pyautogui.PAUSE = 0.5

この例では、各操作の後に0.5秒待機します。

FAILSAFE

フェイルセーフは既定で有効です。

print(pyautogui.FAILSAFE)

通常は

True

と表示されます。

FAILSAFEは無効化しないことを推奨します。 マウスを画面左上へ移動することで処理を中断できる、安全のための重要な機能です。

💡 実践例

次の例では、

  1. 指定位置へ移動
  2. クリック
  3. 少し待機
  4. 下へスクロール

を実行します。

import pyautogui
import time

pyautogui.moveTo(800, 300, duration=1)
pyautogui.click()

time.sleep(1)

pyautogui.scroll(-800)

GUI自動化では、このような小さな操作を組み合わせて一連の処理を構築します。

最初は「移動」「クリック」「スクロール」の3つだけ覚えても、多くの自動化を作成できます。

⚠️ マウス操作で注意すること

マウス操作は画面上の座標を基準に実行されます。

そのため、

  • ウィンドウの位置が変わる
  • 解像度が変わる
  • ディスプレイ構成が変わる
  • 表示倍率（DPI）が変わる

と、期待した位置をクリックできなくなることがあります。

座標を固定するよりも、画像認識機能と組み合わせることで、より安定した自動化を実現できます。

クリック位置を十分確認せずに自動実行すると、重要なファイルの削除や意図しないボタン操作につながる可能性があります。 初めて実行するスクリプトは、テスト環境で十分に確認してください。

📝 まとめ

PyAutoGUIでは、マウスに関する基本操作を簡単に実行できます。

代表的な機能は次のとおりです。

  • position()：現在位置の取得
  • moveTo()：指定座標へ移動
  • move()：相対移動
  • click()：左クリック
  • doubleClick()：ダブルクリック
  • rightClick()：右クリック
  • dragTo()：指定位置までドラッグ
  • scroll()：ホイール操作

これらを組み合わせることで、多くのGUI操作を自動化できます。また、実際の業務では画像認識機能と併用することで、画面レイアウトの変化にも対応しやすいスクリプトを作成できます。

上に戻る