AutoJs6

- Overview - 综述
- About - 关于文档
- Progress - 文档部署进度
- Changelog - 文档更新日志

- Manual - AutoJs6 使用手册
- Q & A - 疑难解答

- Global - 全局对象
- Automator - 自动化
- AutoJs6 - 本体应用
- App - 通用应用
- Color - 颜色
- Image - 图像
- OCR - 光学字符识别
- Barcode - 条码
- QR Code - 二维码
- Keys - 按键
- Device - 设备
- Storage - 储存
- File - 文件
- Engine - 引擎
- Task - 任务
- Module - 模块
- Plugins - 插件
- Toast - 消息浮动框
- Notice - 消息通知
- Console - 控制台
- Shell
- Shizuku
- Media - 多媒体
- Sensor - 传感器
- Recorder - 记录器
- Timer - 定时器
- Thread - 线程
- Continuation - 协程
- Event - 事件监听
- Dialog - 对话框
- Floaty - 悬浮窗
- Canvas - 画布
- UI - 用户界面
- Web - 万维网
- HTTP
- Base64
- Crypto - 密文
- Internationalization - 国际化
- Standardization - 标准化
- E4X

- UiSelector - 选择器
- UiObject - 控件节点
- UiObjectCollection - 控件集合
- UiObjectActions - 控件节点行为
- WebSocket
- EventEmitter - 事件发射器
- ImageWrapper - 包装图像类
- App - 应用枚举类
- Color - 颜色类
- Version - 版本工具类
- Polyfill - 代码填泥
- Arrayx - Array 扩展
- Numberx - Number 扩展
- Mathx - Math 扩展

- Exceptions - 异常
- Intent - 意图
- Runtime - 运行时
- Context - 上下文
- Activity - 活动

- Scripting Java - 脚本化 Java
- Android API Level - 安卓 API 级别
- Color Table - 颜色列表

- Glossaries - 术语
- HttpHeader - HTTP 标头
- HttpRequestMethods - HTTP 请求方法
- MimeType - MIME 类型
- NotificationChannel - 通知渠道

- Data Types - 数据类型
- Omnipotent Types - 全能类型
- Storage - 存储类
- AndroidBundle
- AndroidRect
- CryptoCipherOptions
- CryptoKey
- CryptoKeyPair
- ConsoleBuildOptions
- HttpRequestBuilderOptions
- HttpRequestHeaders
- HttpResponseBody
- HttpResponseHeaders
- HttpResponse
- InjectableWebClient
- InjectableWebView
- NoticeOptions
- NoticeChannelOptions
- NoticePresetConfiguration
- NoticeBuilder
- Okhttp3HttpUrl
- OcrOptions
- Okhttp3Request
- OpencvPoint
- OpencvRect
- OpencvSize

- GitHub - 应用项目地址
- GitHub - 文档项目地址

# 控件集合 (UiObjectCollection)#

UiObjectCollection 代表 控件节点 (UiObject) 的对象集合.

UiObjectCollection

## [@] UiObjectCollection#

`Global`

AutoJs6 中几乎所有 UiObjectCollection 实例均已借助 Rhino 引擎将其包装为了 NativeArray 类型.
因此 JavaScript 的 Array 原型方法在 UiObjectCollection 实例上可以直接使用:

    let wc = contentMatch(/.+/).find();
    wc.toArray().forEach(w => console.log(w.content()));
    wc.forEach(w => console.log(w.content())); /* 效果同上. */

    /* 包装后的对象 "是" 一个 JavaScript 数组. */
    console.log(Array.isArray(wc)); // true

    /* Array 的原型方法 slice. */
    console.log(typeof wc.slice); // 'function'
    console.log(wc.slice === Array.prototype.slice); // true

    /* UiObjectCollection "类" 的实例方法依然全部可用 (如 size, click, each 等). */
    console.log(typeof wc.size); // 'function'
    console.log(typeof wc.click); // 'function'
    console.log(typeof wc.each); // 'function'

经过包装的 UiObjectCollection 将不能通过 instanceof 判断其类型, 但仍可通过 getClass 方法判断:

    let wc = contentMatch(/.+/).find();
    console.log(wc instanceof UiObjectCollection); // false
    console.log(wc.getClass() === UiObjectCollection); // true

