Android 输入

通过在界面元素上执行手势和按键事件,与 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 - 从与选择器匹配的界面元素向给定方向滑动。
  • tap - 点按与选择器匹配的界面元素。
  • text - 在与选择器匹配的界面元素中输入文本。

说明

android input 会在连接的 Android 设备或模拟器上执行用户互动和硬件输入。

AI 智能体和测试脚本可以将 android input 与 android layout 或 android screen 结合使用,以发现界面元素并使用手势或按键与其交互。

界面元素选择器

大多数 input 子命令都使用选择器表达式来定位界面元素。选择器是以逗号分隔列表形式的 key=value 或 key:value 对,用于指定目标元素必须满足的属性。请将选择器括在单引号中,以防止 shell 解释空格、英文逗号或特殊字符。

选择器会与应用的实时无障碍节点层次结构进行匹配:

  • 字符串属性:默认情况下,作为不区分大小写的子字符串进行匹配(例如,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(默认):失败并显示错误,同时列出所有匹配的元素,确保互动不会触发错误的界面组件。
  • --match=first:与界面层次结构中遇到的第一个匹配元素进行交互。

可用的手势和指令

  • 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