查找元素

如何阅读界面转储,选择持续有效的选择器,处理重复元素、列表、图标、网页和没有元素的界面,以及排查匹配不到的选择器。

本页为译文。如与英文版不一致,以英文版为准。 English

Droidline 脚本的大部分工作,是告诉它要操作哪一个元素。本指南介绍如何像 Droidline 那样查看界面,以及如何选择在应用更新或手机语言改变之后仍然有效的选择器。

先看再写

在手机上打开要操作的界面,然后保存 Droidline 看到的内容:

droidline dump screen.json
droidline screenshot screen.png
d.dump("screen.json")
d.screenshot("screen.png")
await d.dump("screen.json");
await d.screenshot("screen.png");
await d.DumpAsync("screen.json");
await d.ScreenshotAsync("screen.png");

在编辑器中打开 screen.json,与截图并排放置,搜索你在手机上看到的文字。每个匹配项都是一个元素;它周围的字段就是你可以使用的选项:

{
  "text": "Keep me signed in",
  "id": "dev.droidline.demo:id/auto_login",
  "desc": "",
  "class": "android.widget.CheckBox",
  "bounds": [60, 860, 1020, 960],
  "clickable": true,
  "checkable": true,
  "checked": false
}

bounds 是以像素为单位的 [left, top, right, bottom]。如果不确定文件中的哪个元素对应屏幕上的哪个东西,就把 bounds 和截图对照:上面这个元素横向从 60 到 1020 像素,纵向从 860 到 960 像素。

如果更想用鼠标指着选,droidline inspect 会把截图和元素树并排显示,并给出带代码的选择器建议。这是可选功能,上面的 dump 就已足够。

挑选选择器

选择器由一个字段和一个值组成。按以下顺序挑选:

  1. id,如果元素有的话。 ID 由应用的开发者设定,不会随手机语言变化,大多数在应用更新后也不变。只写 :id/ 之后的部分:("id", "auto_login")。
  2. text,用于按钮和标签。 在代码中一目了然,但它是显示出来的文字,所以会随语言变化,有时也会随更新变化。如果文字中有会变化的部分,例如数量,就使用 textContains:("textContains", "unread") 能匹配“3 unread”。
  3. desc,用于图标。 图标按钮通常不显示文字,但带有供屏幕阅读器使用的描述,例如“Search”或“More options”。
  4. 查询,当一个字段匹配到多个元素时。 组合多个条件,或借助旁边的元素来指定。见一个字段不够时。
  5. class 加 nth,作为最后的手段。 “第三个复选框”这种写法,布局一变就会失效。
d.touch("id", "auto_login")
d.touch("text", "Log in")
d.touch("textContains", "unread")
d.touch("desc", "More options")
d.touch("class", "android.widget.CheckBox", nth=2)
await d.touch("id", "auto_login");
await d.touch("text", "Log in");
await d.touch("textContains", "unread");
await d.touch("desc", "More options");
await d.touch("class", "android.widget.CheckBox", { nth: 2 });
await d.TouchAsync("id", "auto_login");
await d.TouchAsync("text", "Log in");
await d.TouchAsync("textContains", "unread");
await d.TouchAsync("desc", "More options");
await d.TouchAsync("class", "android.widget.CheckBox", nth: 2);
droidline touch id auto_login
droidline touch text "Log in"
droidline touch textContains unread
droidline touch desc "More options"
droidline touch class android.widget.CheckBox --nth 2

无法直接点击的文字

文字常常是一个更大的可点击行中的标签,而标签本身不可点击。你不需要去找那一行:touch 会发现标签不接受点击,转而点击离它最近的可点击父元素。发生这种情况时,回复中会有 "via": "parent"。

如果标签位于你要操作的控件旁边,例如设置行末尾的开关,点击标签所在的行通常就能切换开关。如果不行,就用 {"class": "android.widget.Switch", "row": {"text": "Wi-Fi"}} 这样的查询直接选中开关本身。

多个元素匹配

有多个元素匹配时,命令作用于按屏幕顺序的第一个。用 nth 选择其他元素(从 0 开始计数),用 count 查看一共有几个:

print(d.count("text", "Delete"))          # 3
d.touch("text", "Delete", nth=1)          # 第二个
console.log(await d.count("text", "Delete"));   // 3
await d.touch("text", "Delete", { nth: 1 });    // 第二个
Console.WriteLine(await d.CountAsync("text", "Delete"));   // 3
await d.TouchAsync("text", "Delete", nth: 1);              // 第二个
droidline count text Delete
droidline touch text Delete --nth 1