除上述 find 方法, children, untilFind, findOf 以及附带集合类结果筛选器的 pickup, 返回的也都是一个经过包装的 UiObjectCollection:

    let s = contentMatch(/.+/);
    let w = pickup(s);
    let wcList = [
        s.find(),
        s.untilFind(),
        s.findOf(w && w.compass('p2') || pickup()),
        pickup(s, '{}'),
    ];
    console.log(wcList.every(o => o.getClass() === UiObjectCollection)); // true

当 pickup 使用 children 等作为结果筛选器时, 返回的是不经过包装的 UiObjectCollection, 因此需要使用一次 toArray 方法才能使用 JavaScript 的数组相关方法:

    let wc = pickup(/.+/, 'p', 'children');
    /* 需使用 toArray 进行一次转换. */
    wc.toArray().forEach(w => console.log(w.content()));

    /* 直接使用 children 方法则不需要 toArray 转换. */
    pickup(/.+/, 'p').children().forEach( /* ... */ );

UiObjectCollection 可能为空集合:

    /* 空集合. */
    let wc = contentMatch(/[^\s\S]/).find();

    console.log(wc.length); // 0

    /* 即使是空集合, 依然是 UiObjectCollection 类型. */
    console.log(wc === null); // false
    console.log(wc.getClass() === UiObjectCollection); // true

集合的遍历即可用 UiObjectCollection 的实例方法 (如 each), 或使用 JavaScript 的数组遍历方法 (如 forEach), 或使用 [ for / for...in (不推荐) / for...of ] 循环:

    /**
     * @type {UiObjectCollection | Array<UiObject>}
     */
    let wc = pickup(/.+/, 'wc');

    wc.each(w => console.log(detect(w, 'txt')));

    wc.forEach(w => console.log(detect(w, 'txt')));

    for (let i = 0; i < wc.length; i += 1) {
        console.log(detect(wc[i], 'txt'));
    }

    for (let i in wc) {
        if (wc.hasOwnProperty(i) && /^\d+$/.test(i)) {
            console.log(detect(wc[i], 'txt'));
        }
    }

    for (let w of wc) {
        console.log(detect(w, 'txt'));
    }

控件集合支持 控件行为 (UiObject Action).
如 [ click / longClick / imeEnter / setText / focus ] 等.

performAction 源码摘要:

    /* Updated as of Nov 2, 2022. */

    override fun performAction(action: Int, vararg arguments: ActionArgument): Boolean {
        var success = true
        nodes.filterNotNull().forEach { node ->
            when (arguments.isEmpty()) {
                true -> node.performAction(action)
                else -> node.performAction(action, *arguments)
            }.also { success = success and it }
        }
        return success
    }

由源码摘要可知, 控件集合执行控件行为, 相当于使集合中所有控件依次执行一次控件行为:

    let wc = contentMatch(/[^\s\S]/).find();

    /* 对控件集合执行 click 控件行为. */
    wc.click();

    /* 相当于对集合中每个控件元素执行控件行为. */
    wc.forEach(w => {
        if (w !== null) {
            w.click();
        }
    });

执行控件行为后, 返回结果是 boolean 类型, 表示集合中所有控件在执行行为过程中未出现失败或异常.

常见相关方法或属性:

- UiObject#find
- UiObject#children
- UiSelector#find
- UiSelector#untilFind
- UiSelector.pickup

## [m#] isEmpty#

### isEmpty()#

`6.2.0`

- returns { boolean }

返回集合是否为空.

## [m#] isNotEmpty#

### isNotEmpty()#

`6.2.0`

- returns { boolean }

返回集合是否非空.

## [m#] empty#

### empty()#

`DEPRECATED`

- returns { boolean }

返回集合是否为空.

已弃用, 建议使用 isEmpty 替代.

## [m#] nonEmpty#

### nonEmpty()#

`DEPRECATED`

- returns { boolean }

返回集合是否非空.

已弃用, 建议使用 isNotEmpty 替代.

## [m#] toArray#

### toArray()#

- returns { JavaArray<UiObject> }

转换集合为 Java 数组.

## [m#] toList#

### toList()#

`6.2.0`

- returns { JavaArrayList<UiObject> }

转换集合为 Java 数组列表.

## [m#] get#

### get(i)#

`DEPRECATED`

- returns { UiObject }

按索引获取集合中的 UiObject 元素.

