# SCROLL **[提案]**

> [返回动作目录](README.md) · [统一选择器](../selector.md) · [执行与结果](../execution.md)

SCROLL 是统一滚动动作。当前代码尚未实现。

## 1. 滚动到目标

~~~json
{
  "id": "scroll-to-target",
  "action": "SCROLL",
  "packageName": "com.example.target",
  "mode": "TO_TARGET",
  "target": {
    "text": "目标选项"
  },
  "container": {
    "resourceId": "com.example.target:id/list"
  },
  "direction": "DOWN",
  "maxAttempts": 8,
  "timeoutMs": 10000
}
~~~

目标出现且可见时成功；每次滚动后重新读取页面。

## 2. 按方向滚动

~~~json
{
  "id": "scroll-down",
  "action": "SCROLL",
  "packageName": "com.example.target",
  "mode": "DIRECTION",
  "container": {
    "resourceId": "com.example.target:id/list"
  },
  "direction": "DOWN",
  "amount": "PAGE",
  "maxAttempts": 1,
  "timeoutMs": 3000
}
~~~

首批字段：

- `mode`：`TO_TARGET`、`DIRECTION`、`TO_EDGE`。
- `direction`：`UP`、`DOWN`、`LEFT`、`RIGHT`。
- `amount`：`SMALL`、`PAGE`。
- `maxAttempts`：有限正整数。
- `container`：可选；省略时要求页面中只有一个可滚动容器。

## 3. 执行规则

1. 找到唯一、可见且可滚动的容器。
2. TO_TARGET 先检查目标是否已经可见。
3. 优先调用节点滚动动作；不支持时可使用容器内手势。
4. 每次滚动后重新读取容器和目标。
5. 达到目标、页面边缘、`maxAttempts` 或总超时时停止。

容器内容连续两次不变可以视为到达边缘。滚动次数和持续时间始终受步骤 `timeoutMs` 限制。

## 4. 结果码

- `OK`
- `SCROLL_SENT`：方向滚动成功。
- `TARGET_NOT_FOUND`
- `CONTAINER_NOT_FOUND`
- `CONTAINER_AMBIGUOUS`
- `EDGE_REACHED`
- `ACTION_FAILED`
- `SCROLL_TIMEOUT`

## 5. 测试

覆盖目标已可见、滚动后出现、唯一容器、多个容器、边缘检测、最大次数、总超时和节点动作/手势两种实现。真实 RecyclerView、WebView 和横向列表需要真机验证。