控件集合 (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 源码摘要:

kotlin

/* 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 类型, 表示集合中所有控件在执行行为过程中未出现失败或异常.

常见相关方法或属性:

[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();