已弃用, 建议使用数组下标形式访问元素.

    let wc = pickup(/.+/, '{}');
    if (wc.length >= 2) {
        console.log(wc.get(2) instanceof UiObject); // true
        console.log(wc[2] instanceof UiObject); // true
    }

## [m#] size#

### size()#

`DEPRECATED`

- returns { UiObject }

返回集合大小.

已弃用, 建议使用 length 属性.

    let wc = pickup(/.+/, '{}');
    console.log(wc.size()); // e.g. 23
    console.log(wc.length); // e.g. 23

## [m#] each#

### each(consumer)#

`DEPRECATED`

- consumer { (w: UiObject) => void } - 消费者
- returns { UiObjectCollection }

对集合中每个元素执行一次消费.

已弃用, 建议使用 forEach.

    let wc = pickup(/.+/, '{}');
    wc.each(w => console.log(w.content()));
    wc.forEach(w => console.log(w.content()));

## [m#] find#

### find(selector)#

`A11Y`

- selector { UiSelector } - 选择器
- returns { UiObjectCollection }

筛选新的控件集合.

以集合中每一个元素为根节点, 依次按选择器筛选出所有满足条件的后代节点加入新集合, 将此新集合作为返回结果.

    /* 例如此集合中共有 3 个控件. */
    let wc = pickup(/.+/);
    console.log(wc.length); // 3

    /* 3 个控件作为根节点, 其所有的子孙节点分别有 10, 50, 200 个. */
    console.log(wc.map(w => w.find().length)); // [ 10, 50, 200 ]

    /* 其中 clickable 为 true 的控件分别有 2, 3, 4 个. */
    console.log(wc.map(w => w.find().filter(c => c.clickable()).length)); // [ 2, 3, 4 ]

    /* 因此 wc.find(clickable(true)) 应返回 2 + 3 + 4 个. */
    console.log(wc.find(clickable(true)).length); // 9

## [m#] findOne#

### findOne(selector)#

`A11Y`

- selector { UiSelector } - 选择器
- returns { UiObject | null }

筛选一个控件.

以集合中每一个元素为根节点, 遍历其所有后代节点, 当满足选择器的筛选条件时, 返回此控件并停止筛选.
无满足筛选条件的控件时返回 null.

    let wc = pickup(/.+/);
    console.log(wc.findOne(clickable(true))); /* 返回一个可点击控件或 null. */

## [m#] performAction#

用于执行控件集合的行为.

集合中所有控件将全部执行指定的行为.

### performAction(action, ...arguments)#

`A11Y`

- action { number } - 行为的唯一标志符 (Action ID)
- arguments { ...ActionArgument[] } - 行为参数, 用于给行为传递参数
- returns { boolean }

返回行为是否全部执行成功.

> 注: 即使在执行过程中, 某一个控件执行失败, 后续控件依旧继续执行行为, 而非立即终止.

> 参阅: UiObjectActions 章节.

## [m#] click#

### click()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 点击 ] 行为.

## [m#] longClick#

### longClick()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 长按 ] 行为.

## [m#] accessibilityFocus#

### accessibilityFocus()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 获取无障碍焦点 ] 行为.

## [m#] clearAccessibilityFocus#

### clearAccessibilityFocus()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 清除无障碍焦点 ] 行为.

## [m#] focus#

### focus()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 获取焦点 ] 行为.

## [m#] clearFocus#

### clearFocus()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 清除焦点 ] 行为.

## [m#] dragStart#

### dragStart()#

`6.2.0` `A11Y` `API>=32`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 拖放开始 ] 行为.

## [m#] dragDrop#

### dragDrop()#

`6.2.0` `A11Y` `API>=32`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 拖放放下 ] 行为.

## [m#] dragCancel#

### dragCancel()#

`6.2.0` `A11Y` `API>=32`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 拖放取消 ] 行为.

## [m#] imeEnter#

### imeEnter()#

`6.2.0` `A11Y` `API>=30`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 输入法 ENTER 键 ] 行为.

## [m#] moveWindow#

### moveWindow(x, y)#

`6.2.0` `A11Y` `API>=26`

- x { number } - X 坐标
- y { number } - Y 坐标
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 移动窗口到新位置 ] 行为.

## [m#] nextAtMovementGranularity#

### nextAtMovementGranularity(granularity, isExtendSelection)#

`6.2.0` `A11Y`

