agent_admin/docs/agent/actions/scroll.md

SCROLL [提案]

返回动作目录 · 统一选择器 · 执行与结果

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

1. 滚动到目标

{
  "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. 按方向滚动

{
  "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 和横向列表需要真机验证。