uiautomator2

uiautomator2

此技能可帮助你使用 uiautomator2 Python 包提供的 u2cli 自动化 Android 设备。

常规用法

• 使用 u2cli <command> [args] 运行命令。
• 连接了多台 Android 设备时，使用 u2cli -s <serial> <command> [args]。
• 以下示例仅展示 <command> [args]；运行时请在前面加上 u2cli。

命令

设备命令

• dump-hierarchy：转储当前 UI 层级，以便分析和选择元素。优先使用默认输出，因为 u2cli 会在返回前对其进行压缩，这通常已足够，并且适用于 grep，例如 dump-hierarchy | grep -i "keyword"。只有在明确需要完整的未压缩层级时，才使用 dump-hierarchy --raw。
• screenshot：截取当前屏幕并保存到本地文件。输出为截图的文件路径和大小。例如：screenshot /tmp/screenshot.jpg。
• app-current：获取当前前台应用的包名和 activity。
• device-info：显示设备信息。
• window-size：显示屏幕窗口大小。
• shell：在设备上运行 shell 命令。使用 --timeout <seconds> 设置命令超时时间。例如：shell "pm list packages"。

应用命令

• app-start：按包名启动应用。选项：--activity <activity>、--wait、--stop。例如：app-start com.android.settings --activity .Settings --wait。
• app-list：列出已安装的包。
• app-stop：按包名停止应用。例如：app-stop com.example.app。
• app-install：安装 APK。例如：app-install ./app-debug.apk。
• app-uninstall：按包名卸载应用。例如：app-uninstall com.example.app。
• app-clear：按包名清除应用数据。例如：app-clear com.example.app。

输入命令

• press：按下硬件键或 Android 按键。例如：press home。
• send-keys：在当前焦点输入框中输入文本。默认会在输入前清除内容；使用 --no-clear 可保留现有文本。例如：send-keys "hello world"。
• clear-text：清除当前焦点输入框中的文本。例如：clear-text。
• click：点击坐标或选择器。坐标格式为 X Y，也可以使用 --text、--resource-id、--description 和 --class-name 等选择器选项。例如：click 500 1200；比例示例：click 0.5 0.5；选择器示例：click --text Gmail。
• double-click：双击坐标。选项：--duration <seconds>，用于设置两次点击之间的延迟。此命令需要 X Y；不支持选择器选项。例如：double-click 500 1200；比例示例：double-click 0.5 0.5。
• long-click：长按坐标或选择器。选项：--duration <seconds> 和 --timeout <seconds>。例如：long-click 500 1200；比例示例：long-click 0.5 0.5；选择器示例：long-click --text Gmail。
• swipe：从一个坐标滑动到另一个坐标。参数为 FX FY TX TY。选项：--duration <seconds>、--steps <number>、--scale <number>。例如：swipe 500 1800 500 400 --duration 0.3；比例示例：swipe 0.5 0.8 0.5 0.2 --duration 0.3。
• drag：从一个坐标拖动到另一个坐标。参数为 SX SY EX EY。选项：--duration <seconds>。例如：drag 300 1200 800 1200；比例示例：drag 0.3 0.5 0.8 0.5。

选择器命令

• exists：检查选择器是否存在。选项：--timeout <seconds>，以及选择器选项。示例：exists --text Gmail --timeout 3。
• wait：等待选择器出现。使用 --gone 可等待其消失。选项：--timeout <seconds>，以及选择器选项。示例：wait --text Gmail --timeout 10；等待其消失的示例：wait --text Loading --gone --timeout 10。
• scroll：滚动选择器。选项：--direction vert|horiz、--action forward|backward|toEnd|toBeginning、--max-swipes <number>、--to-text <text>，以及选择器选项。示例：scroll --scrollable --direction vert --action forward；滚动到文本的示例：scroll --scrollable --to-text Settings。

系统界面命令

• open-notification：打开通知栏。
• open-quick-settings：打开快捷设置。
• open-url：在设备上打开 URL。示例：open-url https://example.com。

常用选择器选项

在基于选择器的命令中使用这些选项，例如 click、long-click、exists、wait 和 scroll。

• 文本选择器：--text <text>、--text-contains <text>、--text-matches <regex>、--text-starts-with <text>。
• 描述选择器：--description <text>、--description-contains <text>。
• 资源和类选择器：--resource-id <id>、--class-name <class>、--package <package>。
• 状态选择器：--selected、--focused、--enabled、--scrollable、--clickable、--checked、--checkable。
• 位置选择器：--instance <number>、--index <number>。
• 子级选择器：使用 --child KEY=VALUE [KEY=VALUE ...]，或使用 --child-text、--child-resource-id、--child-class-name、--child-clickable 和 --child-index 等子级专用选项来追加子级选择器层级。示例：click --resource-id com.example:id/list --child text=OK。