# 统一选择器

> [返回文档中心](README.md) · [动作目录](actions/README.md)

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

## 1. 当前字段 **[已实现]**

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

规则：

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

## 2. 简单扩展 **[提案]**

~~~json
{
  "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. 查询接口

建议公共接口保持简单：

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

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

## 5. 实现顺序

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