一个字段不够时

选择器也可以写成包含多个条件的对象,称为查询。把查询放在字段名的位置,并省略值。所有条件必须在同一个元素上成立:

d.touch({"class": "android.widget.Button", "text": "确定"})
d.checked({"class": "android.widget.Switch", "row": {"text": "Wi-Fi"}})
d.input({"editable": True, "below": {"text": "邮箱"}}, "knife")
await d.touch({ class: "android.widget.Button", text: "确定" });
await d.checked({ class: "android.widget.Switch", row: { text: "Wi-Fi" } });
await d.input({ editable: true, below: { text: "邮箱" } }, "knife");
await d.TouchAsync(new { @class = "android.widget.Button", text = "确定" });
await d.CheckedAsync(new { @class = "android.widget.Switch", row = new { text = "Wi-Fi" } });
await d.InputAsync(new { editable = true, below = new { text = "邮箱" } }, "knife");
droidline touch '{"class":"android.widget.Button","text":"确定"}'
droidline checked '{"class":"android.widget.Switch","row":{"text":"Wi-Fi"}}'
droidline input '{"editable":true,"below":{"text":"邮箱"}}' knife

查询中可以包含:

  • 字段:text、textContains、textMatches、id、desc、descContains、descMatches、class 和 package,匹配方式与上面的选择器相同。
  • 状态:clickable、checkable、checked、enabled、editable、selected、scrollable 等 dump 中的值,设为 true 或 false。其中 visible 对列表留在屏幕边缘之外的项为 false。不加 "visible": true 时匹配不看这个值;如果要自己点击元素的坐标,最好先加上。
  • 关系,每个关系里再放一个查询:
    • has:某个后代元素匹配。包含文字“Wi-Fi”的可点击行写作 {"clickable": true, "has": {"text": "Wi-Fi"}}。
    • inside:某个祖先元素匹配。
    • row:同一列表行中有元素匹配。用旁边的标签找到开关或复选框,就靠它。
    • below、above、left_of、right_of:位于第一个匹配元素的那一侧。结果按由近到远排列,所以 nth=0 是最近的那个。

所有接受选择器的命令都接受查询:touch、exists、wait、get_text、count、scroll_to、which 等。所有键都列在命令参考中。

正则表达式

textMatches 和 descMatches 接受正则表达式,它必须与整个文字匹配,而不是其中一部分:

d.touch("textMatches", r"删除 \d+ 项")
d.wait("descMatches", "下载(中|完成).*")
await d.touch("textMatches", "删除 \\d+ 项");
await d.wait("descMatches", "下载(中|完成).*");
await d.TouchAsync("textMatches", "删除 \\d+ 项");
await d.WaitAsync("descMatches", "下载(中|完成).*");
droidline touch textMatches '删除 \d+ 项'
droidline wait descMatches '下载(中|完成).*'

如果文字的一部分就足够,使用更易读的 textContains。

留住元素再使用

find 像 touch 一样等待元素出现,但不点击,而是把元素作为对象返回。find_all 立即返回当前屏幕上所有匹配的元素。你可以读取字段、让它执行操作,或在它里面继续查找:

for row in d.find_all("id", "message_row"):
    sender = row.find("id", "sender").text
    if sender == "妈妈":
        row.click()
        break

field = d.find({"editable": True})
print(field.bounds, field["enabled"])
field.input("你好")
for (const row of await d.findAll("id", "message_row")) {
  const sender = (await row.find("id", "sender")).text;
  if (sender === "妈妈") {
    await row.click();
    break;
  }
}

const field = await d.find({ editable: true });
console.log(field.bounds, field.node.enabled);
await field.input("你好");
foreach (var row in await d.FindAllAsync("id", "message_row"))
{
    var sender = (await row.FindAsync("id", "sender")).Text;
    if (sender == "妈妈")
    {
        await row.ClickAsync();
        break;
    }
}

var field = await d.FindAsync(new { editable = true });
Console.WriteLine($"{field.Bounds} {field["enabled"]}");
await field.InputAsync("你好");

