控件

日常脚本用得最多的一组。参数按顺序写：按什么找、找什么、最多等几秒。找不到返回 null 或 false，不抛异常；只有参数写错才会抛 INVALID_ARGUMENT。

功能概览

·前两个参数是按什么找（7 种，和选择器同名）和找什么
·第三个参数是最多等几秒：findElement / getElementText 默认只看一眼，clickElement 默认等 10 秒
·clickElement 默认把点没点到记进日志（setClickLog 可关），第四个参数是日志里的名字，第五个参数选落点
·返回的控件对象常用 exists / click / getText / getRect 四个方法

findElement#

找控件。默认只看一眼；给了等待秒数就每隔 0.5 秒再找一次，直到找到或超时。找到返回控件对象，没找到返回 null。

typescript

type By =
  | "label" | "labelContains" | "accessibilityId"
  | "xpath" | "predicate" | "classChain" | "className";

findElement(by: By, value: string, timeoutSec?: number): Element | null;

参数

参数名	类型	是否必填	默认值	描述
`by`	`By`	是	—	按什么找：label 文字完全相等，labelContains 文字包含，accessibilityId 按控件的名字（开发者起的，最稳），xpath / predicate / classChain / className 和同名选择器一样。只认这 7 个值，写错会抛 INVALID_ARGUMENT，报错里直接给出改好的写法。
`value`	`string`	是	—	找什么：文字、名字或表达式，含义随 by 而定。不能为空。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼。

返回值

类型	描述
`Element \| null`	找到的控件对象；超时还没找到返回 null。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：by 不是那 7 个值之一、value 为空、等待秒数不是数字或超过 600（多半是误传了毫秒）、照旧写法传了 {}。控件找不到不算错，不会抛异常。

注意事项

只写文字（findElement('登录')）或照旧写 {} 会直接报错，报错里给出改好的那一行。
命中多个时取第一个、只找看得见的。要第几个、或者要连看不见的一起找，用选择器：client.label('确定', false, 1)。

示例

javascript

if (findElement('label', '登录', 3)) {
  logi('检测到登录页');
}

var balance = findElement('labelContains', '余额');
if (balance) {
  logi(balance.getText());
}

参见 clickElement、getElementText、client.label

clickElement#

等控件出现并点它，落点在控件范围里随机。点到返回 true，等不到或点不了返回 false，不抛异常。

typescript

clickElement(
  by: By,
  value: string,
  timeoutSec?: number,
  desc?: string,
  position?: "random" | "up" | "center" | "bottom"
): boolean;

参数

参数名	类型	是否必填	默认值	描述
`by`	`By`	是	—	按什么找：label 文字完全相等，labelContains 文字包含，accessibilityId 按控件的名字（开发者起的，最稳），xpath / predicate / classChain / className 和同名选择器一样。只认这 7 个值，写错会抛 INVALID_ARGUMENT，报错里直接给出改好的写法。
`value`	`string`	是	—	找什么：文字、名字或表达式，含义随 by 而定。不能为空。
`timeoutSec`	`number`	否	`10`	最多等几秒。可有可无的弹窗写 1，别白等 10 秒。
`desc`	`string`	否	—	控件在日志里叫什么。点到记「点击控件 xxx」，没找到记「没有找到控件 xxx」；不写就用定位写法，比如「点击控件 label=确定」。高频轮询时不想刷屏，用 setClickLog(false) 关掉。
`position`	`"random" \| "up" \| "center" \| "bottom"`	否	`"random"`	点哪儿：random 在控件范围里随机（落点多在中间一带），up 上部三分之一，center 正中附近，bottom 下部三分之一。和录制器里「点击位置」的四个选项一致。

返回值

类型	描述
`boolean`	点到返回 true；等不到控件、或点的时候出错返回 false。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错，包括 position 不是那 4 个值。参数写错是脚本的问题，会直接抛出来，不会被当成「没找到」返回 false。第三个参数传了文字（旧写法把名字写在这儿）也会报错，并提示把名字挪到第四个。

示例

javascript

clickElement('label', '确定');
clickElement('labelContains', '跳过', 1);          // 可有可无的弹窗，最多等 1 秒
clickElement('label', '确定', 10, '确定按钮');      // 日志里写「确定按钮」
clickElement('accessibilityId', 'publish', 5, null, 'center');

参见 findElement、element.click、setClickLog

getElementText#

读控件的文字，或者它的某个属性。找不到控件、读不到时返回 null。

typescript

getElementText(by: By, value: string, timeoutSec?: number, attr?: string): string | null;

参数

参数名	类型	是否必填	默认值	描述
`by`	`By`	是	—	按什么找：label 文字完全相等，labelContains 文字包含，accessibilityId 按控件的名字（开发者起的，最稳），xpath / predicate / classChain / className 和同名选择器一样。只认这 7 个值，写错会抛 INVALID_ARGUMENT，报错里直接给出改好的写法。
`value`	`string`	是	—	找什么：文字、名字或表达式，含义随 by 而定。不能为空。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼。
`attr`	`string`	否	—	不写读文字；写了读这个属性，例如 value、enabled、name。

返回值

类型	描述
`string \| null`	文字或属性值；找不到、读不到返回 null。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：by 不是那 7 个值之一、value 为空、等待秒数不是数字或超过 600（多半是误传了毫秒）、照旧写法传了 {}。控件找不到不算错，不会抛异常。

示例

javascript

var balance = getElementText('accessibilityId', 'balance', 3);
if (balance !== null) {
  logi('余额：' + balance);
}

var enabled = getElementText('accessibilityId', 'submit', 0, 'enabled');

参见 element.getText

element.exists#

控件现在在不在。只查一次，不等待。findElement 和选择器（client.label 等）返回的都是这种控件对象。

typescript

element.exists(): boolean;

返回值

类型	描述
`boolean`	在返回 true，否则 false。

示例

javascript

var ok = client.label('好');
if (ok.exists()) {
  ok.click();
}

参见 findElement、client.label

element.click#

在控件范围里随机点一下，落点多在中间一带、离边缘留有余量，每次都不一样。

typescript

element.click(): object;

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAElementNotFoundError`WDA_ELEMENT_NOT_FOUND	调用的那一刻控件不在。这些方法不会等待 —— 要等，先用 findElement 带上等待秒数。

示例

javascript

var btn = findElement('label', '确定', 5);
if (btn) {
  btn.click();
}

参见 clickElement

element.getText#

读控件的文字。

typescript

element.getText(): string;

返回值

类型	描述
`string`	控件上的文字。

异常

异常类型	触发条件
`WDAElementNotFoundError`WDA_ELEMENT_NOT_FOUND	调用的那一刻控件不在。这些方法不会等待 —— 要等，先用 findElement 带上等待秒数。

示例

javascript

var el = findElement('labelContains', '余额');
if (el) {
  logi(el.getText());
}

参见 getElementText

element.getRect#

控件的位置和大小，单位 point，可以直接拿去 client.click。

typescript

element.getRect(): { x: number; y: number; width: number; height: number };

返回值

类型	描述
`{ x, y, width, height }`	左上角坐标和宽高，单位 point。

异常

异常类型	触发条件
`WDAElementNotFoundError`WDA_ELEMENT_NOT_FOUND	调用的那一刻控件不在。这些方法不会等待 —— 要等，先用 findElement 带上等待秒数。

示例

javascript

var r = client.accessibilityId('avatar').getRect();
client.click(r.x + r.width / 2, r.y + r.height / 2);

参见 client.click