Android 輸入

在 UI 元素上執行手勢和按鍵事件,與 Android 應用程式互動。

用量

android input [-h] [--device=PARAM]

選項

  • --device=PARAM - 裝置序號或模擬器 ID (由「adb devices」回報)。
  • -h,--help:顯示指定指令的說明訊息。

android 選項:

  • --sdk=PARAM - Android SDK 的路徑。
  • -v,--verbose:啟用詳細輸出功能,以便排解問題。
  • -V,--version:輸出版本資訊並結束。

子指令

  • key:按下硬體按鈕、導覽鍵或 Android 按鍵碼。
  • scroll:捲動容器元素,直到目標元素出現為止 (選用)。
  • swipe:從符合選取器的 UI 元素,朝指定方向滑動。
  • tap:輕觸與選取器相符的 UI 元素。
  • text:在與選取器相符的 UI 元素中輸入文字。

說明

android input 會在已連結的 Android 裝置或模擬器上執行使用者互動和硬體輸入。

AI 代理和測試指令碼可搭配使用 android input 與 android layout 或 android screen,探索 UI 元素,並透過手勢或按鍵與這些元素互動。

UI 元素選取器

大多數 input 子指令都會使用選取器運算式指定 UI 元素。選取器是以半形逗號分隔的 key=value 或 key:value 組合清單,用於指定目標元素必須滿足的屬性。請用單引號括住選取器,以免殼層解讀空格、半形逗號或特殊字元。

選取器會與應用程式的即時無障礙節點階層進行比對:

  • 字串屬性:根據預設,系統會比對不區分大小寫的子字串 (例如 text=submit 會比對「Submit order」)。傳遞 *,即可比對該屬性值不為空白的任何元素。在值前後加上斜線,即可將其視為區分大小寫的規則運算式,比對值的任何部分 (例如 text=/^Submit$/)。在結尾斜線後方加上 i 標記,即可將其視為不區分大小寫的規則運算式 (例如 text=/^submit$/i)。規則運算式中的半形逗號不會分割選取器。如要比對開頭為 / 的常值文字,請使用 text=/^\/help/ 等規則運算式。
    • text (同義詞:txt):元素上顯示的文字。
    • id (同義詞:res):檢視表資源 ID 名稱 (例如 id=submit_button 或完整資源名稱 com.example.app:id/submit_button)。
    • class (同義詞:clazz、cls、clz):元素類別名稱或簡易類別名稱 (例如 class=Button 或 android.widget.Button)。
    • desc (同義詞:content):無障礙內容說明。
  • 互動屬性:比對布林值 (true 或 false)。
    • clickable (同義詞:click):元素是否可點選。
    • checkable:元素是否可勾選或切換。
    • scrollable (同義詞:scroll):元素是否為可捲動的容器。
    • focusable:元素是否可以接收焦點。
    • longclickable (同義詞:longclick):元素是否支援長按。
  • 狀態屬性:比對為布林值 (true 或 false)。
    • checked:元素目前是否已勾選。
    • focused:元素目前是否為焦點。
    • selected:目前是否已選取元素。

比對行為 (--match)

如果選取器與畫面上的多個元素相符:

  • --match=single (預設):失敗並顯示錯誤,列出所有相符元素,確保互動不會觸發錯誤的 UI 元件。
  • --match=first:與 UI 階層中遇到的第一個相符元素互動。

可用的手勢和指令

  • tap <target>:點選目標元素的中心。
  • text <string> <target>:清除現有文字,並在目標元素中輸入 <string>。傳遞 --submit,在輸入後傳送 Enter/OK 按鍵事件。
  • scroll <target>:朝指定方向 (--dir=up|down|left|right) 捲動容器元素。使用 --until=<selector> 可持續捲動,直到出現相符元素。
  • swipe <target>:從 <target> 開始朝某個方向 (--dir=up|down|left|right) 執行滑動手勢,可選擇 --distance (螢幕比例) 和 --speed (每秒像素)。
  • key <key>:傳送硬體按鈕或按鍵事件 (例如 back、home、recents、power、volume-up、volume-down、enter、tab、esc 或整數 Android 鍵碼)。支援修飾符旗標 --shift、--alt 和 --ctrl。

指定目標裝置 (--device)

如果連結多部裝置或模擬器,請傳遞 --device=<serial-number> (由 adb devices 回報),將輸入事件導向特定裝置。

範例

根據按鈕顯示的文字輕觸按鈕:

android input tap 'text=Submit'

輕觸符合多個屬性的元素:

android input tap 'id=submit_btn,class=Button,clickable=true'

如果有多個相符項目,請輕觸第一個相符元素:

android input tap --match=first 'class=android.widget.TextView'

在輸入欄位中輸入文字並提交:

android input text 'user@example.com' 'id=email_input' --submit

向下捲動容器,直到項目出現:

android input scroll 'id=recycler_view' --dir=down --until='text=Settings'

在資訊卡元素上向左滑動:

android input swipe 'id=card_view' --dir=left

按下裝置的返回按鈕:

android input key back