页面与系统

读当前页面的控件树、屏幕尺寸和截图，打开链接、写剪贴板，处理系统弹窗。

client.source#

当前页面的控件树。调试定位时有用，但比较慢，别放在循环里反复调。

typescript

client.source(format?: "xml" | "json", accessible?: boolean): string;

参数

参数名	类型	是否必填	默认值	描述
`format`	`"xml" \| "json"`	否	`"xml"`	输出格式。
`accessible`	`boolean`	否	`false`	传 true 只要无障碍可见的节点，树会小很多。

返回值

类型	描述
`string`	控件树的文本。

示例

javascript

var xml = client.source();
logd(xml.substring(0, 500));

参见 setSnapshotMaxDepth

setSnapshotMaxDepth#

设置读控件树的最大深度（默认 50）。越深能找到嵌得越深的控件，但越慢。返回改之前的深度，方便临时调大、用完改回去。

typescript

setSnapshotMaxDepth(depth?: number): number | null;

参数

参数名	类型	是否必填	默认值	描述
`depth`	`number`	否	`50`	最大深度。

返回值

类型	描述
`number \| null`	改之前的深度；读不到时是 null。

注意事项

深度 0 在 WDA 上是「只要根节点」，不是「不限制」。还原时如果拿到的原值小于 1，就别写回去。

示例

javascript

var prev = setSnapshotMaxDepth(80);
var found = findElement('accessibilityId', 'deep_button');
if (prev >= 1) {
  setSnapshotMaxDepth(prev);
}

参见 client.source

client.windowSize#

屏幕尺寸，单位 point。结果会被缓存。

typescript

client.windowSize(): { width: number; height: number };

返回值

类型	描述
`{ width, height }`	屏幕宽高，单位 point。

示例

javascript

var size = client.windowSize();
client.click(size.width / 2, size.height - 80);

client.screenshot#

截屏，拿到图片数据。找色、找图、识字不用先截图，直接调 findColor / findImage / ocr。

typescript

client.screenshot(format?: "base64" | "bytes"): string | number[];

参数

参数名	类型	是否必填	默认值	描述
`format`	`"base64" \| "bytes"`	否	`"base64"`	base64 返回 PNG 的 base64 字符串，bytes 返回字节数组。

返回值

类型	描述
`string \| number[]`	PNG 图片数据。

异常

异常类型	触发条件
`WDAError`	format 不是 base64 或 bytes。

示例

javascript

var png = client.screenshot();
savePicVideo(png, 'screen.png');

参见 keepScreen、savePicVideo

client.openUrl#

让系统打开一个网址或自定义 scheme（例如 App 的深链接）。

typescript

client.openUrl(targetUrl: string): object;

参数

参数名	类型	是否必填	默认值	描述
`targetUrl`	`string`	是	—	要打开的地址。

返回值

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

示例

javascript

client.openUrl('https://example.com');

client.setClipboard#

写入设备剪贴板，支持中文等非 ASCII 文字。用 client.getClipboard() 读回来。

typescript

client.setClipboard(content: string, contentType?: string): object;
client.getClipboard(): string;

参数

参数名	类型	是否必填	默认值	描述
`content`	`string`	是	—	要写入的文字。
`contentType`	`string`	否	`"plaintext"`	内容类型。

返回值

类型	描述
`object \| string`	setClipboard 返回 WDA 的原始响应；getClipboard 返回剪贴板里的文字。

异常

异常类型	触发条件
`WDAError`	content 不是字符串。

注意事项

iOS 只允许前台 App 读剪贴板，getClipboard 会先经 Siri 把 WDA 切到前台、读完再切回原来的 App，整个过程约 3 秒。

示例

javascript

client.setClipboard('要粘贴的文字 / text to paste');
var text = client.getClipboard();

参见 client.sendKeys

client.alert#

处理系统弹窗（权限请求、确认框等）：看在不在、点允许、点取消、列出按钮。

typescript

client.alert.exists(): boolean;
client.alert.accept(): object;
client.alert.dismiss(): object;
client.alert.buttons(): string[];

返回值

类型	描述
`boolean \| object \| string[]`	exists 有弹窗返回 true；accept 点最后一个按钮（通常是「允许」「好」），dismiss 点第一个（通常是「取消」「不允许」）；buttons 按顺序返回按钮文字。

注意事项

要点某个具体的按钮，用 client.alert.click('按钮文字')；client.alert.wait(秒数) 等弹窗出现。

示例

javascript

if (client.alert.exists()) {
  client.alert.accept();
}