Acc 模块

android.acc 是无障碍自动化核心模块，负责窗口、节点、查找、节点动作和节点树序列化。

典型场景

  • 获取当前窗口与根节点
  • 查找按钮、文本、资源 ID 对应的节点
  • 点击、滑动、执行节点动作
  • 把节点树转成 JSON 供分析器或可视化工具使用

常用方法

getWindows()

获取当前可见窗口列表。

  • 参数：无
  • 返回值：Promise<GetWindowsRes[]>
  • 常见字段：id、packName、boundsInScreen、type

getNode(windowId = -1)

获取指定窗口的根节点。

  • 参数：windowId?: number，默认 -1
  • 返回值：Promise<AccNode> 或等价节点对象
  • 说明：-1 一般表示当前窗口
const rootNode = await android.acc.getNode(-1)

getChildNode(index, nodeId)

获取子节点。

  • 参数：
    • index: number
    • nodeId: number
  • 返回值：节点对象或节点 ID 对应包装对象

getParentNode(nodeId)

获取父节点。

  • 参数：nodeId: number
  • 返回值：节点对象或节点 ID 对应包装对象

performAction(nodeId, code)

对节点执行动作。

  • 参数：
    • nodeId: number
    • code: number
  • 返回值：Promise<boolean>

performActionEx(nodeId, code)

执行带重试或更稳妥的节点动作。

  • 参数与返回值同 performAction

swipe(x1, y1, x2, y2, t)

执行滑动操作。

  • 参数：
    • x1: number
    • y1: number
    • x2: number
    • y2: number
    • t: number：持续时间（毫秒）
  • 返回值：Promise<boolean>

查找能力

除基础节点方法外，项目中的实际测试还大量使用了这些高频方法：

  • findView(condition, timeout?)
  • findViewEx(condition, timeout?)
  • findViews(condition, timeout?)
  • findViewByDesc(desc, timeout?)
  • findViewByDescs(desc, timeout?)
  • findViewById(id, timeout?)
  • findViewByIds(id, timeout?)

查询条件属性

findView / findViewEx / findViews 的第一个参数是查询条件对象，支持以下 30 个属性。传入多个属性时为 AND 关系（同时满足）。

文本匹配

属性类型匹配方式说明
textstring精确匹配节点文本完全等于指定值
textExstring包含匹配节点文本包含指定子串
contentDescriptionstring精确匹配节点描述完全等于指定值
contentDescriptionExstring包含匹配节点描述包含指定子串

组件与资源

属性类型匹配方式说明
classNamestring精确匹配节点类名，如 android.widget.Button
resourceIdstring精确匹配资源ID，如 com.example:id/btn_ok

状态属性（布尔值）

属性说明
isClickable是否可点击
isLongClickable是否可长按
isEnabled是否启用
isFocused是否获得焦点
isFocusable是否可获焦点
isChecked是否已勾选
isCheckable是否可勾选
isScrollable是否可滚动
isVisibleToUser是否对用户可见
isEditable是否可编辑
isPassword是否为密码框

边界属性

用于按屏幕坐标范围筛选节点，分三种匹配模式：

前缀匹配方式示例属性
无前缀精确等于boundsInScreenLeft、boundsInScreenTop、boundsInScreenRight、boundsInScreenBottom
min大于等于 (≥)minBoundsInScreenLeft、minBoundsInScreenTop、minBoundsInScreenRight、minBoundsInScreenBottom
max小于等于 (≤)maxBoundsInScreenLeft、maxBoundsInScreenTop、maxBoundsInScreenRight、maxBoundsInScreenBottom

边界属性的类型均为 number，对应屏幕像素坐标。

结构属性

属性类型匹配方式说明
childCountnumber精确匹配子节点个数

使用示例

// 精确匹配文本
await android.acc.findView({ text: '确定' })

// 包含匹配文本（模糊查找）
await android.acc.findView({ textEx: '确定' }) // 能匹配 "请点击确定按钮"

// 通过描述查找
await android.acc.findView({ contentDescription: '返回' })
await android.acc.findView({ contentDescriptionEx: '返回' }) // 包含匹配

// 通过资源ID查找
await android.acc.findView({ resourceId: 'com.example:id/btn_ok' })

// 组合条件（同时满足）
await android.acc.findView({
  className: 'android.widget.Button',
  isClickable: true,
})

// 在指定区域内查找（用边界范围限定）
await android.acc.findView({
  textEx: '设置',
  minBoundsInScreenTop: 100,
  maxBoundsInScreenBottom: 500,
})

// 查找可编辑的输入框
await android.acc.findView({
  isEditable: true,
  className: 'android.widget.EditText',
})

// 查找已勾选的复选框
await android.acc.findView({ isChecked: true, isCheckable: true })

节点对象常用能力

通过 getNode() 或 findView() 得到节点后，通常会继续调用：

  • node.getChildNode(index)
  • node.getParentNode()
  • node.click()
  • node.toJson(false)
  • node.toJson(true)

toJson(showOnlyVisible?)

把节点树转换为 JSON。

  • 参数：showOnlyVisible?: boolean
  • 返回值：节点 JSON 对象
  • 用途：节点分析、可视化树、调试 UI 层级
const rootNode = await android.acc.getNode()
const json = await rootNode.toJson(false)
console.log(json.className, json.childCount)

注意事项

  1. android.acc 依赖无障碍权限
  2. 页面切换后再查找节点，通常要先等待界面稳定
  3. toJson() 返回的数据可能很大，适合调试和节点分析，不建议在业务主流程中频繁全量调用
  4. 查找不到节点时，优先检查：页面是否正确、无障碍是否开启、超时时间是否太短