前言
MaaFW Python接口說明
Controller模組

Controller模組

MaaFramework Controller 模組說明文檔

本文檔介紹 MaaFramework 中 Controller 模組的核心接口、參數用途以及相關輔助功能，方便使用者快速了解並使用這些接口進行設備/系統操作模擬。

目錄

基本概念

  • Controller 模組：負責將底層設備或系統操作（如模擬點擊、滑動、按鍵、文本輸入、應用啟動/停止、觸摸、截屏等）封裝成統一的接口。
  • 任務(Job)：每個操作接口都會返回一個 Job 或 JobWithResult 對象，用以監控操作狀態、等待操作完成並（在需要時）獲取操作結果。

主要接口與參數說明

連接相關

  • post_connection()
    • 用途：建立設備或系統的連接。
    • 參數：無。
    • 返回：返回一個 Job 對象，表示連接操作的異步任務。

點擊與滑動操作

  • post_click(x, y)

    • 用途：在屏幕上指定的位置模擬一次點擊操作。
    • 參數：
      • x, y：點擊時的屏幕座標。
    • 返回：返回一個 Job 對象。

  • post_swipe(x1, y1, x2, y2, duration)

    • 用途：模擬從起始點 (x1, y1) 到結束點 (x2, y2) 的滑動（拖拽）操作。
    • 參數：
      • x1, y1：起點座標
      • x2, y2：終點座標
      • duration：滑動過程持續時間（通常以毫秒為單位）
    • 返回：返回一個 Job 對象。

鍵盤與文本輸入

  • post_press_key(key)

    • 用途：模擬按下一個鍵。
    • 參數：
      • key：代表按鍵的整型鍵值。
    • 返回：返回一個 Job 對象。

  • post_input_text(text)

    • 用途：模擬在設備上輸入文本。
    • 參數：
      • text：要輸入的字符串。
    • 返回：返回一個 Job 對象。

應用啟動與停止

  • post_start_app(intent)

    • 用途：啟動指定的應用。
    • 參數：
      • intent：啟動應用所需的指令字符串（例如包名或啟動參數）。
    • 返回：返回一個 Job 對象。

  • post_stop_app(intent)

    • 用途：停止或關閉指定的應用。
    • 參數：
      • intent：用於識別需要停止的應用。
    • 返回：返回一個 Job 對象。

觸摸操作

  • post_touch_down(x, y, contact=0, pressure=1)

    • 用途：模擬手指觸碰屏幕時的“按下”操作。
    • 參數：
      • x, y：觸碰位置的座標。
      • contact：觸點索引（對於多點觸控，默認為 0）。
      • pressure：按壓力度（默認為 1）。
    • 返回：返回一個 Job 對象。

  • post_touch_move(x, y, contact=0, pressure=1)

    • 用途：模擬手指在屏幕上滑動時的移動操作。
    • 參數：同上，指定新的目標座標、觸點索引及按壓力度。
    • 返回：返回一個 Job 對象。

  • post_touch_up(contact=0)

    • 用途：模擬手指離開屏幕時的“抬起”操作。
    • 參數：
      • contact：觸點索引（默認為 0）。
    • 返回：返回一個 Job 對象。

截屏操作

  • post_screencap()
    • 用途：截取當前屏幕圖像。
    • 參數：無。
    • 返回：返回一個 JobWithResult 對象，操作完成後可獲取截屏圖像（通常以 NumPy 數組形式）。

附加屬性與設置

  • cached_image
    • 用途：獲取控制器緩存的最新圖像（返回一個 NumPy 數組）。
  • connected
    • 用途：布林值，表示是否已與設備建立連接。
  • uuid
    • 用途：獲取當前控制器的全局唯一標識符，用於調試與追蹤。
  • set_screenshot_target_long_side(long_side)
    • 用途：設定截屏時目標圖像的長邊像素值，幫助控制縮放比例。
    • 參數：
      • long_side：整數，表示目標長邊尺寸。
  • set_screenshot_target_short_side(short_side)
    • 用途：設定截屏時目標圖像的短邊像素值。
    • 參數：
      • short_side：整數。
  • set_screenshot_use_raw_size(enable)
    • 用途：設置是否使用設備的原始分辨率進行截屏（不進行縮放）。
    • 參數：
      • enable：布林值，True 表示使用原始尺寸。

內部輔助方法

  • _status(maaid)
    • 用途：內部方法，通過任務 id 查詢當前操作狀態。
  • _wait(maaid)
    • 用途：內部方法，用於等待指定任務完成。
  • get_screencap()
    • 用途：內部方法，用於獲取截屏圖像（實際返回 cached_image）。
  • _gen_ctrl_job(ctrlid)
    • 用途：根據控制操作返回的 id 生成一個 Job 對象，以便後續狀態查詢與等待操作。

API 初始化與子類擴展

  • API 屬性初始化
    Controller 模組通過靜態方法 _set_api_properties() 設定底層 C 調用接口的返回值類型與參數類型，保證調用時數據類型正確，這部分通常由框架自動處理。

  • 子類擴展
    通過在 __all__ 列表中定義的具體控制器類型（如 AdbController、DbgController、Win32Controller、CustomController），可以根據不同平台或用途進行擴展和自定義操作。

結語

Controller 模組統一封裝了各種常見的設備操作，如點擊、滑動、輸入、截屏等。通過返回 Job 或 JobWithResult 對象，使用者可以方便地監控任務狀態並獲取操作結果。本文件旨在幫助使用者快速了解並上手這些接口。

以上內容根據 MaaFramework 的源碼和設計文檔整理，供使用者參考。

Resource模組