统一选择器

返回文档中心 · 动作目录

选择器只负责从当前页面中找出匹配节点，不等待、不点击，也不默认选择第一个。

1. 当前字段 [已实现]

{
  "resourceId": "com.example.target:id/continue_button",
  "text": "继续",
  "contentDescription": "继续操作",
  "className": "android.widget.Button",
  "clickable": true
}

规则：

已提供字段按 AND 组合。
resourceId、text、contentDescription 和 className 精确匹配。
clickable 匹配节点自身状态。
至少提供一个字段。
当前只遍历 rootInActiveWindow。

2. 简单扩展 [提案]

{
  "resourceId": "com.example.target:id/continue_button",
  "text": {
    "source": "TEXT_OR_DESCRIPTION",
    "mode": "CONTAINS_ANY",
    "values": ["继续", "下一步"]
  },
  "state": {
    "visible": true,
    "enabled": true
  },
  "region": {
    "minXRatio": 0.0,
    "maxXRatio": 1.0,
    "minYRatio": 0.5,
    "maxYRatio": 1.0
  }
}

首批扩展建议只支持：

文字来源：TEXT、CONTENT_DESCRIPTION、TEXT_OR_DESCRIPTION。
文字模式：EXACT、CONTAINS、CONTAINS_ANY。
状态：visible、enabled、clickable、selected、checked、focused、scrollable。
区域：屏幕比例矩形，节点中心点落在区域内即匹配。

visible 统一定义为 isVisibleToUser == true，且屏幕边界非空并与屏幕相交。

正则、祖先/后代关系、逻辑嵌套和多窗口查询等到出现明确场景时再增加。

3. 候选数量

不同动作决定如何使用匹配结果：

WAIT v1 要求恰好一个。
CLICK、INPUT 和 BACK 以外的单目标动作默认要求一个。
EXTRACT 可以显式声明 ONE 或 MANY。
多个候选时不默认选第一个。

CLICK 可以把文字节点向上解析为最近的可点击祖先；这是 CLICK 的规则，不改变基础选择器结果。

4. 查询接口

建议公共接口保持简单：

fun findAll(
    root: AccessibilityNodeInfo,
    selector: NodeSelector,
): List<UiNodeRef>

每次轮询读取新 root。同一轮查询结束后释放不再使用的节点；动作完成后不保留旧节点引用。

5. 实现顺序

保留 v1 精确匹配。
增加可见、启用和边界检查。
增加 TEXT_OR_DESCRIPTION 和 CONTAINS_ANY。
增加屏幕比例区域。
只有实际任务需要时再扩展复杂选择器。

2.5 KiB Raw Permalink Blame History