跳到正文
云点iOS

全局对象与函数

脚本运行前自动注入的对象和函数：设备客户端 client、脚本参数、任务与设备的标识、停止信号，以及统一的错误码。

client#

设备客户端，自动注入。手势、应用、页面、选择器都是它的方法，比如 client.click、client.session、client.label。

typescript
declare const client: WDA.Client;

返回值

类型描述
WDA.Client连着本机 WebDriverAgent 的客户端，会自动接上 WDA 当前的会话。

示例

javascript
client.session('com.apple.Preferences');
var size = client.windowSize();

参见 client.session、client.click

params#

脚本参数，自动注入。在控制台「脚本管理」里给脚本添加的参数，脚本里用 params.参数名 直接读，不用调接口。

typescript
declare const params: Record<string, string | number | boolean>;

返回值

类型描述
Record<string, string | number | boolean>参数名到参数值的对象。值的类型跟着参数的类型走：number 拿到的是数字，boolean 是 true / false，string 是字符串。

注意事项

  • 没有这个参数时读到的是 undefined，可以顺手给个默认值：var rounds = params.rounds || 10。
  • 在代码测试台里运行，用的是当前打开的那个脚本保存好的参数；还没存成脚本的代码没有参数。
  • 别人分享给你的脚本，读到的是你自己填的参数值，不是分享者的。

示例

javascript
var keyword = params.keyword;
var rounds = params.rounds || 10;
logi('搜索 ' + keyword + '，共 ' + rounds + ' 轮');

参见 getScriptConfig

getScriptConfig#

读取参数配置页里给这个脚本填的附加配置。

typescript
getScriptConfig(scriptName: string): unknown | null;

参数

参数名类型是否必填默认值描述
scriptNamestring是—脚本名。

返回值

类型描述
unknown | null附加配置的内容；读取失败返回 null，并写一条错误日志。

示例

javascript
var cfg = getScriptConfig('daily-like');

参见 params

getTaskId#

当前任务的 ID；getScriptId() 是当前脚本的 ID。

typescript
getTaskId(): string;
getScriptId(): string;

返回值

类型描述
string任务 ID / 脚本 ID。

注意事项

  • 脚本作为任务运行时才注入。不确定时先判断：typeof getTaskId === 'function'。

示例

javascript
logi('task=' + getTaskId());

参见 getDeviceId

getDeviceId#

这台设备在系统里的 ID。

typescript
getDeviceId(): string;

返回值

类型描述
string设备 ID。

示例

javascript
logi('device=' + getDeviceId());

shouldStop#

任务是否被要求停止。长循环里一定要检查它，否则在控制台点「停止」要等脚本自己跑完才生效。

typescript
shouldStop(): boolean;

返回值

类型描述
boolean被要求停止时返回 true。

注意事项

  • 停止是协作式的：只是置位一个标志，不会强行打断脚本。sleep 和查找类函数的等待会在停止后立即返回。

示例

javascript
for (var i = 0; i < 100; i++) {
  if (shouldStop()) {
    return false;
  }
  client.swipeUp();
  sleep(randomFloat(1, 3));
}

参见 sleep

WDA.ErrorCode#

每个错误都带一个稳定的错误码 e.code。按错误码判断，不要按错误信息的文字判断 —— 文字是写给人看的，措辞会变。完整的错误码见本页末尾的表。

typescript
declare const WDA: {
  ErrorCode: {
    ELEMENT_NOT_FOUND: "WDA_ELEMENT_NOT_FOUND";
    INVALID_ARGUMENT: "INVALID_ARGUMENT";
    FEATURE_UNAVAILABLE: "FEATURE_UNAVAILABLE";
    // …见下表 / see the table below
  };
};

注意事项

  • 查找类函数（findElement、findImage、findText 等）找不到时返回 null 或 false，不抛异常；抛异常的是参数写错、设备或 WDA 出问题这类真正的错误。

示例

javascript
try {
  client.label('好').click();
} catch (e) {
  if (e.code === WDA.ErrorCode.ELEMENT_NOT_FOUND) {
    loge('没找到「好」');
  } else {
    throw e;
  }
}

错误码一览

错误码（e.code）常量什么时候出现
INVALID_ARGUMENTWDA.ErrorCode.INVALID_ARGUMENT参数写法不对：控件定位写错、等待秒数不是数字或误传了毫秒、区域格式不对、照旧写了 {} 等。属于脚本自己的问题，报错里会给出改好的写法。
WDA_ELEMENT_NOT_FOUNDWDA.ErrorCode.ELEMENT_NOT_FOUND控件对象的 click / getText / getRect 调用时控件不在。
FEATURE_UNAVAILABLEWDA.ErrorCode.FEATURE_UNAVAILABLE设备上的 App 版本太旧，缺少这个功能（找色找图、文字识别、相册），升级 App 即可。
WDA_UNKNOWNWDA.ErrorCode.UNKNOWN未归类的 WDA 错误。
WDA_BAD_GATEWAYWDA.ErrorCode.BAD_GATEWAYWDA 返回 502，通常是 WebDriverAgent 进程挂了，等它被重新拉起来再试。
WDA_EMPTY_RESPONSEWDA.ErrorCode.EMPTY_RESPONSEWDA 返回了空响应。
WDA_REQUEST_FAILEDWDA.ErrorCode.REQUEST_FAILEDWDA 拒绝了这次请求，例如参数不被接受、操作不支持。
WDA_INVALID_SESSIONWDA.ErrorCode.INVALID_SESSION会话失效（App 被关掉、WDA 重启）。client 会自动重新接上当前会话。
WDA_APP_CRASHEDWDA.ErrorCode.APP_CRASHED被操作的 App 可能已经崩溃。
WDA_KEYBOARD_NOT_PRESENTWDA.ErrorCode.KEYBOARD_NOT_PRESENT要用键盘的操作执行时，键盘没有弹出。
WDA_INVALID_ELEMENT_STATEWDA.ErrorCode.INVALID_ELEMENT_STATE控件当前的状态不允许这个操作，比如不可用、不可编辑。
API_FAILEDWDA.ErrorCode.API_FAILED业务中心接口报错，比如读脚本参数、解析模板名时服务端出错。
IMAGE_FAILEDWDA.ErrorCode.IMAGE_FAILED图色操作失败（未细分的原因）。
IMG_BAD_HANDLEWDA.ErrorCode.IMAGE_BAD_HANDLE截图已经释放（releaseScreen 之后）或句柄无效。
IMG_TOO_MANY_HANDLESWDA.ErrorCode.IMAGE_TOO_MANY_HANDLES同时留着的截图超过上限（4 张）。keepScreen 定住的画面用完要 releaseScreen。
IMG_CAPTURE_FAILEDWDA.ErrorCode.IMAGE_CAPTURE_FAILED截图失败，多半是 WDA 没有起来。
TPL_NOT_FOUNDWDA.ErrorCode.TEMPLATE_NOT_FOUND拿不到模板图：这个脚本没上传这个文件名的图，或者下载失败。
TPL_TOO_LARGEWDA.ErrorCode.TEMPLATE_TOO_LARGE模板比搜索区域还大，多半是在别的分辨率上截的。
OCR_LANG_UNSUPPORTEDWDA.ErrorCode.OCR_LANG_UNSUPPORTED这台设备的 Vision 不支持要求的识别语言。
OCR_FAILEDWDA.ErrorCode.OCR_FAILED文字识别失败。