AutoJs6 文档 - 6.6.4

目录

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

常见相关方法或属性:

[m#] isEmpty#

isEmpty()#

6.2.0

返回集合是否为空.

[m#] isNotEmpty#

isNotEmpty()#

6.2.0

返回集合是否非空.

[m#] empty#

empty()#

DEPRECATED

返回集合是否为空.

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

[m#] nonEmpty#

nonEmpty()#

DEPRECATED

返回集合是否非空.

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

[m#] toArray#

toArray()#

转换集合为 Java 数组.

[m#] toList#

toList()#

6.2.0

转换集合为 Java 数组列表.

[m#] get#

get(i)#

DEPRECATED

按索引获取集合中的 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

返回集合大小.

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

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

[m#] each#

each(consumer)#

DEPRECATED

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

已弃用, 建议使用 forEach.

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

[m#] find#

find(selector)#

A11Y

筛选新的控件集合.

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

/* 例如此集合中共有 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

筛选一个控件.

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

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

[m#] performAction#

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

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

performAction(action, ...arguments)#

A11Y

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

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

参阅: 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)#

将控件数组转换为 UiObjectCollection.

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

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

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