脚本 API 参考

最小可运行脚本

脚本必须返回 true 才算成功；返回 false 或不返回都记为失败。运行时库已经拼在脚本前面，client、clickElement、logi、sleep 这些可以直接用。

function main() {
  // 打开「设置」，点进「通用」
  client.session('com.apple.Preferences');
  sleep(2);

  if (!clickElement('label', '通用', 5)) {
    loge('没找到「通用」');
    return false;
  }

  logi('已进入通用设置');
  return true;
}

main();

通用约定

参数按顺序写

所有函数都按顺序传参，不用写 {}。常用的参数在前面，后面用不上的可以不写；中间某个想用默认值就写 null，比如 findImage('a.png', 0, null, 0.85)。照旧写法传 {} 会报 INVALID_ARGUMENT，报错里直接给出改好的那一行。

控件定位写明按什么找

控件函数的前两个参数是按什么找、找什么：clickElement('label', '登录')。按什么找只有 7 种，和选择器同名：label（文字完全相等）、labelContains（文字包含）、accessibilityId（控件的名字，最稳）、xpath、predicate、classChain、className。

时间一律是秒

所有时长参数都以秒为单位，可以是小数。查找、读取类默认只看一眼，点击类默认最多等 10 秒。超过 600 的取值会被当成误传的毫秒拒绝。唯一的例外是 setTimeout 和 setInterval，它们沿用 JavaScript 的毫秒约定。

坐标和区域

坐标一律是 point，不是像素：拿到的 x、y 可以直接给 client.click，同一份脚本在 2x、3x 屏上都对。x、y 都在 0~1 之间时按屏幕比例处理。区域写成 [x, y, 宽, 高]，四个数都在 0~1 之间按屏幕比例算（换分辨率也通用），否则按 point。

同一个画面查好几样

找色、找图、识字默认每次自己截一张、用完就释放。要在同一个画面上查好几样，先 keepScreen() 把画面定住、查完 releaseScreen()；或者用 withScreen(function () { … })，跑完自动放开。

停止是协作式的

在控制台点「停止」只会置位一个标志，不会强行打断脚本。长循环必须检查 shouldStop()，在它返回 true 时退出；sleep 和查找类函数的等待会在停止后立即返回。

错误按 code 判断

所有异常都带稳定的 code 字段，按 code 判断，不要匹配 message 文字 —— 文字是写给人看的，措辞会变。查找类函数找不到时返回 null 或 false，不抛异常；抛异常的是参数写错、设备或 WDA 出问题这类真正的错误。