元素是找到那一刻屏幕的快照。它执行操作时按精确的位置和 class 重新查找,所以屏幕滚动或变化之后会以 NOT_FOUND 失败。需要当前的值时调用 refresh(),或者重新 find。在 CLI 中,droidline find 和 droidline find_all 以 JSON 输出相同的字段。

列表中更靠下的元素

dump 只包含屏幕上显示的内容,某些列表会多包含一点,多出的这些项为 "visible": false。更靠下的元素此时还不存在,所以 touch 找不到它。scroll_to 会一直滑动,直到它进入屏幕,然后你再操作它:

d.scroll_to("text", "Developer options")
d.touch("text", "Developer options")

d.scroll_to("text", "Airplane mode", direction="up")   # 向上查找
await d.scrollTo("text", "Developer options");
await d.touch("text", "Developer options");

await d.scrollTo("text", "Airplane mode", { direction: "up" });   // 向上查找
await d.ScrollToAsync("text", "Developer options");
await d.TouchAsync("text", "Developer options");

await d.ScrollToAsync("text", "Airplane mode", direction: "up");   // 向上查找
droidline scroll_to text "Developer options"
droidline touch text "Developer options"

滑动 20 次(max_swipes)后仍未找到,它就会放弃,并返回 NOT_FOUND。

弹窗、键盘和状态栏

默认情况下,dump 显示的是前台应用。弹出的对话框属于这个应用,会正常显示。要同时看到键盘、状态栏或由 Android 自己绘制的权限对话框等系统窗口,请要求获取所有窗口:

d.dump("all.json", all_windows=True)
await d.dump("all.json", { all_windows: true });
await d.DumpAsync("all.json", allWindows: true);
droidline dump all.json --all_windows

对于可能出现也可能不出现的弹窗,用条件检查,不要等待它们:

if d.exists("text", "Allow"):
    d.touch("text", "Allow")
if (await d.exists("text", "Allow")) await d.touch("text", "Allow");
if (await d.ExistsAsync("text", "Allow"))
    await d.TouchAsync("text", "Allow");
[ "$(droidline exists text Allow)" = "true" ] && droidline touch text Allow

网页和 WebView

Chrome 中的页面和应用内的 WebView 通常也会把链接、按钮和表单字段作为元素提供出来,可见文字在 text 中,有时表单字段的标签在 desc 中。像对待其他界面一样对待它们:先 dump。如果网页在 dump 中没有任何有用的内容,说明它是在 canvas 上绘制的;请按下一节的说明使用坐标。

没有元素的界面

游戏、视频播放器、地图和一些自行绘制界面的应用完全不提供元素:dump 中只有一个大方框。在这些界面上,使用坐标和颜色:

d.tap(540, 1650)                         # 点击一个点,单位为屏幕像素
print(d.color(540, 1650))                # "#FF6B21":该点的颜色
d.swipe(540, 1600, 540, 400, 300)        # 在 300 毫秒内从一个点拖到另一个点
await d.tap(540, 1650);
console.log(await d.color(540, 1650));
await d.swipe(540, 1600, 540, 400, 300);
await d.TapAsync(540, 1650);
Console.WriteLine(await d.ColorAsync(540, 1650));
await d.SwipeAsync(540, 1600, 540, 400, 300);
droidline tap 540 1650
droidline color 540 1650
droidline swipe 540 1600 540 400 300

从原始尺寸的截图中获取坐标:图片中的像素位置就是手机的屏幕像素。color 让你在点击之前确认按钮已经出现,例如等到某个像素变成预期的颜色。

选择器匹配不到时

touch 在超时后以 NOT_FOUND 失败,并告诉你当时屏幕上显示的是什么:

NOT_FOUND: Could not find text 'Log in' within 10s. Current screen: com.example / .MainActivity

按顺序检查以下几点:

  1. 是你预期的界面吗? 消息中写明了当时显示的应用和界面。弹窗、广告或很慢的网络可能把你带到了别处。
  2. 文字完全正确吗? 匹配要求完全一致,包括大小写、空格和标点。从 dump 中复制值,不要手动输入。如果其中一部分会变化,使用 textContains。
  3. 它已经在屏幕上了吗? 如果在屏幕下方还没显示出来,使用 scroll_to。如果还在加载,传入更长的 timeout。
  4. 它在另一个窗口中吗? 使用 all_windows=True 进行 dump。
  5. 这个界面有元素吗? 如果 dump 中只有一个大方框,就使用坐标,或在截图中查找图片或文字。