- granularity { number } - 粒度
- isExtendSelection { boolean } - 是否扩展选则文本
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 按粒度移至下一位置 ] 行为.

## [m#] nextHtmlElement#

### nextHtmlElement(element)#

`6.2.0` `A11Y`

- element { string } - 元素名称
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 按元素移至下一位置 ] 行为.

## [m#] pageLeft#

### pageLeft()#

`6.2.0` `A11Y` `API>=29`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗左移的翻页 ] 行为.

## [m#] pageUp#

### pageUp()#

`6.2.0` `A11Y` `API>=29`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗上移的翻页 ] 行为.

## [m#] pageRight#

### pageRight()#

`6.2.0` `A11Y` `API>=29`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗右移的翻页 ] 行为.

## [m#] pageDown#

### pageDown()#

`6.2.0` `A11Y` `API>=29`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗下移的翻页 ] 行为.

## [m#] pressAndHold#

### pressAndHold()#

`6.2.0` `A11Y` `API>=30`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 按住 ] 行为.

## [m#] previousAtMovementGranularity#

### previousAtMovementGranularity(granularity, isExtendSelection)#

`6.2.0` `A11Y`

- granularity { number } - 粒度
- isExtendSelection { boolean } - 是否扩展选则文本
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 按粒度移至上一位置 ] 行为.

## [m#] previousHtmlElement#

### previousHtmlElement(element)#

`6.2.0` `A11Y`

- element { string } - 元素名称
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 按元素移至上一位置 ] 行为.

## [m#] showTextSuggestions#

### showTextSuggestions()#

`6.2.0` `A11Y` `API>=33`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 显示文本建议 ] 行为.

## [m#] showTooltip#

### showTooltip()#

`6.2.0` `A11Y` `API>=28`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 显示工具提示信息 ] 行为.

## [m#] hideTooltip#

### hideTooltip()#

`6.2.0` `A11Y` `API>=28`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 隐藏工具提示信息 ] 行为.

## [m#] show#

### show()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 显示在视窗内 ] 行为.

## [m#] dismiss#

### dismiss()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 消隐 ] 行为.

## [m#] copy#

### copy()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 复制文本 ] 行为.

## [m#] cut#

### cut()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 剪切文本 ] 行为.

## [m#] paste#

### paste()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 粘贴文本 ] 行为.

## [m#] select#

### select()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 选中 ] 行为.

## [m#] expand#

### expand()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 展开 ] 行为.

## [m#] collapse#

### collapse()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 折叠 ] 行为.

## [m#] scrollLeft#

### scrollLeft()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗左移的滚动 ] 行为.

## [m#] scrollUp#

### scrollUp()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗上移的滚动 ] 行为.

## [m#] scrollRight#

### scrollRight()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗右移的滚动 ] 行为.

## [m#] scrollDown#

### scrollDown()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗下移的滚动 ] 行为.

## [m#] scrollForward#

### scrollForward()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗前移的滚动 ] 行为.

## [m#] scrollBackward#

### scrollBackward()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 使视窗后移的滚动 ] 行为.

## [m#] scrollTo#

### scrollTo(row, column)#

`A11Y`

- row { number } - 行序数
- column { number } - 列序数
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 将指定位置滚动至视窗内 ] 行为.

## [m#] contextClick#

### contextClick()#

`A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 上下文点击 ] 行为.

## [m#] setText#

### setText(text)#

`A11Y`

- text { string } - 文本
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 设置文本 ] 行为.

## [m#] setSelection#

### setSelection(start, end)#

`A11Y`

- start { number } - 开始位置
- end { number } - 结束位置
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 选择文本 ] 行为.

## [m#] clearSelection#

### clearSelection()#

`6.2.0` `A11Y`

- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 取消选择文本 ] 行为.

## [m#] setProgress#

### setProgress(progress)#

`A11Y`

- progress { number } - 进度值
- returns { boolean } - 是否行为已全部执行且执行过程中无异常

控件集合执行 [ 设置进度值 ] 行为.

## [m] of#

### of(list)#

- list { UiSelector[] } - 控件数组
- returns { UiObjectCollection }

将控件数组转换为 UiObjectCollection.

    let wA = pickup(/hello.+/);
    let wB = pickup({ clickable: true });

    let wc = UiObjectCollection.of([ wA, wB ]);

    /* 对 UiObjectCollection 进行操作. */
    wc.click();