必读:运行模型与硬性约束📌 运行环境与双端差异📌 ES Module 严格模式(市场脚本必读)📌 随机数:Math.random 跨运行重复市场脚本:发布、分发与依赖📌 发布流程与审核📌 加密分发(源码保护)📌 scriptDeps 依赖分发(多脚本 require)📌 目标应用绑定常见陷阱清单(实测结论)📌 click 坐标:双数字参数无效📌 aiTxt 的 count/distance/non 写对位置📌 inputText 静默失败与失败判定📌 findOne/waitFor 的 check 两阶段计时📌 选择器正则语法:text*= 裸写不包斜杠📌 aiTxt 选项必须作数组尾参📌 OCR 使用节奏:懒加载与卸载基础类型📘 Point📘 UiNodeArray📘 UiNodeGroupResult📘 ColorMatchArray📘 ImageMatchArray📘 MultiColorMatchArray📘 OcrResultArrayUI 节点📘 UiNode颜色查找结果📘 ColorMatch📘 MultiColorMatch图像查找结果📘 ImageMatchOCR 结果📘 OcrResultaiTxt 结果📘 AiTxtMatch📘 AiTxtResult📘 AiTxtReuseMiss📘 AiTxtOptions📘 FindOneOptions📘 FindAllOptions点击目标📘 ClickOptions线程相关类型📘 Thread📘 Atomic📘 Lock📘 Disposable📘 WindowInfo📘 SharedVarsapp 命名空间类型📘 PackageInfo📘 InstalledPackage📘 SendEmailOptionsdevice 命名空间类型📘 ScreenSize📘 ScreenshotInfoui 命名空间类型📘 FormField📘 FormSchemadb 命名空间类型📘 DbStats全局函数ƒ clickƒ longClickƒ swipeƒ dragƒ gestureƒ inputTextƒ pressKeyƒ backƒ homeƒ powerDialogƒ notificationsƒ quickSettingsƒ recentsƒ splitScreenƒ Homeƒ Backƒ Powerƒ Menuƒ VolumeUpƒ VolumeDownƒ Cameraƒ Upƒ Downƒ Leftƒ Rightƒ OKƒ Textƒ KeyCode屏幕 / UI 查询ƒ getScreenSizeƒ screenshotƒ dumpUiƒ dumpUiTree📘 WidgetCountResultƒ widgetCountƒ findOneƒ findAll颜色查找 (HSV)ƒ findColorƒ findAllColorsƒ findColorFastƒ checkPixelColorƒ getPixelColorƒ refreshScreenƒ waitForColorƒ waitForColorGone极致优化 API — Zero-Copy 截图、VFS、插件隔离ƒ getScreenDataƒ waitForColorEventƒ registerZipƒ requireZipƒ loadPluginƒ findMultiColorsƒ findAllMultiColors图像查找 (ORB 特征点匹配)ƒ findImageƒ findAllImagesOCR 文字识别ƒ ocrƒ ocrFindƒ waitFor📘 WaitForOptions📘 WaitForOcrResultƒ ocrSetModelƒ ocrGetModelƒ ocrInitaiTxt — 智能文本查找 (UI 优先 + OCR 回退)ƒ aiTxt全局信息查询ƒ currentPackageƒ currentActivityƒ currentComponent通用工具ƒ sleepƒ humanPauseƒ logƒ exitƒ pushUI定时器 (基于子线程)ƒ setTimeoutƒ setIntervalƒ clearTimeoutƒ clearInterval事件监听 (events 模块 — Toast / Notification)📘 ToastEvent📘 NotificationEvent📘 EventEmitterƒ sync数据库快捷函数 (config 命名空间)ƒ setKeyƒ getKeyƒ delKeyƒ withKeyLock坐标点管理 (setPosition)📘 CaptureOptionsƒ setPositionƒ getPositionƒ delPositionƒ listPositions滑动轨迹管理📘 SwipeTrackƒ setSwipeƒ delSwipeƒ listSwipesƒ replay摇杆管理📘 JoystickAreaƒ setJoystickƒ getJoystickƒ delJoystickƒ listJoysticks矩形区域管理 (setRect)📘 RectAreaƒ setRectƒ getRectƒ delRectƒ listRects动态区域 (setBox)📘 BoxConfigƒ setBoxƒ getBoxƒ delBoxƒ listBoxesƒ checkBox文本配置管理 (setConf)ƒ setConf控件点选(setWidget,4.0.8+)📘 WidgetOptions📘 WidgetPickƒ setWidgetƒ delWidgetƒ listWidgetssetChoose — 采集型选择(4.8.20+,setWidget 同款交互模型)📘 ChoosePick📘 ChooseRecord📘 SetChooseOptionsƒ setChooseƒ getChooseƒ delChoose弹窗规则执行(rulesDialog,4.1.7+)ƒ rulesDialogƒ getConfƒ delConfƒ listConfs📘 ConfirmDialogOptionsƒ showConfirmDialogƒ setActivity取色管理 (setColor)📘 ColorResult📘 SetColorOptionsƒ setColor📘 NearbyTextInfo📘 ColorRegion📘 MultiColorRef📘 CheckColorOptions📘 CheckColorResultƒ checkColorƒ getColorƒ delColorƒ listColors时间日期比较📘 CompTimeResultƒ compTimeapp 命名空间📦 appdevice 命名空间📦 deviceui 命名空间📦 uithreads 命名空间📦 threadsdb 命名空间 (ThetaDB)📘 DbApikeys 常量对象 (Android KeyEvent 键码)📦 keysbase64 命名空间 — Base64 编码/解码📦 base64http 命名空间 — HTTP 客户端📘 HttpRequestOptions📘 HttpResponseBody📘 HttpResponse📘 HttpRequestBuilder📦 httpqrcode 命名空间 — 二维码识别📘 QrcodeResult📦 qrcodeengine 命名空间 — 脚本引擎管理📘 EngineScriptResult📘 EngineStopResult📘 EngineStopAllResult📦 engine模块系统 — require() 加载 JS 模块📘 NodeModuleƒ requireƒ readFileƒ writeFile📦 require数据采集 (collectData)📘 DataCollectionField📘 CollectDataOptions📘 CollectDataResultƒ collectDataƒ queryDataƒ getDataCountƒ clearDataƒ deleteDataƒ exportDataƒ importDataƒ listDataSets可视化核对 (show*)ƒ showRectƒ showPositionƒ showColorƒ showSwipeƒ showJoystickƒ showOcr摇杆控制 (joystick)ƒ joystick摇杆队列(多线程安全的摇杆操作序列)ƒ joystickQueueƒ pauseJoystickƒ resumeJoystickƒ clearJoystickQueueƒ getJoystickQueueStatusƒ startJoystickWorker配置同步 (checkSettings / exportSettings / importSettings)ƒ checkSettingsƒ exportSettingsƒ importSettingsAPK 打包 (buildApk)ƒ buildApk

Auto Engine 开发者文档

JS 自动化脚本 API(安卓/Windows 双端)。API 签名由 tools/generate-dev-docs.mjs 从 .vscode/auto-engine.d.ts 与 flutter_app/assets/examples/ 自动生成; 「必读/市场/陷阱」章节在生成器 STATIC_CATS 中手工维护。改动数据源后重新执行该脚本并重建网关即可更新。

必读:运行模型与硬性约束

guide 运行环境与双端差异

脚本运行在设备端 Auto Engine 引擎(QuickJS)中,安卓真机为完整能力,Windows(ADB 连手机)为受限模式。 硬件相关 API(如 device.brand、device.model、传感器/屏幕常亮族)在 ADB 受限模式下 不抛错而是返回降级对象(形如 {success:false, error:"..."}),使用前先判断字段再消费,否则拿到的是降级载荷。 涉及无障碍树、截图、OCR 的 API 双端均可用的前提是无障碍服务已开启且已授权截屏。

guide ES Module 严格模式(市场脚本必读)

市场脚本由服务端编译为 QuickJS 字节码并以 ES Module(strict 模式)执行,引擎 API (console/click/aiTxt/…)由运行时注入,无需 import。strict 模式下:
  • 所有变量必须用 var/let/const 声明,隐式全局赋值(x = 1 未声明 x)编译即报错,脚本发布时会直接失败;
  • this 行为、八进制字面量、with 等 sloppy 语法不可用;
  • 本地能跑 ≠ 市场分发成功——本地引擎以普通脚本执行,发布后请用真实订阅账号在真机跑一次验证。

guide 随机数:Math.random 跨运行重复

引擎每次运行的随机序列是固定的(Math.random() 种子不随时间变化),依赖"每次随机"的逻辑 (抽卡、轮换账号等)会跨运行重复。需要真随机时用时间自播种,例如:
let seed = Date.now() % 2147483647;
function rnd() { seed = (seed * 48271) % 2147483647; return seed / 2147483647; }

市场脚本:发布、分发与依赖

guide 发布流程与审核

  1. 本地开发调试(VSCode 扩展提供 auto-engine.d.ts 全量类型提示);
  2. 发布:定价 price_cents ≥ 1(积分/天,已无永久免费档),试用时长 trial_hours 6-12 小时由作者设定;
  3. 发布后进入 pending 审核,管理员通过后才在市场可见;在架脚本更新代码会自动 patch 版本 +1 并重新进入审核;
  4. 购买按月计费(1-12 月),定价语义为积分/天,成交价 = 单价 × 30 × 月数,作者分成 80%;
  5. 每个脚本保留最近 3 个历史版本,可在控制台回看/回滚。

guide 加密分发(源码保护)

市场脚本的明文源码永不下发到设备:发布时服务端把源码编译为 QuickJS 字节码,以 AES-256-GCM 加密存储;任务下发时按目标设备包裹密钥(设备绑定),拷贝密文到其他设备无法解密。 这也意味着:反编译/抓包拿不到源码,同时脚本的执行环境由引擎版本决定—— 引擎升级字节码版本不兼容时,服务端按版本多并存分发,老 App 继续取老版本产物。

guide scriptDeps 依赖分发(多脚本 require)

主脚本可用 require("依赖脚本.js") 引用同作者的其他脚本,云端执行/市场分发时会沿引用链自动打包。 依赖经 /api/scripts/:id/code?key=access_key 远程拉取:
  • access_key 仅作者可见,泄露后可在控制台轮换(rotate-key,默认 14 天宽限期,旧 key 平滑过渡);
  • 轮换默认 auto_fix:服务端自动改写内嵌旧 URL 的主脚本源码并重编译,无需重新上传发布;
  • 被引用为依赖的 key 服务端每 30 天自动轮换(可用 ACCESS_KEY_AUTO_ROTATE_DAYS 调整,0 关闭)。

guide 目标应用绑定

发布脚本时可声明目标应用(包名)与版本要求;用户端启动脚本前读取设备上该应用的实际版本并比对, 不满足时拒绝执行。写脚本时请把自动化目标固定为单一应用,并在发布信息中如实声明包名/版本区间, 避免用户端版本不匹配导致的失败。

常见陷阱清单(实测结论)

guide click 坐标:双数字参数无效

⚠️ click(x, y) 双数字写法无效(引擎按"无效的参数类型 number"记日志跳过,不报错也不点击)。 d.ts 已删除该重载——此写法现在编译期直接报错。点击坐标一律用对象/数组形式:
click({ x: 540, y: 1200 });        // ✔
click([540, 1200]);                 // ✔ 坐标数组
click("开始游戏");                  // ✔ 文本点击
click(aiTxt("~=开始"), { check: true });  // ✔ aiTxt 结果 + 点击后验证
同理控件数组(UiNode[]/AiTxtMatch[])也不可直传——引擎会把它当坐标数组取前两位产生 NaN, 请传单个元素 click(arr[0]) 或 click(ret.data)。 坐标基于当前屏幕截图原点;屏幕旋转/分辨率变化后需重新获取,不要硬编码跨设备坐标。

guide aiTxt 的 count/distance/non 写对位置

这三个选项只认数组末尾 options 元素写法(引擎路由到 AND 模式):
aiTxt(["金币", "体力", { count: [2, 1], non: ["~=锁定"] }]);      // ✔ 末尾 options
aiTxt(["金币", "体力"], { region: ["lt", "rt"], count: [2, 1] }); // ✔ region 数组(AND 模式)
aiTxt(["金币", "体力"], { count: [2, 1] });  // ✖ 独立第二参数被引擎忽略(无声失效,d.ts 已禁止)
多组模式写在各组末尾: aiTxt([["t1","t2",{distance:[0,"min"]}]]); 外层末尾内联 options 只对 region/box/log/confidence 生效,其中的 count/distance/non 同样被忽略。 另: reuse: true 未命中返回 matched=false 的真值对象(不是 null), 判命中用 ret.matched !== false,不能用返回值判空。

guide inputText 静默失败与失败判定

输入前必须先点击聚焦输入框。无聚焦输入框时 inputText 可能静默失败仍返回 "ok"; 较新版本(4.0.5+)对可识别失败会抛错,有两种失败载荷形态(无焦点的 error 形态 / 拒绝 SET_TEXT 的仅 message 形态)。 稳妥写法 = try-catch + 输入后回读验证:
try {
    inputText("hello");
} catch (e) { /* 处理抛错 */ }
// 回读验证(以实际控件 API 为准),不一致则重试或改用剪贴板粘贴方案

guide findOne/waitFor 的 check 两阶段计时

带 check 的查找是两阶段计时:先在 timeout 内等出现,再连续 disappearCheck 次确认消失,总时限 ≈ timeout + (checkRetry+1) × checkWait。 checkWait 是每次检查前的等待(默认 500ms),不是总等待——把 checkWait 当总超时调大 会让消失判定变得极慢。

guide 选择器正则语法:text*= 裸写不包斜杠

findOne/waitFor 条件里的正则操作符(text*=部分匹配)裸写字符串,不包斜杠; re=/…/ 斜杠形式仅用于 aiTxt 选项:
findOne("text*=开始.*任务");          // ✔ 裸写
aiTxt(..., { re: /\d{4}/ });        // ✔ aiTxt 用斜杠
正则不匹配时静默返回 false/空,不报错。屏幕上明明可见却匹配不上 = 无障碍树里没有该 text: 用 aiTxt(..., { log: true }) 看树里实际文本;纯图片文字(画布/游戏内嵌字)无障碍树拿不到, 改用 waitFor({ mode: "ocr", ... })。

guide aiTxt 选项必须作数组尾参

count/distance 等选项对象只认"作为数组最后一个元素"的写法,独立第二参数会无声失效:
aiTxt("领取", [{ count: 3 }]);          // ✔ 取 3 个
aiTxt("领取", { count: 3 });            // ✘ 无声失效(被当匹配条件)

guide OCR 使用节奏:懒加载与卸载

OCR 模型占内存较大,按懒加载设计:首次 ocr()/ocrFind() 时自动初始化; 纯 OCR 阶段结束后调用 ocrRelease() 卸载释放内存。长时间循环脚本注意: 初始化失败时先查模型文件是否就绪(首次会下载),不要在循环里反复重试初始化。

基础类型

interface Point

坐标点
📋 类型定义原文
interface Point {
    x: number;
    y: number;
}

interface UiNodeArray

UiNode 数组 (附带链式 .region() 方法)
字段类型说明
regionRegionFilter<UiNodeArray> 链式区域过滤:返回在指定区域内的子数组
📋 类型定义原文
interface UiNodeArray extends Array<UiNode> {
}

interface UiNodeGroupResult

findAll 多组模式返回的结果对象
字段类型说明
groupIndexnumber 匹配组的索引(从 0 开始,-1 不会被返回——全未命中时返回 null)
selectorsstring[] 该组的选择器表达式数组
matchesUiNode[][] 二维数组:matches[i] 对应 selectors[i] 的所有匹配节点
📋 类型定义原文
interface UiNodeGroupResult {
}

interface ColorMatchArray

ColorMatch 数组 (附带链式 .region() 方法)
📋 类型定义原文
interface ColorMatchArray extends Array<ColorMatch> {
    region: RegionFilter<ColorMatchArray>;
}

interface ImageMatchArray

ImageMatch 数组 (附带链式 .region() 方法)
📋 类型定义原文
interface ImageMatchArray extends Array<ImageMatch> {
    region: RegionFilter<ImageMatchArray>;
}

interface MultiColorMatchArray

MultiColorMatch 数组 (附带链式 .region() 方法)
📋 类型定义原文
interface MultiColorMatchArray extends Array<MultiColorMatch> {
    region: RegionFilter<MultiColorMatchArray>;
}

interface OcrResultArray

OcrResult 数组 (附带链式 .region() 方法)
📋 类型定义原文
interface OcrResultArray extends Array<OcrResult> {
    region: RegionFilter<OcrResultArray>;
}

UI 节点

interface UiNode

UI 控件节点
字段类型说明
idstring | null 控件 ID(通常为 null)
textstring | null 文本内容(无文本时为 null)
descstring | null 描述文本(无描述时为 null)
typestring 节点类型 (node_type)
boundsBounds 边界 [left, top, width, height]
center?Center 中心点 [cx, cy]。
注意:原始 dumpUiTree 节点可能没有该字段(可由 bounds 计算:
cx = bounds[0] + bounds[2]/2, cy = bounds[1] + bounds[3]/2),
引擎内部取坐标时也会自动从 bounds 计算
clickableboolean 是否可点击
scrollableboolean 是否可滚动
enabledboolean 是否启用
packagestring 包名
class_namestring | null 类名。
字段名说明:引擎直出的控件树为 snake_case 的 class_name
(serde 序列化 schema,与 dumpUiTree 输出一致);
部分桌面/兼容路径序列化为 className。两者取其一,建议用 class_name
className?string | null 类名(camelCase 别名,仅部分兼容路径存在)
focusableboolean | null 是否可聚焦
focusedboolean | null 是否已聚焦
checkableboolean | null 是否可勾选
checkedboolean | null 是否已勾选
selectedboolean | null 是否已选中
long_clickableboolean | null 是否可长按
longClickable?boolean | null 是否可长按(camelCase 别名,仅部分兼容路径存在)
passwordboolean | null 是否密码框
visible_to_userboolean | null 是否对用户可见
visibleToUser?boolean | null 是否对用户可见(camelCase 别名,仅部分兼容路径存在)
parent_classstring | null 父控件类名
parentClass?string | null 父控件类名(camelCase 别名,仅部分兼容路径存在)
depthnumber | null 树深度(根节点为 0)
index_in_parentnumber | null 在父节点中的索引(原始树中常为 null,JS 层会另算 indexInParent)
indexInParent?number 在父节点中的索引(JS 层遍历子节点时计算并追加,子节点始终可用)
drawing_ordernumber | null 绘制顺序
drawingOrder?number | null 绘制顺序(camelCase 别名,仅部分兼容路径存在)
accessibility_focusedboolean | null 是否已获得无障碍焦点
dismissableboolean | null 是否可消失(如 Toast)
editableboolean | null 是否可编辑
multi_lineboolean | null 是否多行文本
content_invalidboolean | null 内容是否失效
context_clickableboolean | null 是否可长按弹出上下文菜单
columnnumber | null 网格布局列索引(无值时为 null)
column_countnumber | null 网格布局列数(无值时为 null)
column_spannumber | null 网格布局列跨度(无值时为 null)
rownumber | null 网格布局行索引(无值时为 null)
row_countnumber | null 网格布局行数(无值时为 null)
row_spannumber | null 网格布局行跨度(无值时为 null)
children?UiNode[] 子节点数组(findOne/findAll/dumpUiTree 返回的节点均包含)
regionRegionFilter<UiNode | null> 链式区域过滤:返回在指定区域内的本节点(不在区域内返回 null)
📋 类型定义原文
interface UiNode {
    parent(n?: number): UiNode | null;
    child(i: number): UiNode | null;
}

颜色查找结果

interface ColorMatch

单个颜色匹配结果
字段类型说明
xnumber 匹配区域质心 X 坐标
ynumber 匹配区域质心 Y 坐标
wnumber 外接矩形宽度
hnumber 外接矩形高度
areanumber 匹配像素面积
regionRegionFilter<ColorMatch | null> 链式区域过滤
📋 类型定义原文
interface ColorMatch {
}

interface MultiColorMatch

多点找色结果
字段类型说明
xnumber 锚点 X 坐标
ynumber 锚点 Y 坐标
regionRegionFilter<MultiColorMatch | null> 链式区域过滤
📋 类型定义原文
interface MultiColorMatch {
}

图像查找结果

interface ImageMatch

单个图像匹配结果
字段类型说明
xnumber 匹配中心 X 坐标
ynumber 匹配中心 Y 坐标
confidencenumber 置信度 0.0~1.0 (匹配特征点数 / 20)
regionRegionFilter<ImageMatch | null> 链式区域过滤
📋 类型定义原文
interface ImageMatch {
}

OCR 结果

interface OcrResult

OCR 识别结果
字段类型说明
textstring 识别文本
confidencenumber 置信度 0~1
bboxBounds 边界框 [x, y, w, h]
centerCenter 中心点 [cx, cy]
regionRegionFilter<OcrResult[]> 链式区域过滤
📋 类型定义原文
interface OcrResult {
}

aiTxt 结果

interface AiTxtMatch

aiTxt 单条匹配(主匹配 data / matched 数组元素的类型)
字段类型说明
textstring | null 匹配到的文本
desc?string | null 描述文本(仅选择器模式附带)
centerCenter | null 中心点 [cx, cy]
bounds?Bounds 边界框 [x, y, w, h](仅选择器模式附带)
source"ui" | "ocr" | null 来源: 'ui' (无障碍控件) 或 'ocr' (文字识别)
confidence?number | null 置信度 (仅 source='ocr' 时存在)
📋 类型定义原文
interface AiTxtMatch {
}

interface AiTxtResult

aiTxt 统一返回对象 — 所有模式(单文本 / 多文本查找 / AND / 多组 / pair / box / 选择器)
都返回同一结构,只是各字段的值随模式不同;未匹配返回 null。
常用姿势:
- ret.text / ret.center / ret.source — 主匹配信息(便捷透传)
- click(ret) 或 click(ret.data) — 直接点击主匹配
- ret.index — 命中的文本/组索引
- ret.matched / ret.matchedByIndex — AND、count/distance 模式的全部命中
- ret.base / ret.other / ret.score — pair 模式配对信息
字段类型说明
indexnumber 命中索引:单文本/AND/多文本查找/box 恒为 0;多组/pair 模式为命中的组索引(按传入顺序)
dataAiTxtMatch 主匹配结果,可直接传给 click(ret.data)
matchedAiTxtMatch[] 全部命中(恒有 matched[0] === data):
- 单文本/选择器: 区域内全部候选
- AND 模式: 各文本的首个匹配(顺序与传入文本一致)
- 多组模式: 命中组内的全部匹配
- pair 模式: [主匹配]
textstring | null 匹配到的文本(= data.text,便捷透传)
centerCenter | null 中心点 [cx, cy](= data.center,click(ret) 直接可用)
source"ui" | "ocr" | null 来源: 'ui' (无障碍控件) 或 'ocr' (文字识别)
confidencenumber | null OCR 置信度 0~1(仅 source='ocr' 时非 null)
matchedByIndex?AiTxtMatch[][] count/distance 模式:按文本索引分组的匹配结果(其他模式不存在)
base?string pair 模式:配对基准关键词
other?string | null pair 模式:与基准配对的关键词(无配对时为 null)
score?number pair 模式:本次得分(score 模式下为组合总分)
pairIndex?number pair 模式:配对索引(基准单独匹配时为 -1)
matchedText?string | null pair 模式:最佳配对命中的文本(= data.text)
matchedItems?Array<{ base: string; other: string | null; score: number; groupIndex: number; pairIndex: number; isBaseOnly: boolean }> pair+score 模式:全部配对明细
__texts?Array<{ text: string; center: Center; source: "ui" | "ocr" }> pair 模式:本次查找的全部屏幕文本池(可回传 texts 选项复用,跳过二次截图)
groupIndexnumber 兼容别名 = index(旧版多组模式字段名)
firstAiTxtMatch 兼容别名 = data
node?UiNode 选择器模式("text=xxx" 等写法):命中的原始 UiNode
📋 类型定义原文
interface AiTxtResult {
    region(regionExpr: RegionExpr): AiTxtResult | AiTxtMatch | null;
}

interface AiTxtReuseMiss

aiTxt(reuse: true) 未命中时返回的真值对象(⚠ 不是 null!):
只有非枚举的 matched=false 与 __texts 文本池两个字段,text/center/data 等均为 undefined。
判断命中必须用 ret.matched !== false(或 ret.text != null),不能用返回值判空
字段类型说明
centerundefined @deprecated 未命中对象上恒为 undefined
__textsArray<{ text: string; center: Center; source: "ui" | "ocr" }> 本次收集的屏幕文本池(UI+OCR),可回传 texts 选项复用
📋 类型定义原文
interface AiTxtReuseMiss {
    matched: false;
    text: undefined;
    source: undefined;
    data: undefined;
}

interface AiTxtOptions

aiTxt AND 模式的 options 参数
字段类型说明
count?number[] 每个文本需要选取的匹配数量,默认 [1, 1, ...]
注意: count 大于实际匹配数时返回最大可用数量,不返回 null
distance?[number, "min" | "max"] [基准文本索引, 距离模式]:'min' 选最近,'max' 选最远
non?string | string[] 排除文本:如果屏幕上存在任一排除文本,则返回 null
支持单个字符串或字符串数组,支持匹配前缀语法,包括正则 "re=/pattern/flags"
region?RegionExpr | RegionExpr[] 搜索区域限制(RegionExpr):
- 单区域: "top"/"bottom" 或 setRect 返回的区域对象,作用于所有文本
- 区域数组(AND 多文本模式下按文本一一对应): [nameRect, energyRect]
box?BoxConfig | string | null 动态锚点框(setBox 返回的配置对象或键名,允许传 null 表示未配置),在此框内搜索文本
click?boolean 找到后自动点击匹配元素(使用 center 坐标)
check?boolean | (string | AiTxtOptions)[] 点击后验证(隐含 click,无需另写 click: true):
- true: 保存原始坐标,点击后重新查找,坐标相同→重试点击,未找到或坐标不同→成功
- [text, region?, options?]: 点击后查找 text,找到且无 options → 原结果(仅验证);
未找到 → 重新点击原始元素重试;有 options.click → 点击 text;有 options.check → 点击+坐标验证重试
注意:TS 中数组字面量会被推断为联合类型数组而非元组,因此使用宽松数组类型
checkWait?number check 等待时间(ms),默认 500
checkRetry?number disappear 模式最大重试次数,默认 3
log?boolean | string 输出搜索过程日志(UI 文本 + OCR 文本),默认 false;
传字符串则在匹配成功时额外输出该提示文本
confidence?number OCR 结果最低置信度阈值 (0~1),低于此值的 OCR 匹配将被过滤
仅影响 source='ocr' 的结果,不影响 source='ui' 的结果
默认 0(不过滤)
@example
// 只返回置信度大于 0.8 的 OCR 结果
aiTxt("设置", {confidence: 0.8});
pair?boolean pair 配对模式:多组数组中每组第一个元素与剩余元素逐一配对,
检测同一条识别文本中是否同时包含配对关键词
score?number[] pair+score 模式:为每组指定基准得分,按组合总分选择最佳匹配
texts?Array<{ text: string; center: Center; source: "ui" | "ocr" }> 文本池复用:传入前一次 pair/aiTxt 结果的 __texts,跳过截图和 OCR
reuse?boolean 复用上一次查找的截图/控件树缓存(同屏多次查找时提速)
inScreen?boolean 要求匹配结果完整落在屏幕内(严格 4 角几何 + visibleToUser 可见性双判定),
剔除屏幕边缘被裁切的半截文本和离屏 WebView 节点——这类结果 region 过滤
能命中但点击落空。
生效范围:单文本/选择器/多文本查找/AND 模式;多组/pair 模式不适用
📋 类型定义原文
interface AiTxtOptions {
}

interface FindOneOptions

findOne 的 options 参数(与 AiTxtOptions 子集一致)
字段类型说明
region?RegionExpr 搜索区域限制(RegionExpr),如 "top"/"bottom" 或 setRect 返回的区域对象
timeout?number 查找超时时间(ms),默认 0(单次查找)
click?boolean 找到后自动点击匹配元素(使用 center 坐标)
check?boolean | (string | FindOneOptions)[] 点击后验证(隐含 click):
- true: 保存原始坐标,点击后重新查找,坐标相同→重试点击,未找到或坐标不同→成功
- [text, region?, options?]: 点击后查找 text,找到且无 options → 原结果(仅验证);
未找到 → 重新点击原始元素重试;有 options.click → 点击 text;有 options.check → 点击+坐标验证重试
注意:TS 中数组字面量会被推断为联合类型数组而非元组,因此使用宽松数组类型
checkWait?number check 等待时间(ms),默认 500
checkRetry?number disappear 模式最大重试次数,默认 3
log?boolean | string 输出查找过程日志;传字符串则在匹配成功时额外输出该提示文本
📋 类型定义原文
interface FindOneOptions {
}

interface FindAllOptions

findAll 的 options 参数
字段类型说明
region?RegionExpr 搜索区域限制(RegionExpr),如 "top"/"bottom" 或 setRect 返回的区域对象
non?string | string[] 排除文本:如果屏幕上存在任一排除文本(UI 控件树 + OCR 二次确认),则返回 null
支持字符串或字符串数组,支持 aiTxt 匹配前缀语法(= 精确, ~= 包含, ^= 前缀, $= 后缀, re= 正则)
也支持 findAll 选择器语法(text~=, desc=, id~=, ...),属性名前缀会被自动剥离
log?boolean | string 输出查找过程日志;传字符串则在匹配成功时额外输出该提示文本
click?boolean 找到后自动点击所有匹配控件(使用 center 坐标)
check?boolean | (string | FindAllOptions)[] 点击后验证(隐含 click,无需另写 click: true):
- true: 保存原始坐标,点击后重新查找所有匹配:
全部消失(count=0)或全部坐标变化 → 成功;
仍有匹配且坐标相同 → 重新点击剩余控件,重试
- [selector, region?]: 点击后查找 selector,找到 → 成功;
未找到 → 重新查找并点击所有原始控件,重试
注意:TS 中数组字面量会被推断为联合类型数组而非元组,因此使用宽松数组类型
checkWait?number check 等待时间(ms),默认 500
checkRetry?number check 最大重试次数,默认 3
📋 类型定义原文
interface FindAllOptions {
}

点击目标

interface ClickOptions

click 选项
字段类型说明
pkg?string 限定目标控件的 packageName(支持 "re=正则" 前缀)
act?string 限定目标控件的 className 或 Activity(支持 "re=正则" 前缀)
check?boolean | string | (string | ClickOptions | AiTxtOptions)[] 点击后验证:
- true: 点击后验证目标是否消失(坐标变化/未找到)
- "文本" 或 ["~=文本", region?, options?]: 点击后查找该文本是否出现;
数组末尾的对象元素为 aiTxt 选项写法,如 {region: "lt"}
checkWait?number check 每次检查前等待时间(ms),默认 500
checkRetry?number check 最大重试次数,默认 3
📋 类型定义原文
interface ClickOptions {
}

线程相关类型

interface Thread

线程对象
字段类型说明
_idnumber 线程 ID (主线程为 0)
_aliveboolean 是否存活
📋 类型定义原文
interface Thread {
    interrupt(): void;
    isAlive(): boolean;
    waitFor(): "ok";
    join(timeout?: number): "ok";
    stop(timeout?: number): "ok";
    setTimeout(callback: Function, delay: number): number;
    setInterval(callback: Function, delay: number): number;
}

interface Atomic

原子整数对象 (线程安全)
📋 类型定义原文
interface Atomic {
    get(): number;
    set(v: number): void;
    getAndIncrement(): number;
    incrementAndGet(): number;
    getAndDecrement(): number;
    decrementAndGet(): number;
    addAndGet(delta: number): number;
    getAndAdd(delta: number): number;
    compareAndSet(expect: number, update: number): boolean;
    toString(): string;
}

interface Lock

可重入锁对象
📋 类型定义原文
interface Lock {
    lock(): void;
    unlock(): void;
    tryLock(): boolean;
    isLocked(): boolean;
}

interface Disposable

一次性结果传递对象
📋 类型定义原文
interface Disposable {
    blockAndGet(timeout?: number): any;
    setResult(result: any): void;
    setError(error: any): void;
    isSet(): boolean;
}

interface WindowInfo

应用窗口信息(app.windows() 返回项,分屏多窗口用)
字段类型说明
idstring 窗口 id(bindWindow/pauseWindow 等用)
packagestring 窗口所属应用包名
bounds[number, number, number, number] 窗口区域 [x, y, w, h]
activeboolean 是否活跃窗口
focusedboolean 是否持有焦点
📋 类型定义原文
interface WindowInfo {
}

interface SharedVars

📋 类型定义原文
interface SharedVars {
    set(key: string, value: any): "ok";
    get<T = any>(key: string, defaultValue?: T): T | null;
    has(key: string): boolean;
    delete(key: string): boolean;
    incr(key: string, delta?: number): number;
    clear(): "ok";
}

app 命名空间类型

interface PackageInfo

应用信息 (详细)
📋 类型定义原文
interface PackageInfo {
    packageName: string;
    appName: string;
    versionName: string;
    versionCode: number;
    firstInstallTime: number;
    lastUpdateTime: number;
    sourceDir: string;
    dataDir: string;
    enabled: boolean;
    isSystem: boolean;
}

interface InstalledPackage

应用信息 (列表项)
📋 类型定义原文
interface InstalledPackage {
    packageName: string;
    appName: string;
    versionName: string;
    versionCode: number;
    isSystem: boolean;
}

interface SendEmailOptions

发送邮件选项
字段类型说明
email?string | string[] 收件人
cc?string | string[] 抄送
bcc?string | string[] 密送
subject?string 主题
text?string 正文
📋 类型定义原文
interface SendEmailOptions {
}

device 命名空间类型

interface ScreenSize

屏幕尺寸
📋 类型定义原文
interface ScreenSize {
    width: number;
    height: number;
}

interface ScreenshotInfo

截图信息
📋 类型定义原文
interface ScreenshotInfo {
    width: number;
    height: number;
    size: number;
}

ui 命名空间类型

interface FormField

表单字段定义
字段类型说明
keystring 字段键名 (必填)
labelstring 显示标签 (必填)
type"string" | "number" | "boolean" | "select" | "multiselect" | "password" 字段类型
default?any 默认值
placeholder?string 占位文本
options?Array<string | { value: any; label: string }> select/multiselect 选项
min?number number 最小值
max?number number 最大值
required?boolean 是否必填,默认 false
📋 类型定义原文
interface FormField {
}

interface FormSchema

表单 Schema
字段类型说明
title?string 表单标题,默认 '配置'
fieldsFormField[] 字段列表 (必填)
📋 类型定义原文
interface FormSchema {
}

db 命名空间类型

interface DbStats

数据库统计信息
📋 类型定义原文
interface DbStats {
    namespaces: { [ns: string]: number };
    totalKeys: number;
    path: string;
}

全局函数

func click

declare function click(target: ClickTarget): "ok" | false
declare function click(target: ClickTarget, options: ClickOptions): "ok" | false
智能点击 — 模拟真实人类操作
随机偏移 ±5px、随机前置延迟 30~100ms、微距离滑动 50~150ms。
底层使用 shell input swipe,不依赖无障碍服务,失败时回退到 dispatchGesture。
@param target 点击目标,支持多种形式:
- click({x, y}) 坐标点击(⚠ click(x, y) 双数字写法无效,引擎静默跳过)
- click("文本") 按 text/desc 查找控件点击
- click(aiTxt("文本")) aiTxt 结果点击
- click(uiNode) 控件对象点击
- click([x, y]) 坐标数组
@returns "ok"(成功);目标为 null、文本未找到、类型无效、pkg/act 不匹配、
check 验证失败或内部异常时返回 false(引擎捕获后记日志,不抛错)
📄 示例:002_click.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// click(target, options?)
// ============================================================

// --- click(target, options?) ---
// 智能点击(模拟真实人类行为:随机偏移±5px + 随机前置延迟30~100ms)。
// 参数:
//   target 支持多种类型:
//     click([x, y])            — 坐标数组
//     click({x: n, y: n})      — 坐标对象
//     click("文本")             — 按文本查找(aiTxt: UI + OCR 回退)后点击中心
//     click(aiTxt("文本"))      — 直接传 aiTxt 返回的对象,自动提取 center
//     click(uiNode)            — 控件对象,点击 center 字段
//   options (object, 可选) — 最后一个参数,对象类型:
//     {pkg: "com.example"}     — 仅当前台包名匹配时才执行点击,否则跳过返回 false
click([500, 1000]);                        // 坐标点击
click("登录");                              // 文本查找后点击
click(aiTxt("设置"));                        // 直接传 aiTxt 结果
click({x: 500, y: 1000});                  // 坐标对象

// 包名限制:仅在前台为指定包名时才执行点击
var ret = aiTxt("确定");
click(ret, {pkg: "com.mm.td"});            // 仅在前台为 com.mm.td 时点击
click([500, 800], {pkg: "com.mm.td"});     // 坐标点击 + 包名限制
click("设置", {pkg: "com.mm.td"});          // 文本点击 + 包名限制

// check 选项:点击后验证(三种模式)
// 用法: click(target, {check: true | 文本 | 数组, checkWait?: ms, checkRetry?: 次数})
//   check: true                       — 验证被点击的元素是否消失(坐标变化或未找到)
//                                        从 target 提取文本和坐标,点击后重新查找
//                                        未消失则重新点击,最多重试 checkRetry 次
//   check: "每日任务"                  — 点击后查找"每日任务"是否出现(全屏)
//                                        未找到则重新点击
//   check: ["~=每日任务", "top"]       — 点击后在 top 区域查找
//   check: ["~=每日任务", {region: "top"}] — 同上,options 写法
//   checkWait: 检查前等待(ms),默认 500
//   checkRetry: 最大重试次数,默认 3
// 返回: 验证通过 "ok",验证失败 false

// check: true — 验证元素是否消失(适用于弹窗关闭、按钮点击后消失等场景)
// 从 target 对象中提取 text/desc 和坐标,点击后重新查找
var ret = aiTxt("确定");
click(ret, {check: true});  // 点击"确定"后验证它是否消失
// 等价于 aiTxt 的 check: true,但直接在 click 中完成

// 多组模式下对匹配组的结果使用 check: true
var groups = aiTxt([["~=去完成", "~=完成奖励"]]);
if (groups) {
  click(groups.data, {check: true});
}

// check: "文本" — 验证指定文本是否出现
var que_pos = [540, 960];  // 示例坐标(每日任务入口,实际用 setRect/setPosition 采集)

var ok = click(que_pos, {check: "每日任务"});
if (ok) {
  log("点击成功,每日任务已出现");
} else {
  log("点击后未找到每日任务");
}

// 点击后在 top 区域检查
click(que_pos, {check: ["~=每日任务", "top"]});

// 点击后在 top 区域检查,自定义等待和重试
click(que_pos, {
  check: ["~=每日任务", {region: "top"}],
  checkWait: 1000,   // 每次检查前等 1 秒
  checkRetry: 5      // 最多重试 5 次
});

// 结合 pkg 限制 + check 验证
click(que_pos, {
  pkg: "com.mm.td",
  check: ["~=每日任务", "top"],
  checkWait: 800,
  checkRetry: 4
});

func longClick

declare function longClick(target: ClickTarget, options?: { duration?: number }): any
智能长按
@param target 同 click 参数(坐标/文本/对象/数组)
@param options.duration 长按时长(毫秒),默认 1000
📄 示例:003_longClick.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// longClick(target, options?)
// ============================================================

// --- longClick(target, options?) ---
// 智能长按(模拟真实人类行为:随机偏移±4px + 随机前置延迟50~150ms)。
// 参数:
//   target 同 click: 坐标/文本/对象/数组
//   options (object, 可选) — {duration: 毫秒},默认 1000
longClick([500, 1000]);                    // 坐标长按,默认 1000ms
longClick([500, 1000], {duration: 2000});  // 坐标长按 2000ms
longClick("设置");                          // 文本查找后长按
longClick(aiTxt("设置"));                   // 直接传 aiTxt 结果
longClick(aiTxt("设置"), {duration: 1500}); // aiTxt 结果 + 自定义时长

func swipe

declare function swipe(path: [Point, Point] | number[][], options?: { duration?: number }): "ok"
滑动手势(模拟真实人类行为,随机偏移 + 非匀速)
@example swipe([[500, 1500], [500, 500]], {duration: 800});
@param path 起终点坐标数组 [[x1, y1], [x2, y2]]
@param options.duration 持续时间(毫秒),默认 500
@returns "ok"
📄 示例:004_swipe.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// swipe(path, options?)
// ============================================================

// --- swipe(path, options?) ---
// 滑动手势(模拟真实人类行为:随机偏移±3px + 随机前置延迟30~80ms)。
// 参数:path [[x1,y1],[x2,y2]] (int), options (object, 可选) — {duration: 毫秒},默认 500
swipe([[500, 1500], [500, 500]], {duration: 500});     // 快速向上滑动 500ms
swipe([[500, 500], [500, 1500]], {duration: 1000});    // 缓慢向下滑动 1000ms
swipe([[100, 1000], [900, 1000]], {duration: 300});     // 快速向右滑动 300ms

func drag

declare function drag(path: [Point, Point] | number[][], options?: { duration?: number }): any
按下拖拽(模拟真实人类行为)
@example drag([[500, 1000], [500, 500]], {duration: 600});
@param path 起终点坐标数组 [[x1, y1], [x2, y2]](传位置数字会直接抛错)
@param options.duration 持续时间(毫秒),默认 500
📄 示例:005_drag.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// drag(path, options?)
// ============================================================

// --- drag(path, options?) ---
// 按下拖拽(模拟真实人类行为:随机偏移±3px + 随机前置延迟30~80ms)。
// 与 swipe 的区别:drag 更强调按住后拖拽,底层使用 shell input swipe。
// 参数:path [[x1,y1],[x2,y2]] (int), options (object, 可选) — {duration: 毫秒},默认 500
drag([[500, 1000], [500, 500]], {duration: 3800});      // 向上拖拽
drag([[100, 500], [900, 500]], {duration: 3600});       // 向右拖拽

func gesture

declare function gesture(points: Array<[number, number]>, options?: { duration?: number }): any
自定义手势路径(模拟真实人类行为)
@param points 路径点序列,至少 2 个点
@param options.duration 总持续时间(毫秒),默认 500
📄 示例:006_gesture.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// gesture(points, options?)
// ============================================================

// --- gesture(points, options?) ---
// 自定义手势路径(模拟真实人类行为:随机偏移±2px + 随机前置延迟30~80ms)。
// 参数:
//   points (array) — 路径点序列 [[x,y], [x,y], ...],至少 2 个点
//   options (object, 可选) — {duration: 毫秒},默认 500
gesture([[100, 500], [500, 500], [900, 500]], {duration: 600});           // 三点折线
gesture([[500, 1500], [500, 1000], [600, 800], [600, 500]], {duration: 1000}); // 曲线路径

func inputText

declare function inputText(text: string): "ok"
向当前聚焦的输入框输入文本
@param text 文本内容
@returns "ok"
📄 示例:007_inputText.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// inputText(text)
// ============================================================

// --- inputText(text) ---
// 向当前聚焦的输入框输入文本。参数:text (string),无默认值。
inputText("Hello World");

func pressKey

declare function pressKey(keyCode: string): "ok"
模拟系统按键 (shell input 方式,不依赖无障碍服务)
@param keyCode 按键名: back | home | recent | recents | notifications | quick_settings | power_dialog | take_screenshot | volume_up | volume_down
@returns "ok"
📄 示例:008_pressKey.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// pressKey(keyCode)
// ============================================================

// --- pressKey(keyCode) ---
// 模拟系统按键。参数:keyCode (string),无默认值。
// 支持的按键:back, home, recent, recents, notifications,
//             quick_settings, power_dialog, take_screenshot,
//             volume_up, volume_down
pressKey("back");
pressKey("home");
pressKey("recent");
pressKey("recents");          // 同 recent
pressKey("notifications");
pressKey("quick_settings");
pressKey("power_dialog");
pressKey("take_screenshot");  // 需要 Android 11+
pressKey("volume_up");
pressKey("volume_down");

func back

declare function back(): boolean
模拟返回键 (无障碍服务方式) @returns 是否成功

func home

declare function home(): boolean
模拟 Home 键 (无障碍服务方式) @returns 是否成功

func powerDialog

declare function powerDialog(): boolean
打开电源对话框 @returns 是否成功

func notifications

declare function notifications(): boolean
打开通知栏 @returns 是否成功

func quickSettings

declare function quickSettings(): boolean
打开快速设置 @returns 是否成功

func recents

declare function recents(): boolean
打开最近任务 @returns 是否成功

func splitScreen

declare function splitScreen(): boolean
进入分屏模式 @returns 是否成功

func Home

declare function Home(): "ok"
大写开头的按键函数 (Root / pressKey 方式) @returns "ok"

func Back

declare function Back(): "ok"

func Power

declare function Power(): "ok"

func Menu

declare function Menu(): "ok"

func VolumeUp

declare function VolumeUp(): "ok"

func VolumeDown

declare function VolumeDown(): "ok"

func Camera

declare function Camera(): "ok"

func Up

declare function Up(): "ok"

func Down

declare function Down(): "ok"

func Left

declare function Left(): "ok"

func Right

declare function Right(): "ok"

func OK

declare function OK(): "ok"

func Text

declare function Text(text: string): "ok"
输入文本 (Root 方式),等价于 inputText(text)
@returns "ok"

func KeyCode

declare function KeyCode(code: number | string): boolean
通过键码模拟按键
@param code 数字(Android KeyEvent 键码) 或字符串(按键名)
@returns 是否成功
📄 示例:101_KeyCode.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 9. Keys 模块(按键模拟)
// KeyCode(code) — 通过键码模拟按键
// ============================================================

// --- KeyCode(code) — 通过键码模拟按键 ---
// 参数:code (number|string)
//   如果是数字,通过 Android KeyEvent 键码模拟
//   如果是字符串,通过按键名称模拟
// 返回 boolean。
// 示例1: 通过数字键码
KeyCode(3);    // KEYCODE_HOME
KeyCode(4);    // KEYCODE_BACK
KeyCode(24);   // KEYCODE_VOLUME_UP
KeyCode(25);   // KEYCODE_VOLUME_DOWN
KeyCode(66);   // KEYCODE_ENTER

// 示例2: 通过按键名称
KeyCode("home");
KeyCode("back");
KeyCode("volume_up");
KeyCode("volume_down");
KeyCode("enter");

屏幕 / UI 查询

func getScreenSize

declare function getScreenSize(): ScreenSize
获取屏幕尺寸
@returns {width, height}
📄 示例:011_getScreenSize.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 2. 屏幕信息
// getScreenSize()
// ============================================================

// --- getScreenSize() ---
// 获取屏幕尺寸。无参数。返回 {width: int, height: int}。
var size = getScreenSize();
log("屏幕尺寸: " + size.width + "x" + size.height);

func screenshot

declare function screenshot(): ScreenshotInfo
截图信息
@returns {width, height, size} (size 为字节数)
📄 示例:012_screenshot.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 2. 屏幕信息
// screenshot()
// ============================================================

// --- screenshot() ---
// 获取截图信息。无参数。返回 {width: int, height: int, size: int}。
var shot = screenshot();
log("截图: " + shot.width + "x" + shot.height + ", 数据大小=" + shot.size + " 字节");

func dumpUi

declare function dumpUi(): string
获取 UI 树 JSON 字符串 (pretty 格式)
📄 示例:013_dumpUi.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 3. UI 控件操作
// dumpUi()
// ============================================================

// --- dumpUi() ---
// 获取完整 UI 控件树。无参数。返回 JSON 字符串。
var uiTree = dumpUi();
log("UI 树: " + uiTree.substring(0, 200));

func dumpUiTree

declare function dumpUiTree(): any
获取 UI 树对象 (compact,已 JSON.parse)

interface WidgetCountResult

widgetCount() 返回的节点统计结果
字段类型说明
totalnumber 总节点数(包含根节点,等于 parents + leaves)
parentsnumber 父节点数(有至少一个子节点的节点)
leavesnumber 子节点数(叶子节点,无子节点)
📋 类型定义原文
interface WidgetCountResult {
}

func widgetCount

declare function widgetCount(): WidgetCountResult
统计当前界面的 UI 节点数量
复用 dumpUiTree 采集整棵控件树并递归统计:
- total — 总节点数(包含根节点)
- parents — 父节点数(有至少一个子节点的节点)
- leaves — 子节点数(叶子节点,无子节点)
适用场景:
- 判断界面复杂度(如检测是否进入新页面、列表是否加载完成)
- 等待界面稳定(轮询直到 total 不再变化)
- 对比不同状态下的控件数量差异
性能:与 dumpUiTree 共用一次原生调用,统计在 JS 侧递归完成,
1000 节点 < 5ms,不会阻塞脚本。
@returns 节点统计结果,无控件树时返回 {total:0, parents:0, leaves:0}
@example
```js
var c = widgetCount();
console.log(c.total); // 156 — 总节点数
console.log(c.parents); // 42 — 父节点数
console.log(c.leaves); // 114 — 叶子节点数
// 等待列表加载完成(节点数稳定)
var last = -1;
while (true) {
var cur = widgetCount().total;
if (cur === last && cur > 10) break;
last = cur;
sleep(500);
}
// 检测页面切换
var before = widgetCount().total;
click("下一步");
waitFor(() => widgetCount().total !== before, 10000);
```

func findOne

declare function findOne(selector: string, options?: FindOneOptions): UiNode | null
查找第一个匹配的 UI 节点
selector 语法:
- text=登录 / text~=双倍 / text^=设 / text$=置
- #btn_login (按 id)
- type=Button / type=android.widget.Button
- classname=android.widget.EditText 或 .android.widget.EditText
- package=com.example.app
- desc=登录按钮
- 属性选择器: clickable=true / focusable=true / checkable=true / checked=true / selected=true / longClickable=true / password=true / visibleToUser=true
- 多条件 AND: 用 & 分隔,如 .android.widget.Button&text~=提交&clickable=true
@param selector 选择器表达式
@param options.timeout 超时毫秒,默认 0 (不等待)
@param options.region 区域表达式
@param options click/check 等选项(与 aiTxt 一致,详见 FindOneOptions)
@returns UiNode 或 null
@example findOne("text=登录", {timeout: 5000, region: "bottom"});
📄 示例:014_findOne.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 3. UI 控件操作
// findOne(selector, options?)
// ============================================================

// --- findOne(selector, options?) ---
// 查找第一个匹配的 UI 节点。
// 参数:
//   selector (string) - 选择器,支持的字段:
//     "text=登录"          → 按文本查找
//     "#btn_login"         → 按 ID 查找
//     "type=Button"        → 按控件类型查找
//     "classname=android.widget.EditText" → 按 className 查找
//     ".android.widget.EditText"          → 同上(CSS 简写)
//     "package=com.example.app" → 按包名查找
//     "desc=登录按钮"       → 按描述查找
//     "clickable=true"     → 按属性查找
//     "focusable=true"     → 按可聚焦查找
//     "checkable=true"     → 按可勾选查找
//     "checked=true"       → 按已勾选查找
//     "selected=true"      → 按已选中查找
//     "longClickable=true" → 按可长按查找
//     "password=true"      → 按密码框查找
//     "visibleToUser=true" → 按可见性查找
//     --- Hamibot 对齐属性 ---
//     "depth=0"            → 按节点深度查找(根节点为 0)
//     "indexInParent=0"    → 按在父节点中的索引查找
//     "drawingOrder=1"     → 按绘制顺序查找
//     "accessibilityFocused=true" → 按无障碍焦点查找
//     "dismissable=true"   → 按可dismiss查找
//     "editable=true"      → 按可编辑查找
//     "multiLine=true"     → 按多行文本查找
//     "contentInvalid=true" → 按内容无效查找
//     "contextClickable=true" → 按上下文可点击查找
//     "column=0"           → 按列号查找(网格布局)
//     "columnCount=2"      → 按列数查找(网格布局)
//     "columnSpan=1"      → 按列跨度查找(网格布局)
//     "row=0"              → 按行号查找(网格布局)
//     "rowCount=2"         → 按行数查找(网格布局)
//     "rowSpan=1"          → 按行跨度查找(网格布局)
//   匹配操作符: = 精确, ~= 包含, ^= 前缀, $= 后缀, *= 正则
//   组合: 用 & 分隔多个条件(AND 关系)
//   options (object, 可选) - {timeout, region, click, check, checkWait, checkRetry, log}
//     timeout: 超时时间(毫秒),默认 0(不等待)
//     region: 搜索区域限制
//     click: true 找到后自动点击
//     check: true 点击后验证消失;[selector, region?] 点击后验证出现
//     checkWait: 检查等待时间(ms),默认 500
//     checkRetry: 最大重试次数,默认 3
//     log: 输出搜索过程日志
// 返回 UiNode 或 null,UiNode 包含以下字段:
//   {id, text, desc, type, className, package, bounds, center,
//    clickable, scrollable, enabled,
//    focusable, focused, checkable, checked, selected,
//    longClickable, password, visibleToUser, parentClass,
//    depth, indexInParent, drawingOrder, accessibilityFocused,
//    dismissable, editable, multiLine, contentInvalid, contextClickable,
//    column, columnCount, columnSpan, row, rowCount, rowSpan}

// 示例1: 不等待(默认),找不到立即返回 null
var node1 = findOne("text=登录");
if (node1) {
    log("找到登录按钮: " + node1.text + " 中心: " + node1.center[0] + "," + node1.center[1]);
}

// 示例2: 带超时等待,在 5 秒内反复查找
var node2 = findOne("text=登录", {timeout: 5000});
if (node2) {
    log("5秒内找到登录按钮");
} else {
    log("5秒内未找到登录按钮");
}

// 示例3: 按 ID 查找
var node3 = findOne("#username_input");

// 示例4: 按 className 查找(两种写法等价)
var node4a = findOne("classname=android.widget.EditText");
var node4b = findOne(".android.widget.EditText");

// 示例5: 按包名查找
var node5 = findOne("package=com.example.app&clickable=true");

// 示例6: 多条件组合
var node6 = findOne(".android.widget.Button&text~=提交&clickable=true");

// 示例7: 使用 Hamibot 对齐的新属性
// 按深度查找根节点
var root = findOne("depth=0");
// 按可编辑查找输入框
var editField = findOne("editable=true&clickable=true");
// 按可dismiss查找对话框
var dialog = findOne("dismissable=true");
// 按节点深度+类型组合查找
var level1Buttons = findAll("depth=1&clickable=true");
// 按网格布局属性查找
var gridCell = findOne("column=0&row=0");
// 使用正则匹配 text
var loginBtn = findOne("text*=^登.*录$");
// 使用正则匹配 className
var buttons = findAll("classname*=android\\.widget\\..*Button$");

func findAll

declare function findAll(selector: string, options?: FindAllOptions): UiNodeArray | null
declare function findAll(selectors: string[], options?: FindAllOptions): UiNodeGroupResult | null
declare function findAll( groups: (string | string[] | FindAllOptions)[][] ): UiNodeGroupResult | null
declare function findAll( groups: (string | string[] | FindAllOptions)[][], options: FindAllOptions ): UiNodeGroupResult | null
多选择器数组写法: findAll(["text=按钮", "text=关闭"]) — 返回第一个命中的选择器组
📄 示例:015_findAll.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 3. UI 控件操作
// findAll(selector)
// ============================================================

// --- findAll(selector) ---
// 查找所有匹配的 UI 节点。参数:selector (string),无默认值。
// 返回数组 [{id, text, desc, type, bounds, center, clickable}, ...] 或 null(无匹配返回 null)
var allButtons = findAll("type=android.widget.Button");
if (allButtons) {
    log("找到 " + allButtons.length + " 个按钮");
    for (var i = 0; i < allButtons.length; i++) {
        log("  按钮[" + i + "]: " + allButtons[i].text + " @ " + allButtons[i].center);
    }
} else {
    log("未找到按钮");
}

// findAll 完整调用方式:
//   1. 单选择器模式: findAll(selector, region?, options?)
//      返回 UiNodeArray (附带 .region() 链式方法)
//   2. 多组模式: findAll(groups, options?)
//      groups 为二维数组,按顺序逐组查找,找到第一个所有选择器都有匹配的组即返回
//      返回 {groupIndex, selectors, matches:[[...],[...]]} 或 null

// findAll 单选择器 + 区域过滤
var topButtons = findAll("clickable=true", {region: "top"});
if (topButtons) {
    log("上半屏找到 " + topButtons.length + " 个可点击控件");
}

// findAll 单选择器 + non 排除
// 如果屏幕上存在 "跳过" 文本,则返回 null
var result = findAll("text=领取", {non: "text~=跳过"});
if (result) {
    log("找到领取按钮,且无跳过文本");
}

// findAll 多组模式(短路查找)
// 按顺序尝试每组,找到第一个所有选择器都有匹配的组即返回
var res = findAll([
    ["text=立即领取", "text=关闭"],           // 组0
    ["text=同意", "text=继续"],               // 组1
    ["text=取消", "text=确定", ["top","bottom"]] // 组2(带区域)
]);
if (res) {
    log("命中组 " + res.groupIndex + ": " + JSON.stringify(res.selectors));
    // res.matches[0] → 组0第一个选择器的所有匹配
    // res.matches[1] → 组0第二个选择器的所有匹配
    click(res.matches[0][0].center);  // 点击第一个匹配
}

// findAll 多组模式 + 全局 non 排除
// 全局 non: 屏幕上存在任一排除文本时直接返回 null(所有组都不匹配)
var res2 = findAll([
    ["text=领取", "text=关闭"],
    ["text=继续", "text=确定"]
], {non: "text~=跳过"});
if (res2) {
    log("命中组 " + res2.groupIndex);
}

// findAll 多组模式 + 组级 non 排除(新功能)
// 组级 non: 仅跳过该组,继续尝试下一组(而非全局返回 null)
var res3 = findAll([
    // 组0: 如果屏幕存在 "广告" 文本,跳过此组,继续尝试组1
    ["text=关闭", ["top"], {non: ["~=广告"]}],
    // 组1: 如果屏幕存在 "弹窗" 文本,跳过此组
    ["text=继续", {non: ["~=弹窗"]}],
    // 组2: 无 non,始终尝试
    ["text=确定", "text=取消"]
]);
if (res3) {
    log("命中组 " + res3.groupIndex + ": " + JSON.stringify(res3.selectors));
} else {
    log("所有组均未命中或被 non 排除");
}

// findAll click: true — 找到后自动点击所有匹配控件
// 适用于"关闭所有弹窗"等场景:找到所有可点击的关闭按钮并逐一点击
var allCloseBtns = findAll("id~=close_btn&clickable=true", {click: true});
log("点击了 " + (allCloseBtns ? allCloseBtns.length : 0) + " 个关闭按钮");

// findAll check: true — 点击后验证消失(disappear 模式)
// 隐含 click: true,点击所有匹配控件后重新查找:
//   全部消失(count=0)或全部坐标变化 → 成功,返回原匹配数组
//   仍有匹配且坐标相同 → 重新点击剩余控件,重试(最多 checkRetry 次)
//   超过重试次数仍存在 → 返回 null
var closed = findAll("text=关闭广告", {region: "top", check: true, checkWait: 800, checkRetry: 3});
if (closed) {
    log("广告关闭成功,共关闭 " + closed.length + " 个");
} else {
    log("广告关闭失败,控件仍在");
}

// findAll check: [selector, region?] — 点击后验证出现(appear 模式)
// 隐含 click: true,点击所有匹配控件后查找验证选择器:
//   找到 → 成功,返回原匹配数组
//   未找到 → 重新查找并点击所有原始控件,重试(最多 checkRetry 次)
//   超过重试次数验证选择器仍未出现 → 返回 null
//
// 验证选择器支持两种写法:
//   UI 选择器: "text=我的"、"id~=btn"、"classname=android.widget.Button" 等
//   纯文本/正则: "我的"、"re=/首页|登录/"、"文本A|文本B"(含 | 自动作为正则)
var matched = findAll("classname=android.widget.TextView&clickable=true", {region: "rt", click: true, check: ["text=我的"]});
if (matched) {
    log("点击成功,验证文本出现");
} else {
    log("点击后验证文本未出现");
}

// findAll check: [selector, region] — 带区域验证
// 点击所有匹配控件后,在指定区域内查找验证选择器
var result2 = findAll("text=立即领取", {region: "top", click: true, check: ["text=已领取", "bottom"]});
if (result2) {
    log("领取成功,验证文本出现在底部");
}

// findAll click + non 组合使用
// 排除文本 + 点击:如果屏幕存在排除文本则返回 null,否则点击所有匹配控件
var adBtns = findAll("text=领取奖励", {non: "text~=跳过", click: true});
if (adBtns) {
    log("领取了 " + adBtns.length + " 个奖励");
}

颜色查找 (HSV)

func findColor

declare function findColor(hex: Color, options?: { tolerance?: number; region?: RegionExpr }): ColorMatch | null
找色 — 在屏幕中查找指定颜色
@param hex 颜色值,如 "#FF5722" 或 0xFF5722(也支持 setColor 键名)
@param options.tolerance HSV 容差 0~255,默认 0
@param options.region 区域表达式
@returns 匹配结果或 null
@example findColor("#FF5722", {tolerance: 10, region: "top"});
📄 示例:018_findColor.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 4. 颜色查找
// findColor(hex, options?)
// ============================================================

// --- findColor(hex, options?) ---
// HSV 色彩空间找色(inRange 阈值过滤 + 连通域轮廓提取)。
// 相比 RGB 直接匹配,HSV 对光照和阴影更鲁棒。
// 参数:
//   hex (string|number|object) - 颜色值,四种形式:
//     "#FF5722" 颜色字符串
//     0xFF5722 数字
//     "btnColor" setColor 保存的键名字符串(自动从取色配置读取颜色)
//     setColor 返回的颜色对象(如 var {c1} = setColor(...) 后传 c1)
//   options (object, 可选) - {tolerance, region}
//     tolerance: HSV 容差 0~255,默认 0
//       H: ±tolerance 度 (0~360 色相空间)
//       S: ±tolerance/255 (0~1 饱和度空间)
//       V: ±tolerance/255 (0~1 明度空间)
//     region: 搜索区域限制(setRect 返回值 / "lt" 等区域名 / [x,y,w,h] 数组)
//       指定 region 时返回区域内面积最大的连通域(区域内无匹配返回 null,
//       即使全屏其他位置存在更大色块也不影响)
// 返回 {x: int, y: int, w: int, h: int, area: int} 或 null
//   x, y: 匹配区域质心坐标
//   w, h: 外接矩形宽高
//   area: 像素面积

// 示例1: 精确匹配(tolerance=0,默认)
var pos1 = findColor("#FF5722");
// 等价于:
var pos1b = findColor(0xFF5722);
// 等价于:
var pos1c = findColor("#FF5722", {tolerance: 0});

// 示例2: 带容差匹配(HSV 色彩空间,对光照变化更鲁棒)
var pos2 = findColor("#FF5722", {tolerance: 10});   // 容差 10: H ±10°, S/V ±0.039
var pos3 = findColor(0xFF5722, {tolerance: 20});    // 容差 20: H ±20°, S/V ±0.078
var pos4 = findColor("#4CAF50", {tolerance: 50});   // 容差 50: H ±50°, S/V ±0.196

// 示例3: 使用 setColor 键名 + setRect 区域(典型配合用法)
// 先取色/画区域(有缓存时直接读缓存,无缓存弹窗采集)
var arrowArea = setRect("arrowArea", {hint: "请框选背包第一个装备的绿色箭头区域"});
var {cmpColor} = setColor(["cmpColor"], {hint: "请取第一个装备的绿色"});
// 用键名 "cmpColor" 在 arrowArea 区域内找色(也可直接传 cmpColor 对象)
var pos5 = findColor("cmpColor", {region: arrowArea, tolerance: 20});
// 等价于传对象:
var pos5b = findColor(cmpColor, {region: arrowArea, tolerance: 20});

if (pos1) {
    log("找到颜色区域: 质心(" + pos1.x + "," + pos1.y + ") " +
        "外接矩形 " + pos1.w + "x" + pos1.h + " 面积=" + pos1.area);
    click(pos1);
}

func findAllColors

declare function findAllColors(hex: Color, options?: { tolerance?: number; region?: RegionExpr }): ColorMatchArray
找所有色 — 查找屏幕中所有匹配的颜色
@returns 匹配结果数组 (附带链式 .region())
📄 示例:019_findAllColors.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 4. 颜色查找
// findAllColors(hex, options?)
// ============================================================

// --- findAllColors(hex, options?) ---
// HSV 查找屏幕中所有匹配颜色区域。返回连通域列表,按面积降序排列。
// 参数同 findColor。返回数组 [{x, y, w, h, area}, ...] 或 null(无匹配返回 null)

// 示例1: 精确匹配(tolerance=0,默认)
var all1 = findAllColors("#FF5722");
// 等价于:
var all1b = findAllColors(0xFF5722);
// 等价于:
var all1c = findAllColors("#FF5722", {tolerance: 0});

// 示例2: 带容差匹配
var all2 = findAllColors("#FF5722", {tolerance: 30});
if (all2) {
    log("找到 " + all2.length + " 个匹配颜色区域");
    for (var i = 0; i < all2.length; i++) {
        log("  [" + i + "] 质心(" + all2[i].x + "," + all2[i].y + ") " +
            all2[i].w + "x" + all2[i].h + " 面积=" + all2[i].area);
    }
} else {
    log("未找到匹配颜色");
}

func findColorFast

declare function findColorFast(hex: Color, options?: { tolerance?: number; region?: RegionExpr }): ColorMatch | null
快速找色 (RGB 模式) — 使用 RGB 欧氏距离匹配,跳过 HSV 转换,速度提升 ~3x
@param hex 目标颜色
@param options.tolerance 每通道最大允许差异 0~255,默认 0
@param options.region 区域表达式
@returns 匹配结果或 null
@example findColorFast("#FF5722", {tolerance: 10, region: "top"});
📄 示例:163_findColorFast.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// findColorFast(hex, tolerance?, region?) — 快速找色(RGB 模式)
// ============================================================

// --- findColorFast(hex, tolerance?, region?) — 快速找色(RGB 模式) ---
// 使用 RGB 欧氏距离匹配,跳过 HSV 转换,速度提升 ~3x
// 适用于对颜色匹配精度要求不高的快速检测场景
// 参数和返回值同 findColor
var fast = findColorFast("#FF0000", {tolerance: 10});
if (fast) {
    log('快速找色命中: (' + fast.x + ', ' + fast.y + ')');
}

func checkPixelColor

declare function checkPixelColor(coords: [number, number, Color], options?: { tolerance?: number }): boolean
检查指定坐标的像素是否匹配目标颜色 — 零分配单像素检测,性能比 findColor 高 1000x+
@param coords [x, y, hex] 数组(位置数字调用会直接抛错)
@param options.tolerance 颜色容忍度 0~255,默认 0
@returns true(匹配)/ false(不匹配或坐标越界)
@example checkPixelColor([100, 200, "#FF5722"], {tolerance: 10});
📄 示例:164_checkPixelColor.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// checkPixelColor(coords, options?) — 检查指定坐标像素颜色
// ============================================================

// --- checkPixelColor(coords, options?) — 检查指定坐标像素颜色 ---
// 零分配单像素检测,性能比 findColor 全屏扫描高 1000x+
// 适用于定点颜色监测(如按钮高亮检测、加载完成检测)
// 返回: true(匹配)/ false(不匹配或坐标越界)
if (checkPixelColor([500, 800, "#00FF00"], {tolerance: 20})) {
    log('按钮已亮起!');
    click([500, 800]);
}

func getPixelColor

declare function getPixelColor(pos: [number, number]): { r: number; g: number; b: number; a: number; hex: string } | null
获取指定坐标的像素颜色 — 使用截图缓存,零拷贝读取
@param pos [x, y] 坐标数组
@returns 像素颜色信息或 null(坐标越界)
@example getPixelColor([100, 200]);
📄 示例:162_getPixelColor.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// getPixelColor([x, y]) — 获取指定坐标的像素颜色
// ============================================================

// --- getPixelColor([x, y]) — 获取指定坐标的像素颜色 ---
// 使用截图缓存,零拷贝读取像素值
// 返回: {r, g, b, a, hex} 或 null(坐标越界)
var px = getPixelColor([100, 200]);
if (px) {
    log('像素颜色: ' + px.hex + ' RGBA(' + px.r + ',' + px.g + ',' + px.b + ',' + px.a + ')');
}

func refreshScreen

declare function refreshScreen(): void
强制刷新截图缓存 — 使当前截图缓存失效,下次 findColor 等函数会重新截图
📄 示例:161_refreshScreen.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// refreshScreen() — 强制刷新截图缓存
// ============================================================

// --- refreshScreen() — 强制刷新截图缓存 ---
// 使当前截图缓存失效,下次 findColor 等函数会重新截图
// click() 已内置自动刷新,通常无需手动调用
// 适用场景:sleep 后需要获取最新画面时
refreshScreen();

func waitForColor

declare function waitForColor(color: Color, options?: { timeout?: number; tolerance?: number; region?: RegionExpr }): ColorMatch | null
低功耗等待颜色出现 — 指数退避轮询策略 + 截图缓存,CPU 占用降低 80%+
@param color 要等待的颜色
@param options.timeout 最大等待时间(毫秒),默认 30000
@param options.tolerance 颜色容忍度 0~255,默认 0
@param options.region 区域表达式
@returns 匹配结果或 null(超时未出现)
@example waitForColor("#FF0000", {timeout: 10000, tolerance: 10});
📄 示例:166_waitForColor.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// waitForColor(color, timeout?, tolerance?, region?) — 等待颜色出现
// ============================================================

// --- waitForColor(color, timeout?, tolerance?, region?) — 等待颜色出现 ---
// 低功耗版颜色等待:使用指数退避轮询策略 + 截图缓存
// 前期间隔 200ms 快速检测,后期逐步退避到最高 2000ms
// 相比 while(true) + findColor + sleep 模式,CPU 占用降低 80%+
// 返回: {x, y, w, h, area} 或 null(超时未出现)
var colorFound = waitForColor("#FF0000", {timeout: 10000, tolerance: 10});
if (colorFound) {
    log('颜色出现于: (' + colorFound.x + ', ' + colorFound.y + ')');
    click(colorFound);
}

func waitForColorGone

declare function waitForColorGone(color: Color, options?: { timeout?: number; tolerance?: number; region?: RegionExpr }): boolean
低功耗等待颜色消失 — 指数退避轮询策略
@param color 要等待消失的颜色
@param options.timeout 最大等待时间(毫秒),默认 30000
@param options.tolerance 颜色容忍度 0~255,默认 0
@param options.region 区域表达式
@returns true(颜色已消失)/ false(超时仍存在)
📄 示例:167_waitForColorGone.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// waitForColorGone(color, timeout?, tolerance?, region?) — 等待颜色消失
// ============================================================

// --- waitForColorGone(color, timeout?, tolerance?, region?) — 等待颜色消失 ---
// 与 waitForColor 相反,等待指定颜色从屏幕上消失
// 返回: true(颜色已消失)/ false(超时仍存在)
if (waitForColorGone("#CCCCCC", {timeout: 5000, tolerance: 10})) {
    log('加载动画已消失,页面加载完成');
}

// === 低功耗最佳实践 ===
// ❌ 传统高发热写法(不推荐)
// while(true) {
//     var btn = findColor("#FF0000");
//     if(btn) { click(btn); break; }
//     sleep(200);
// }

// ✅ 框架推荐的低功耗写法(CPU 占用 < 1%)
// waitForColor 内置指数退避 + 截图缓存,无需手动循环
var btn = waitForColor("#FF0000", {timeout: 30000, tolerance: 10});
if (btn) {
    click(btn);
    // click 后自动刷新截图缓存
    // 如需等待点击效果,使用 waitForColorGone
    waitForColorGone("#FF0000", {timeout: 5000, tolerance: 10});
}

// === 定点颜色监测最佳实践 ===
// 对于固定位置的按钮状态检测,使用 checkPixelColor 比 findColor 快 1000x+
var BTN_X = 540, BTN_Y = 1800;
var BTN_COLOR_OFF = "#808080"; // 灰色=未激活
var BTN_COLOR_ON = "#00CCFF";  // 蓝色=已激活

// 等待按钮激活
while (!checkPixelColor([BTN_X, BTN_Y, BTN_COLOR_ON], {tolerance: 20})) {
    sleep(500);
}
click([BTN_X, BTN_Y]);


// 22. 极致优化 API — Zero-Copy 截图、VFS、Wasm 沙箱、插件隔离、事件驱动等待
// ==============================================================================
// 以下 API 是 flutter-auto 极致优化架构的高级功能:
// - getScreenData(): 零拷贝获取屏幕像素数据(ArrayBuffer)
// - waitForColorEvent(): 智能帧差检测 + 自适应休眠(CPU 占用 < 0.1%)
// - registerZip() / requireZip(): VFS 虚拟文件系统,从 zip 包加载模块
// - loadPlugin(): 隔离插件加载,白名单 API 控制

极致优化 API — Zero-Copy 截图、VFS、插件隔离

func getScreenData

declare function getScreenData(): { width: number; height: number; data: ArrayBuffer }
零拷贝获取屏幕像素数据 — 返回 ArrayBuffer,无 JSON 序列化开销
@returns {width, height, data: ArrayBuffer} — data 为 RGBA 像素数据
📄 示例:168_getScreenData.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// getScreenData() — 零拷贝获取屏幕像素数据
// ============================================================

// --- getScreenData() — 零拷贝获取屏幕像素数据 ---
// 返回 {width, height, data: ArrayBuffer}
// JS 侧通过 Uint8Array 直接读取像素,无 JSON 序列化开销
// 适用于自定义图像处理算法(如像素遍历、颜色统计等)
var screen = getScreenData();
var pixels = new Uint8Array(screen.data);
// 读取 (100, 200) 位置的像素 (RGBA)
var idx = (200 * screen.width + 100) * 4;
var r = pixels[idx], g = pixels[idx + 1], b = pixels[idx + 2], a = pixels[idx + 3];
log('像素颜色: rgba(' + r + ',' + g + ',' + b + ',' + a + ')');

func waitForColorEvent

declare function waitForColorEvent(color: Color, options?: { timeout?: number; tolerance?: number }): ColorMatch | null
事件驱动颜色等待 — 智能帧差检测 + 自适应休眠
屏幕无变化时深度休眠(最长 5 秒),有变化时立即检查
CPU 占用 < 0.1%
@param color 目标颜色
@param timeout 超时毫秒,默认 30s
@param tolerance 颜色容忍度 0~255,默认 0
@returns 匹配结果或 null
📄 示例:169_waitForColorEvent.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// waitForColorEvent() — 事件驱动颜色等待(CPU 占用 < 0.1%)
// ============================================================

// --- waitForColorEvent() — 事件驱动颜色等待(CPU 占用 < 0.1%) ---
// 使用智能帧差检测:屏幕无变化时深度休眠(最长 5 秒),有变化时立即检查
// 相比 waitForColor 的固定间隔轮询,CPU 占用进一步降低 90%+
//
// 参数:
//   color (string|number) — 目标颜色,如 "#FF0000" 或 0xFF0000FF
//   timeout (number, 可选) — 超时毫秒,默认 30s
//   tolerance (number, 可选) — 颜色容忍度 0~255,默认 0
// 返回: {x, y, w, h, area} 或 null
var result = waitForColorEvent("#00CCFF", 60000, 10);
if (result) {
    log('检测到目标颜色: (' + result.x + ', ' + result.y + ')');
    click(result.x, result.y);
}

func registerZip

declare function registerZip(zipPath: string): number
注册 zip 包到 VFS 虚拟文件系统
注册后 require() 可从中加载模块
@param zipPath zip 文件路径
@returns 加载的文件数量

func requireZip

declare function requireZip(zipPath: string, moduleName?: string): any
从 zip 包加载单个 JS 模块
@param zipPath zip 文件路径
@param moduleName 模块文件名,默认 'index.js'
@returns 模块的 exports 对象

func loadPlugin

declare function loadPlugin( path: string, options?: { allowedApis?: string[] } ): any
加载隔离插件 — 在独立作用域中执行,白名单 API 控制
@param path 插件 JS 文件路径
@param options 配置选项
- allowedApis: 允许的 API 名称数组(默认全部允许)
@returns 插件的 module.exports
📄 示例:171_loadPlugin.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// loadPlugin() — 隔离插件加载
// ============================================================

// --- loadPlugin() — 隔离插件加载 ---
// 在独立作用域中加载 JS 插件,插件无法访问主脚本全局变量
// 通过白名单 API 控制插件可调用的功能
//
// 参数:
//   path (string) — 插件 JS 文件路径
//   options (object, 可选):
//     allowedApis: 允许的 API 名称数组(默认全部允许)
// 返回: 插件的 module.exports 对象
var matcher = loadPlugin('/sdcard/plugins/matcher.js', {
    allowedApis: ['findColor', 'click', 'sleep', 'log']
});
var matchResult = matcher.find('#FF0000');
if (matchResult) {
    log('插件找到颜色: ' + JSON.stringify(matchResult));
}

func findMultiColors

declare function findMultiColors( para: { color: Color; offsets: Array<[number, number, Color]> }, options?: { tolerance?: number; region?: RegionExpr } ): MultiColorMatch | null
多点找色 — 以锚点颜色定位,再校验偏移点颜色
@param firstColor 锚点颜色
@param offsets 偏移点数组 [[dx, dy, color], ...]
@param tolerance HSV 容差,默认 0
@param region 区域表达式
@returns 匹配结果或 null
📄 示例:020_findMultiColors.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 4. 颜色查找
// findMultiColors(para, options?)
// ============================================================

// --- findMultiColors(para, options?) ---
// HSV 多点找色:先找锚点颜色的连通域,再检查偏移位置颜色是否在 HSV 范围内。
// 参数:
//   para (object) — {color: 锚点颜色, offsets: 偏移颜色点}
//     color: 锚点颜色,如 "#FF0000" 或 0xFF0000
//     offsets: [[dx, dy, color], ...]
//       dx, dy: 相对锚点质心的偏移量(像素)
//       color: 颜色值,如 "#00FF00" 或 0x00FF00
//   options (object, 可选) — {tolerance, region}
//     tolerance: HSV 颜色容忍度 0~255,默认 0
//     region: 区域表达式
// 返回: {x, y} 或 null

// 示例1: 基本多点找色
// 锚点红色,右偏 10px 为绿色,下偏 20px 为蓝色
var mc1 = findMultiColors({color: "#FF0000", offsets: [[10, 0, "#00FF00"], [0, 20, "#0000FF"]]});
if (mc1) {
    log("多点找色命中: " + mc1.x + "," + mc1.y);
    click(mc1);
}

// 示例2: 带容差
var mc2 = findMultiColors({color: "#FF5722", offsets: [[5, 5, "#FFAA00"], [10, 10, "#00AAFF"]]}, {tolerance: 20});
if (mc2) { log("容差 20 命中: " + mc2.x + "," + mc2.y); }

// 示例3: 带区域
var mc3 = findMultiColors({color: "#FF0000", offsets: [[10, 0, "#00FF00"]]}, {tolerance: 0, region: "lt"});  // 左上角
var mc3b = findMultiColors({color: "#FF0000", offsets: [[10, 0, "#00FF00"]]}, {tolerance: 0}).region("lt"); // 链式

func findAllMultiColors

declare function findAllMultiColors( para: { color: Color; offsets: Array<[number, number, Color]> }, options?: { tolerance?: number; region?: RegionExpr } ): MultiColorMatchArray
多点找色 (全部) — 返回所有匹配结果
@returns 匹配结果数组 (附带链式 .region())
📄 示例:021_findAllMultiColors.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 4. 颜色查找
// findAllMultiColors(para, options?)
// ============================================================

// --- findAllMultiColors(para, options?) ---
// 多点找色(返回所有匹配位置)。参数同 findMultiColors。
// 返回: [{x, y}, ...] 或 null(无匹配返回 null)
var allMc = findAllMultiColors({color: "#FF0000", offsets: [[10, 0, "#00FF00"]]}, {tolerance: 10});
if (allMc) {
    log("找到 " + allMc.length + " 个多点匹配");
} else {
    log("未找到多点匹配");
}

图像查找 (ORB 特征点匹配)

func findImage

declare function findImage( templatePath: string | string[], options?: { threshold?: number; region?: RegionExpr } ): ImageMatch | null
找图 — ORB 特征点匹配
支持多模板冗余: 传入路径数组时逐一尝试,返回置信度最高的结果。
底层会自动缓存模板图片。
@param templatePath 模板图片路径,或路径数组
@param threshold 匹配阈值 0.0~1.0,默认 0.8
@param region 区域表达式 (传给 Rust 做 ROI 裁剪)
@returns 匹配结果或 null
📄 示例:022_findImage.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 4. 颜色查找
// findImage(templatePath, options?)
// ============================================================

// --- findImage(templatePath, options?) ---
// 找图:在屏幕中查找模板图片(NCC 归一化互相关匹配)。
// NCC 对亮度变化鲁棒,适用于 UI 自动化场景(无旋转/缩放)。
// 算法优化:
//   1. 积分图加速 — O(1) 区域均值/平方和计算
//   2. 金字塔分层搜索 — 1/4 粗搜 → 1/2 精搜 → 原图精搜(速度提升 10~50 倍)
//   3. ROI 区域限制 — 只在指定区域搜索(速度提升几十倍)
//   4. SAD 回退 — 纯色模板自动切换到 SAD 匹配
//   5. 多模板冗余 — 传入路径数组,只要有一张匹配即返回结果
// 参数:
//   templatePath (string|array) — 模板图片路径,或路径数组(多模板冗余)
//     多模板示例: ["/sdcard/btn_normal.png", "/sdcard/btn_pressed.png"]
//   options (object, 可选) — {threshold, region}
//     threshold: 匹配阈值 0.0~1.0,默认 0.8(confidence = NCC 系数,1.0=完全匹配)
//     region: 区域表达式,传给 Rust 层做 ROI 裁剪
//       支持命名区域: "lt"|"rt"|"lb"|"rb"|"left"|"right"|"top"|"bottom"
//       支持坐标表达式: "800,0" 或 "0>800,0>600" 或 "device.width/2,0"
// 返回: {x, y, confidence} 或 null
//   x, y: 模板中心在屏幕中的位置
//   confidence: 匹配置信度 0.0~1.0

// 示例1: 基本找图
var img1 = findImage("/sdcard/template.png");
if (img1) {
    log("找到图片: (" + img1.x + "," + img1.y + ") 置信度: " + img1.confidence.toFixed(3));
    click(img1);
}

// 示例2: 自定义阈值
var img2 = findImage("/sdcard/button.png", {threshold: 0.9});   // 高阈值,更严格
var img3 = findImage("/sdcard/button.png", {threshold: 0.7});   // 低阈值,更宽松

// 示例3: 带区域(ROI 裁剪 — 只在指定区域搜索,大幅提速)
var img4 = findImage("/sdcard/icon.png", {threshold: 0.8, region: "rt"});       // 右上角找
var img4b = findImage("/sdcard/icon.png", {threshold: 0.8}).region("rt"); // 链式
var img4c = findImage("/sdcard/close_btn.png", {threshold: 0.85, region: "device.width-300,0"}); // 自定义坐标
var img4d = findImage("/sdcard/btn.png", {threshold: 0.8, region: "0>540,0>960"}); // 左上 540x960 区域

// 示例4: 多模板冗余(不同状态的模板,任一匹配即返回)
var img5 = findImage([
    "/sdcard/btn_normal.png",    // 正常态
    "/sdcard/btn_pressed.png",   // 按压态
    "/sdcard/btn_disabled.png"   // 禁用态
], {threshold: 0.85, region: "rt"});
if (img5) {
    log("匹配到按钮: (" + img5.x + "," + img5.y + ") conf=" + img5.confidence.toFixed(3));
}

func findAllImages

declare function findAllImages( templatePath: string | string[], options?: { threshold?: number; region?: RegionExpr } ): ImageMatchArray
找所有匹配图 — 返回所有匹配结果 (按 confidence 降序,附带链式 .region())
📄 示例:023_findAllImages.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 4. 颜色查找
// findAllImages(templatePath, options?)
// ============================================================

// --- findAllImages(templatePath, options?) ---
// 找所有匹配图。参数同 findImage,支持多模板和 ROI。
// 返回: [{x, y, confidence}, ...] 或 null(无匹配返回 null,按置信度降序排列)
var allImgs = findAllImages("/sdcard/button.png", {threshold: 0.85});
if (allImgs) {
    log("找到 " + allImgs.length + " 个匹配图片");
    for (var i = 0; i < allImgs.length; i++) {
        log("  [" + i + "] (" + allImgs[i].x + "," + allImgs[i].y + ") conf=" + allImgs[i].confidence.toFixed(3));
    }
} else {
    log("未找到匹配图片");
}

// 示例: 多模板 + ROI
var allBtns = findAllImages(["/sdcard/btn_a.png", "/sdcard/btn_b.png"], {threshold: 0.8, region: "bottom"});

OCR 文字识别

func ocr

declare function ocr(options?: { region?: RegionExpr }): OcrResultArray
对当前屏幕进行 OCR 识别
@param region 区域表达式
@returns OCR 结果数组 (附带链式 .region())
📄 示例:025_ocr.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5. OCR 文字识别
// ocr()
// ============================================================

// --- ocr() ---
// 对当前屏幕执行 OCR 识别。无参数。
// 返回数组 [{text, confidence, bbox, center}, ...] 或 null(无识别结果返回 null)
var results = ocr();
if (results) {
    for (var i = 0; i < results.length; i++) {
        log("  [" + i + "] text='" + results[i].text + "' confidence=" + results[i].confidence + " center=" + results[i].center);
    }
} else {
    log("OCR 未识别到任何文字");
}

func ocrFind

declare function ocrFind(text: string, options?: { region?: RegionExpr }): OcrResult | null
OCR 查找文本 — 返回第一个匹配项
@param text 要查找的文本
@param region 区域表达式
@returns 匹配项或 null
📄 示例:026_ocrFind.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5. OCR 文字识别
// ocrFind(text)
// ============================================================

// --- ocrFind(text) ---
// 在 OCR 结果中查找包含指定文本的区域。参数:text (string),无默认值。
// 返回 {text, confidence, bbox, center} 或 null
var found = ocrFind("登录");
if (found) {
    log("找到文字: " + found.text + " @ " + found.center);
    click(found.center[0], found.center[1]);
}

func waitFor

declare function waitFor(target: string, options?: WaitForOptions): WaitForOcrResult | boolean | string | null
统一等待函数 — 等待文本/控件/Activity/包名出现或消失(整合原 waitTxt/waitUI/waitActivity/waitPkg)
通过 options.mode 指定等待场景(省略时自动推断):
- 'ocr': 等待文本出现(OCR 轮询,自适应间隔 300ms → 3000ms),target 支持匹配前缀 (=, ~=, ^=, $=, re=)
- 'ui': 等待 UI 控件出现(控件树轮询,自适应间隔 500ms → 5000ms),target 为选择器
- 'act': 等待前台 Activity 变为指定值(包含匹配),target 可为简短类名,必须显式传 mode
- 'pkg': 等待前台应用包名变为指定值(包含匹配),必须显式传 mode
mode 自动推断:target 含选择器语法(text=/desc~/id*= 前缀、#id、.type、& 组合)→ 'ui',否则 → 'ocr'
所有 mode 均支持 disappear 等待消失模式(两阶段:先出现 → 连续 disappearCheck 次不出现才确认消失)
@param target 等待目标(文本/选择器/Activity 名/包名)
@param options 选项对象
- mode: 'ocr' | 'ui' | 'act' | 'pkg',省略时自动推断
- timeout: 最大等待毫秒,默认引擎超时或 30000
- interval: 初始轮询间隔(毫秒),ocr 默认 300 / ui 默认 500 / act/pkg 默认 500
- region: 区域表达式(仅 ocr/ui 模式支持)
- log: 输出轮询过程日志;字符串时匹配成功额外输出该字符串
- disappear: 等待消失模式,默认 false
- disappearCheck: 消失确认检查次数,默认 2(最小 2)
@returns 普通模式: ocr → 结果对象或 null;ui → true/false;act/pkg → 匹配字符串或 null
disappear 模式(所有 mode): true(出现过且已消失)/ false(超时:从未出现或仍存在)
@example
```js
waitFor("登录", {timeout: 30000}); // ocr 等文本出现
waitFor("=首页", {timeout: 15000, region: "top"}); // ocr 精确匹配 + 区域
waitFor("text=登录", {timeout: 10000}); // ui 等控件出现(自动推断)
waitFor("MainActivity", {mode: "act", timeout: 10000}); // 等 Activity
waitFor("com.tencent.mm", {mode: "pkg", timeout: 15000}); // 等包名
waitFor("加载中", {disappear: true, timeout: 30000}); // ocr 等文本消失
waitFor("id=progressBar", {mode: "ui", disappear: true}); // ui 等控件消失
```
📄 示例:028_waitFor.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5. OCR 文字识别
// waitFor(target, options?) — 统一等待函数
// ============================================================

// --- waitFor(target, options?) — 统一等待函数 ---
// 等待文本/控件/Activity/包名出现或消失。
// 整合原 waitTxt / waitUI / waitActivity / waitPkg 四个函数,通过 mode 区分场景。
// 轮询间隔自适应指数退避:ocr 初始 300ms 递增至 3000ms;ui 初始 500ms 递增至 5000ms;act/pkg 初始 500ms 递增至 3000ms。
//
// 参数:
//   target (string, 必填) — 等待目标,含义随 mode 变化:
//     mode: 'ocr' — 文本(支持匹配前缀: = 精确, ~= 包含(默认), ^= 前缀, $= 后缀, re= 正则)
//     mode: 'ui'  — UI 选择器(text=xxx, desc~=xxx, id*=xxx, #id, .type, 多条件用 & 组合)
//     mode: 'act' — Activity 名(包含匹配,可为简短类名,如 "MainActivity")
//     mode: 'pkg' — 应用包名(包含匹配,如 "com.tencent.mm")
//   options (object, 可选) — 所有可选项:
//     mode (string) — 等待场景: 'ocr'|'ui'|'act'|'pkg'。
//       省略时自动推断:target 含选择器语法(text=/desc~/id*= 前缀、#id、.type、& 组合)
//       → 'ui';否则 → 'ocr'。注意:act/pkg 必须显式传 mode,无法推断。
//     timeout (number) — 最大等待时间(毫秒),默认为引擎设置的超时时间
//     interval (number) — 初始轮询间隔(毫秒),见上方各模式默认值与上限
//     log (bool|string) — 输出轮询过程日志,默认 false;传字符串时匹配成功额外输出该字符串
//     region (string|object) — 区域表达式,仅 ocr/ui 模式支持,仅在该区域内匹配
//     disappear (bool) — 等待消失模式,默认 false。
//       ocr/ui 模式: 两阶段语义 — 必须先等到目标出现过,再等到消失才算成功;
//         消失需连续 disappearCheck 次检查都不存在才确认(防抖动/漏识别)
//       act/pkg 模式: dumpsys 为权威状态源,无漏识别问题 — 进入时目标已不存在
//         直接进入消失确认(连续 disappearCheck 次不存在即确认),无需先出现过。
//         典型场景:广告已打开时调用 waitFor(act, {disappear:true}) 立即继续,不错过广告
//     disappearCheck (number) — 消失确认检查次数,默认 2(最小 2)
//
// 返回值(所有可能情况):
//   普通模式:
//     ocr → 命中: {text, center, bbox, confidence, source: "ocr"}(附带 .region() 方法)
//           超时: null
//     ui  → 命中: true;超时: false
//     act → 命中: 匹配的完整 Activity 名字符串;超时: null
//     pkg → 命中: 匹配的完整包名字符串;超时: null
//   disappear 模式:
//     ocr/ui: true — 目标出现过且已确认消失;false — 超时(从未出现 / 仍存在)
//     act/pkg: true — 目标已不存在(含进入时就已不存在);false — 超时仍存在
//   超时时会自动输出诊断日志(OCR 模式输出最后识别到的文本;act/pkg 输出当前值)

// ========== ocr 模式(原 waitTxt)==========

// 示例1: 等待文本出现(mode 自动推断为 ocr,默认使用引擎超时时间)
var wt1 = waitFor("加载完成");
if (wt1) {
    log("文本已出现: " + wt1.text + " @ " + wt1.center);
    click(wt1);   // 直接点击
} else {
    log("等待超时");
}

// 示例2: 显式指定 mode + 自定义超时
var wt2 = waitFor("登录", {mode: "ocr", timeout: 5000});    // 5 秒超时
var wt3 = waitFor("=首页", {timeout: 15000});              // 精确匹配,15 秒超时

// 示例3: 正则匹配
var wt4 = waitFor("re=/^\\d+$/", {timeout: 8000});  // 等待纯数字出现

// 示例4: 实战 — 等待页面加载后操作
var loaded = waitFor("欢迎", {timeout: 20000});
if (loaded) {
    sleep(500);
    click(aiTxt("开始"));
}

// 示例5: 区域过滤 — 仅在上半屏等待文本
var wt5 = waitFor("广告", {timeout: 10000, region: "top"});
if (wt5) {
    log("上半屏找到广告: " + wt5.text + " @ " + wt5.center);
}

// 示例6: 自定义间隔 + 日志(调试用)
var wt6 = waitFor("立即领取", {timeout: 60000, interval: 500, log: true});
// 输出:
// [waitFor:ocr] 开始等待, target="立即领取", interval=500ms, timeout=60000ms
// [waitFor:ocr] 第 5 次轮询,未命中
// [waitFor:ocr] 命中, 共尝试 7 次

// 示例7: 正则 + 区域 + 日志
var wt7 = waitFor("re=/^\\d+秒$/", {timeout: 30000, region: "bottom", log: true});
if (wt7) {
    log("倒计时: " + wt7.text);
}

// 示例8: log 参数为字符串 — 匹配成功时自动输出该字符串
// 等价于 if(waitFor(...)) { log("回答生成完成"); }  但更简洁
var wt9 = waitFor("回答完成", {timeout: 60000, log: "回答生成完成了,进行下一步"});
if (wt9) {
    // log 字符串已在匹配成功时自动输出,这里直接处理结果
    click(wt9);
}

// ========== ui 模式(原 waitUI)==========

// 示例9: 等待控件出现(mode 自动推断:target 含选择器语法 → ui)
var wu1 = waitFor("text=登录", {timeout: 10000});
if (wu1) {
    log("登录控件已出现");
}

// 示例10: 显式 mode + 区域过滤
var wu2 = waitFor("id=submit", {mode: "ui", timeout: 5000, region: "bottom"});

// 示例11: CSS 简写与多条件组合
var wu3 = waitFor("#loginBtn");                          // #id 简写 → ui 模式
var wu4 = waitFor(".android.widget.Button");             // .type 简写 → ui 模式
var wu5 = waitFor("clickable=true&text~=确定", {timeout: 8000});  // 多条件 AND

// ========== act 模式(原 waitActivity 语义)==========

// 示例12: 等待 Activity 出现(包含匹配,target 可为简短类名)
var wa1 = waitFor("MainActivity", {mode: "act", timeout: 10000});
if (wa1) {
    log("已进入 Activity: " + wa1);   // 返回完整 Activity 名字符串
}

// 示例13: 完整 Activity 名
var wa2 = waitFor("com.mm.td.ui.activity.LoginActivity", {mode: "act"});

// ========== pkg 模式(原 waitPkg 语义)==========

// 示例14: 等待应用切换到前台
var wp1 = waitFor("com.tencent.mm", {mode: "pkg", timeout: 15000});
if (wp1) {
    log("微信已到前台: " + wp1);       // 返回完整包名字符串
}

// 示例15: 包名包含匹配(只要包名包含 target 即命中)
var wp2 = waitFor("com.mm", {mode: "pkg", timeout: 8000});

// ========== disappear 等待消失模式(四种 mode 均支持)==========

// 示例16: 等待文本消失 — 先出现再消失才算成功
// 场景:点击"提交"后等待"加载中"转圈出现并最终消失
click(aiTxt("提交"));
var gone1 = waitFor("加载中", {timeout: 30000, disappear: true});
// gone1: true  — "加载中"出现过且已连续 2 次检查不存在
// gone1: false — 超时:从未出现 / 仍存在
if (gone1) {
    log("加载已完成");
} else {
    log("等待加载超时");
}

// 示例17: 提高消失确认次数 — 连续 3 次不出现才确认消失(更稳,适合 OCR 偶发漏识别场景)
var gone2 = waitFor("re=/^\\d+%$/", {timeout: 60000, disappear: true, disappearCheck: 3});

// 示例18: 等待控件消失
var gone3 = waitFor("id=progressBar", {mode: "ui", timeout: 20000, disappear: true});

// 示例19: 等待 Activity 消失 — 页面切走
var gone4 = waitFor("LoginActivity", {mode: "act", timeout: 10000, disappear: true});

// 示例20: 等待应用退到后台 — 包名不再是目标应用
var gone5 = waitFor("com.mm.td", {mode: "pkg", timeout: 15000, disappear: true});

// 示例21: disappear + region + log 组合
var gone6 = waitFor("广告", {region: "top", timeout: 10000, disappear: true, log: true});
// 输出:
// [waitFor:ocr] 开始等待, target="广告", interval=300ms, timeout=10000ms, region=top, disappear=true (确认 2 次)
// [waitFor:ocr] 目标已出现, 开始等待消失
// [waitFor:ocr] 连续 1/2 次未检出
// [waitFor:ocr] 连续 2/2 次未检出
// [waitFor:ocr] 已确认消失, 共尝试 5 次

// 示例22: log 字符串在 findOne 中使用 — 替代 if + log 模式
// 旧写法:
//   if (findOne("desc=加载完成", {timeout: 60000})) { log("加载完成,继续"); }
// 新写法: 等价但更简洁
var fe = findOne("desc=加载完成", {timeout: 60000, log: "加载完成,继续"});
if (fe) {
    // "加载完成,继续" 已自动输出
}

// 示例11: log 字符串在 aiTxt 中使用
var at = aiTxt("~=领取", {log: "找到领取按钮"});
if (at) {
    click(at);
}
// log: true 只输出调试日志;log: "字符串" 输出调试日志 + 匹配成功时输出该字符串

interface WaitForOptions

waitFor 的 options 参数
字段类型说明
mode?"ocr" | "ui" | "act" | "pkg" 等待场景: 'ocr' | 'ui' | 'act' | 'pkg',省略时自动推断(选择器语法 → ui,否则 → ocr)
timeout?number 最大等待毫秒,默认 30000
region?RegionExpr | null 搜索区域限制(仅 ocr/ui 模式支持)
interval?number 初始轮询间隔(毫秒),ocr 默认 300 / ui 默认 500 / act/pkg 默认 500,自适应递增
log?boolean | string 输出轮询过程日志
- true: 输出调试日志
- string: 输出调试日志 + 匹配成功时输出该字符串
disappear?boolean 等待消失模式,默认 false。
两阶段语义:必须先等到目标出现过,再等到消失才算成功
disappearCheck?number 消失确认检查次数,默认 2(最小 2)。
消失需连续 N 次检查都不存在才确认
📋 类型定义原文
interface WaitForOptions {
}

interface WaitForOcrResult

waitFor ocr 模式的返回结果
📋 类型定义原文
interface WaitForOcrResult {
    text: string;
    center: Center;
    bbox: number[];
    confidence: number;
    source: "ocr";
    region: RegionFilter<any>;
}

func ocrSetModel

declare function ocrSetModel(size: "tiny" | "small" | "medium"): "ok"
切换 OCR 模型
@param size 'tiny' | 'small' | 'medium'
@returns "ok"
📄 示例:027_ocrSetModel.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5. OCR 文字识别
// ocrSetModel(size)
// ============================================================

// --- ocrSetModel(size) ---
// 切换 OCR 模型尺寸。参数:size (string: 'tiny'/'small'/'medium'),无默认值。
// tiny: 最快,精度最低; small: 平衡; medium: 最慢,精度最高
ocrSetModel("tiny");     // 切换到 tiny 模型
ocrSetModel("small");    // 切换到 small 模型
ocrSetModel("medium");   // 切换到 medium 模型

func ocrGetModel

declare function ocrGetModel(): "tiny" | "small" | "medium" | "none"
获取当前 OCR 模型
@returns 'tiny' | 'small' | 'medium' | 'none'
📄 示例:029_ocrGetModel.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5. OCR 文字识别
// ocrGetModel()
// ============================================================

// --- ocrGetModel() ---
// 获取当前 OCR 模型尺寸。无参数。返回 'tiny'/'small'/'medium'/'none'
var model = ocrGetModel();
log("当前 OCR 模型: " + model);

func ocrInit

declare function ocrInit(modelDir: string, dictPath: string, modelSize: string): "ok"
初始化 OCR 引擎 (通常由 App 启动时调用)
@returns "ok"
📄 示例:024_ocrInit.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5. OCR 文字识别
// ocrInit(modelDir, dictPath, modelSize)
// ============================================================

// --- ocrInit(modelDir, dictPath, modelSize) ---
// 初始化 OCR 引擎。通常由 App 启动时自动调用,脚本中一般不需要手动调用。
// 参数:modelDir (string), dictPath (string), modelSize (string: 'tiny'/'small'/'medium')
ocrInit("/path/to/models", "/path/to/ppocr_keys_v1.txt", "medium");

aiTxt — 智能文本查找 (UI 优先 + OCR 回退)

func aiTxt

declare function aiTxt( text: string, options: AiTxtOptions & { reuse: true } ): AiTxtResult | AiTxtReuseMiss | null
declare function aiTxt( texts: string[], options: AiTxtOptions & { reuse: true } ): AiTxtResult | AiTxtReuseMiss | null
declare function aiTxt(text: string, options?: AiTxtOptions): AiTxtResult | null
declare function aiTxt( texts: string[], options?: Omit<AiTxtOptions, "count" | "distance" | "non"> ): AiTxtResult | null
declare function aiTxt( texts: string[], options: AiTxtOptions & { region: RegionExpr[] } ): AiTxtResult | null
declare function aiTxt( textsAndOptions: Array<string | AiTxtOptions> ): AiTxtResult | null
declare function aiTxt( groups: Array<Array<string | string[] | [string, number] | AiTxtOptions>>, options: AiTxtOptions & { pair: true; score?: number[] } ): AiTxtResult | null
declare function aiTxt( groups: Array<Array<string | string[] | AiTxtOptions> | Omit<AiTxtOptions, "count" | "distance" | "non">>, options?: Omit<AiTxtOptions, "count" | "distance" | "non"> ): AiTxtResult | null
多组模式: aiTxt([["文本1","文本2"], ["文本3"]], options?),count/distance/non 写在组内末尾元素: aiTxt([["文本1", {distance: [...]}]], options?)
⚠ 外层数组末尾内联 options(aiTxt([[...], {count:...}])只对 region/box/log/confidence 生效,
其中的 count/distance/non 被引擎忽略;独立第二参数中的这三项同样被忽略
📄 示例:030_aiTxt.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 5.5 智能文本查找 (aiTxt)
// aiTxt(textOrArray, options?)
// ============================================================

// --- aiTxt(textOrArray, options?) ---
// 智能文本查找:默认多线程模式,UI 控件优先 → OCR 回退。
//   1. 单次 dumpUiTree 获取控件树,在内存中同时搜索 text 和 desc
//   2. 若 UI 未命中,单次 OCR 识别屏幕文字
//   全程仅需 1~2 次平台调用
//
// 统一调用约定: aiTxt(para, options?) — 所有可选参数放入 options 对象
//
// 匹配语法(文本前缀指定匹配模式,无前缀默认 ~= 包含匹配):
//   =文本        — 精确匹配 (exact)
//   ~=文本       — 包含匹配 (contains),默认
//   ^=文本       — 前缀匹配 (prefix)
//   $=文本       — 后缀匹配 (suffix)
//   re=/pattern/flags — 正则匹配 (regex),支持 /pattern/flags 格式
//   re=pattern   — 正则匹配 (regex),无 flags
//
// 四种调用模式:
//
// 1. 单文本模式: aiTxt("文本") 或 aiTxt("文本", {region: "region"})
//    返回单个结果 {text, center, source, ...} 或 null
//
// 2. 多文本查找模式: aiTxt(["文本1", "文本2"], {region: "region"})
//    返回所有匹配结果的数组(查找任意一个)
//
// 3. 多文本 AND 模式: aiTxt(["文本1", "文本2"], {region: ["区域1", "区域2"]})
//    所有文本必须同时存在才返回第一个匹配(带 .matched 数组),否则 null
//    返回值: {text, center, source, matched: [...]} 或 null
//    .matched 数组包含所有同时找到的文本结果
//    .region(expr) 可对结果做二次区域过滤
//
// 4. 多组模式: aiTxt([["文本1", "文本2"], ["文本3", "文本4"]])
//    每组内所有文本必须同时存在(AND),按组顺序评估,返回第一个匹配的组
//    返回单个对象 {index, data, matched?} 或 null(全部未匹配):
//      index  — 匹配组在传入数组中的索引
//      data   — 组内第一个匹配 {text, center, bbox?, confidence?, source}
//      matched — 组内其余匹配(仅有多个匹配时存在;仅 data 一个时省略)
//    组内最后一个元素为数组时作为该组各文本的区域:
//    aiTxt([["~=拜访", "获得", [null, "left"]]])
//    → "~=拜访" 全屏查找, "获得" 左半屏查找
//    组内也可用 {region: ...} 对象指定区域(v1.1.0 新增):
//    aiTxt([["~=每日任务", {region: "top"}]])
//    → 在上半屏查找 "~=每日任务"
//    aiTxt([[["t1","t2"], {region: ["rb", "lb"]}]])
//    → t1 在右下查找, t2 在左下查找
//
// 5. count/distance 增强模式(AND 模式或多组模式组内):
//    AND 模式: aiTxt(["文本1", "文本2"], {region: ["区域1", "区域2"], count:[n1,n2], distance:[refIdx,"min"|"max"]})
//    多组模式: aiTxt([["文本1", "文本2", ["区域1", "区域2"], {count:[n1,n2], distance:[refIdx,"min"|"max"]}]])
//    options 对象属性(均为可选):
//      count — 数组,每个文本需要选取的匹配数量,默认 [1, 1, ...]
//      distance — [基准文本索引, "min"|"max"]
//        基准文本索引: 0=第一个文本, 1=第二个文本, ...(以该文本第一个匹配的中心点为基准点)
//        "min": 其他文本选距离基准最近的匹配; "max": 选最远的
//    使用 count/distance 时结果额外附带 .matchedByIndex(按文本索引分组的二维数组)
//
// options 字段:
//   region — 区域表达式(字符串或数组),默认 null(全屏)
//     当 region 为数组时触发 AND 模式,每个元素对应一个文本的区域
//   pair — 配对检测模式(多组模式下使用)
//   non — 排除文本,屏幕上存在任一排除文本时返回 null
//   click — true 找到后自动点击
//   check — 点击后验证(隐含 click)
//   checkWait — check 等待时间(ms),默认 500
//   checkRetry — 最大重试次数,默认 3
//   log — 输出搜索过程日志
//   isInstalled — 从匹配文本中提取应用名,查找已安装应用包名
//   getTimeCount — 从匹配文本中提取时间数字和单位,转为秒数
// 返回:
//   单文本 → {text, center, confidence?, source} 或 null
//   多文本查找 → [{text, center, ...}, ...]
//   AND 模式 → {text, center, matched: [...]} 或 null
//   多组模式 → {index, data, matched?} 或 null(3.1.7+54 精简,旧 [null,{...},null] 数组格式已移除)
//   count/distance 模式 → 额外附带 .matchedByIndex(二维数组,按文本索引分组,非枚举)
//   source 值: 'ui'(来自 UI 控件)或 'ocr'(来自 OCR 识别)
// 区域表达式:
//   null 或 'all' — 全屏
//   'left','right','top','bottom','lt','lb','rt','rb' — 预定义区域
//   'W/2>W,0>H/2' — 自定义坐标范围

// 示例1: 查找单个文本(默认包含匹配)— UI 优先,OCR 回退
var at1 = aiTxt("登录");
if (at1) {
    log("aiTxt 找到: " + at1.text + " source=" + at1.source + " @ " + at1.center);
    if (at1.confidence !== undefined) {
        log("  OCR 置信度: " + at1.confidence);
    }
}

// 示例2: 匹配语法前缀
var at2a = aiTxt("=登录");      // 精确匹配:text 或 desc 完全等于 "登录"
var at2b = aiTxt("~=登录");     // 包含匹配(等价于 aiTxt("登录"))
var at2c = aiTxt("^=登");       // 前缀匹配:text 或 desc 以 "登" 开头
var at2d = aiTxt("$=录");       // 后缀匹配:text 或 desc 以 "录" 结尾

// 示例3: 查找多个文本(数组)— 默认多线程模式
// 单次 dumpUiTree + 按需单次 OCR,内存中匹配所有文本
// 无匹配时返回 null
var at3 = aiTxt(["登录", "注册", "忘记密码"]);
if (at3) {
    for (var i = 0; i < at3.length; i++) {
        log("aiTxt[" + i + "]: " + at3[i].text + " source=" + at3[i].source);
    }
} else {
    log("未找到任何匹配文本");
}

// 示例4: 数组中混合匹配语法
var at4 = aiTxt(["=设置", "^=通知", "$=确认", "取消"]);
// "=设置" → 精确匹配, "^=通知" → 前缀匹配, "$=确认" → 后缀匹配, "取消" → 包含匹配(默认)

// 示例5: 正则表达式匹配
var at5a = aiTxt("re=/^\d{4}$/");         // 匹配 4 位数字
var at5b = aiTxt("re=/登录|注册/i");      // 匹配“登录”或“注册”,忽略大小写
var at5c = aiTxt("re=\d+元");            // 匹配“数字+元”,如“100元”
var at5d = aiTxt(["re=/^\d+$/", "re=/[a-z]+@"]); // 数组正则匹配

// 示例6: 带区域过滤
var at6 = aiTxt("确定", {region: "lt"});          // 只在左上角查找
var at6b = aiTxt("确定").region("lt"); // 链式方式,等价
var at6c = aiTxt(["确定", "取消"], {region: "top"}); // 上半屏查找

// 示例6b: 单文本 non 排除(3.1.6+50 修复,此前单文本模式静默忽略 non)
// 语义:主文本命中后,若屏幕上存在任一排除文本(UI 或 OCR 识别),整体返回 null
// 排除文本支持全部匹配语法(=, ~=, ^=, $=, re=),字符串或数组均可
var at6d = aiTxt("~=限时礼包", {non: "开始游戏"});
// 屏幕有"开始游戏"文本 → 返回 null(即使"限时礼包"存在)
// 屏幕无"开始游戏"且"限时礼包"存在 → 返回匹配结果
// "限时礼包"本身不存在 → 返回 null(不触发 non 检查)
if (at6d) {
    log("限时礼包可用(开始游戏不在屏幕上)");
}

// 多个排除文本:任一存在即返回 null
var at6e = aiTxt("~=领取奖励", {non: ["~=跳过", "re=/广告|推送/"]});
// 选择器格式输入同样支持 non
var at6f = aiTxt("text=领取", {region: "top", non: "~=跳过"});

// 示例7: AND 模式 —— 所有文本必须同时存在
// 在左侧查找“确定”,在右侧查找“取消”,两个都找到才返回
var at7 = aiTxt(["确定", "取消"], {region: ["lt", "rt"]});
if (at7) {
    log("AND 匹配成功: " + at7.text + " @ " + at7.center);
    log("  匹配的全部文本:");
    for (var i = 0; i < at7.matched.length; i++) {
        log("  [" + i + "]: " + at7.matched[i].text + " @ " + at7.matched[i].center);
    }
    click(at7);              // 点击第一个匹配(确定)
    click(at7.matched[1]);   // 点击第二个匹配(取消)
} else {
    log("未同时找到 '确定' 和 '取消'");
}

// 两个文本都在屏幕下方才返回
var at7b = aiTxt(["确定", "解锁奖励"], {region: ["bottom", "bottom"]});
if (at7b) {
    log("两个文本都在底部: " + at7b.matched[0].text + ", " + at7b.matched[1].text);
}

// 示例7c: AND 模式 + null 区域(全屏查找)
// 第一个文本全屏查找,第二个文本只在左半屏查找
var at7c = aiTxt(["确定", "取消"], {region: [null, "left"]});
if (at7c) {
    log("AND 匹配: " + at7c.text + " + " + at7c.matched[1].text + " (left)");
}

// 示例8: 使用区域表达式(device.width / device.height)
var at8 = aiTxt("提交", {region: "device.width/2>device.width,0>device.height/2"});  // 右上角区域

// 示例9: 多组模式 —— 返回 {index, data, matched?},index 判断哪个组匹配
// 组1: "确定" 和 "解锁奖励" 都存在
// 组2: 包含 "子不足" 和 包含 "获得" 都存在
// 组3: 包含 "拜访" (全屏) 和 "获得" (左半屏) 都存在
// 组2匹配时返回示例: {index: 1, data: {text:"体力不足", center:[x,y], source:"ocr"}}
var at9 = aiTxt([
    ["确定", "解锁奖励"],                    // 组1: 两个文本都全屏查找
    ["~=子不足", "~=获得"],                  // 组2: 两个文本都全屏查找
    ["~=拜访", "获得", [null, "left"]]      // 组3: 拜访全屏, 获得左半屏
]);

// 通过 .index 快速判断(无匹配时 at9 为 null)
switch (at9 ? at9.index : -1) {
    case 0:
        log("组1匹配: 确定 + 解锁奖励");
        click(at9.data);                   // 点击 "确定"
        click(at9.matched[0]);             // 点击 "解锁奖励"(组内第2个匹配在 matched[0])
        break;
    case 1:
        log("组2匹配: 子不足 + 获得");
        click(at9.data);                   // 点击第一个匹配
        break;
    case 2:
        log("组3匹配: 拜访 + 获得(左)");
        click(at9.data);
        break;
    default:
        log("所有组均未匹配");
}

// 示例9b: 多组模式 — 单组 AND(等价于 AND 模式)
// 用多组语法实现单组 AND,区域内嵌在组数组中
var at9b = aiTxt([["确定", "取消", ["lt", "rt"]]]);
// 返回 {index: 0, data: {text:"确定",...}, matched:[{text:"取消",...}]} 或 null
if (at9b) {
    log("单组 AND: " + at9b.data.text + " + " + at9b.matched[0].text);
}

// 示例9c: count/distance 增强模式 — 按距离筛选多个匹配
// 场景: 屏幕上有多个"确定"按钮和1个"取消"按钮
// 需求: 找到2个"确定"和1个"取消",且"确定"必须是距离"取消"最近的2个
//
// count=[2,1]     → "确定"找2个,"取消"找1个
// distance=[1,"min"] → 以索引1(取消)为基准,选距离最近的(min)
//   索引 0 = "确定",索引 1 = "取消"
//   "min" = 距离最小(最近),"max" = 距离最大(最远)

// 多组模式写法(options 内嵌在组数组最后一个元素)
var at9c = aiTxt([["确定", "取消", ["lt", "rt"], {count: [2, 1], distance: [1, "min"]}]]);
if (at9c) {
    // at9c.data 是第一个选中的匹配;at9c.matched 是其余匹配(按距离排序)
    log("count/distance 模式匹配成功: " + (1 + at9c.matched.length) + " 个结果");
    log("  [0]: " + at9c.data.text + " @ " + at9c.data.center);
    for (var i = 0; i < at9c.matched.length; i++) {
        log("  [" + (i + 1) + "]: " + at9c.matched[i].text + " @ " + at9c.matched[i].center);
    }
    // at9c.matchedByIndex 是按文本索引分组的二维数组(非枚举,JSON.stringify 不显示)
    // matchedByIndex[0] = "确定"的2个匹配(距离"取消"最近的2个)
    // matchedByIndex[1] = "取消"的1个匹配(基准)
    var confirms = at9c.matchedByIndex[0];  // 2个"确定"
    var cancels = at9c.matchedByIndex[1];   // 1个"取消"
    log("最近的2个确定:");
    log("  确定1: " + confirms[0].center);
    log("  确定2: " + confirms[1].center);
    log("取消(基准): " + cancels[0].center);
    // 依次点击
    click(confirms[0]);
    click(confirms[1]);
}

// AND 模式写法(options 作为第三参数)
var at9c2 = aiTxt(["确定", "取消"], {region: ["lt", "rt"], count: [2, 1], distance: [1, "min"]});
if (at9c2) {
    log("AND + count/distance: 共 " + at9c2.matched.length + " 个结果");
    var confirms2 = at9c2.matchedByIndex[0];
    var cancels2 = at9c2.matchedByIndex[1];
    click(confirms2[0]);
    click(confirms2[1]);
}

// 示例9d: count 模式(无 distance)— 每个文本选取前 N 个匹配
// 找到3个"金币"图标和2个"钻石"图标
var at9d = aiTxt([["金币", "钻石", {count: [3, 2]}]]);
if (at9d[0]) {
    var coins = at9d[0].matchedByIndex[0];   // 3个"金币"
    var gems = at9d[0].matchedByIndex[1];    // 2个"钻石"
    log("找到 " + coins.length + " 个金币, " + gems.length + " 个钻石");
}

// 示例9e: distance max 模式 — 选距离基准最远的匹配
// 找到1个" Boss" 和2个"小怪",且"小怪"是距离"Boss"最远的2个
var at9e = aiTxt([["Boss", "小怪", {count: [1, 2], distance: [0, "max"]}]]);
if (at9e[0]) {
    var boss = at9e[0].matchedByIndex[0];    // 1个"Boss"(基准)
    var mobs = at9e[0].matchedByIndex[1];    // 2个"小怪"(距离Boss最远的2个)
    log("Boss @ " + boss[0].center);
    log("最远的小怪1: " + mobs[0].center);
    log("最远的小怪2: " + mobs[1].center);
}

// 示例9f: 多组模式 — 组内 options.region 指定区域(v1.1.0 新增)
// 每个组可以在末尾放一个 {region: ...} 对象来指定该组的搜索区域
//
// region 为字符串时:组内所有文本共用同一区域
// region 为数组时:按文本索引逐个分配区域
//
// 扁平格式 — 文本 + options.region(字符串 = 所有文本共用)
// aiTxt([["~=每日任务", {region: "top"}]])
// → 在上半屏查找 "~=每日任务"
//
// 嵌套格式 — 文本数组 + options.region(数组 = 按文本索引分配)
// aiTxt([[["~=娱乐得奖", "~=捕捉"], {region: ["rb", "lb"]}]])
// → 右下找 "~=娱乐得奖",左下找 "~=捕捉"
//
// 混合多组示例:
var at9f = aiTxt([
    ["~=每日任务", {region: "top"}],                          // 组1: 扁平格式, 上半屏
    [["~=娱乐得奖", "~=捕捉"], {region: ["rb", "lb"]}],        // 组2: 嵌套格式, 右下+左下
]);
if (at9f) {
    switch (at9f.groupIndex) {
        case 0:
            log("组1匹配: 每日任务 (上半屏)");
            click(at9f[0]);
            break;
        case 1:
            log("组2匹配: 娱乐得奖(右下) + 捕捉(左下)");
            click(at9f[1]);
            break;
        default:
            log("所有组均未匹配");
    }
}

// 示例9g: 组内 options.region 与 count/distance 组合
// region 指定区域,count/distance 控制匹配数量和距离筛选
var at9g = aiTxt([
    ["确定", "取消", {region: ["lt", "rt"], count: [2, 1], distance: [1, "min"]}],
]);
// → 左上找2个"确定",右上找1个"取消",以"取消"为基准选距离最近的2个"确定"
if (at9g[0]) {
    var confirms9g = at9g[0].matchedByIndex[0];
    var cancels9g = at9g[0].matchedByIndex[1];
    log("组内 region + count/distance: " + confirms9g.length + "个确定, " + cancels9g.length + "个取消");
}

// 示例9h: 多组模式 — 末尾 options 对象(v1.1.0 新增)
// options 对象放在 groups 数组末尾(外层),对所有组生效
// 等价于作为第二参数传入: aiTxt(groups, options)
//
// 用法: aiTxt([["t1","t2"], ["t3","t4"], {distance: [0, "min"]}])
// → groups 为 [["t1","t2"], ["t3","t4"]],options 为 {distance: [0, "min"]}
//
// 实战示例:多组 AND + distance 距离筛选
var at9h = aiTxt([
    ["~=完成浏览", "去浏览", "re=/\\d+/\\d+/"], { distance: [0, "min"] }
]);
// → 单组多文本 AND 模式:3个文本必须同时存在
//   distance: [0, "min"] → 以第1个文本("~=完成浏览")为基准,选距离最近的匹配
if (at9h) {
    log("找到浏览任务: " + at9h[0].text);
    click(at9h[0].matched[0]);
}

// 末尾 options 也可与第二参数 options 合并(内联优先)
// aiTxt([["t1","t2"]], {pair: true})               → pair 模式
// aiTxt([["t1","t2"], {distance: [0, "min"]}], {pair: true}) → 合并:pair + distance

// 示例10: 实战 — 找到并直接点击(不需要手动取中心点)
var btn = aiTxt("立即开始");
if (btn) {
    click(btn);     // 直接传 aiTxt 返回的对象,click 自动提取 center
} else {
    log("未找到 '立即开始' 按钮");
}

// 示例11: 实战 — aiTxt + longClick
var item = aiTxt("设置");
if (item) {
    longClick(item, {duration: 2000});  // 长按 2 秒
}

// 示例12: aiTxt click 选项 — 找到后自动点击
// aiTxt("你好", {region: "top", click: true})
//   找到 "你好" 后自动点击,返回匹配结果(无需手动调 click)
var result = aiTxt("立即开始", {region: "top", click: true});
if (result) {
    log("已点击 '立即开始'");
} else {
    log("未找到 '立即开始'");
}

// 示例13: aiTxt check: true — 保存原始坐标,点击后比较坐标判断点击是否成功
// aiTxt("登录", {check: true})
//   找到"登录"后点击 → 等待0.5s → 再次查找"登录":
//   - 未找到 → 成功(原元素已消失)
//   - 找到但坐标不同 → 成功(原元素消失,这是另一个同名元素)
//   - 找到且坐标相同 → 失败 → 重新点击(重试 checkRetry=3 次)
var checked = aiTxt("登录", {check: true});
if (checked) {
    log("登录按钮点击成功(已消失或坐标变化)");
} else {
    log("登录按钮点击失败(重试后仍在原位置)");
}

// 示例14: aiTxt check: [text, region] — 点击后验证文字出现,未找到则重新点击原始元素重试
// aiTxt("登录", {check: ["我们", "bottom"]})
//   找到"登录"后点击 → 等待 → 在 bottom 区域查找"我们":
//   - 找到 → 成功(仅验证,不点击"我们")
//   - 未找到 → 重新查找并点击"登录" → 再次检查(重试)
var verify = aiTxt("登录", {check: ["我们", "bottom"]});
if (verify) {
    log("登录成功,已验证'我们'出现");
} else {
    log("登录失败,重试后仍未出现'我们'");
}

// 示例15: aiTxt check: [text] — 不带 region,全屏验证
// aiTxt("登录", {check: ["欢迎回来"]})
//   找到"登录"后点击 → 查找"欢迎回来"(全屏):
//   - 找到 → 成功,未找到 → 重新点击"登录"重试
var login = aiTxt("登录", {check: ["欢迎回来"]});
if (login) {
    log("登录成功");
} else {
    log("登录失败");
}

// 示例16: aiTxt check: [text, {check: true}] — 验证文字出现后,对该文字执行 check
// aiTxt("登录", {check: ["欢迎回来", {check: true}]})
//   找到"登录"后点击 → 查找"欢迎回来" → 找到后对"欢迎回来"执行 {check: true}:
//   即保存"欢迎回来"坐标 → 点击 → 重新查找比较坐标
var login2 = aiTxt("登录", {check: ["欢迎回来", {check: true}]});
if (login2) {
    log("登录成功,已验证'欢迎回来'并处理");
} else {
    log("登录失败或'欢迎回来'处理失败");
}

// 示例17: aiTxt check: [text, {click: true}] — 验证文字出现后点击该文字(不验证)
// aiTxt("登录", {check: ["欢迎回来", {click: true}]})
//   找到"登录"后点击 → 查找"欢迎回来" → 找到后点击"欢迎回来"(不验证)
var login3 = aiTxt("登录", {check: ["欢迎回来", {click: true}]});
if (login3) {
    log("已点击'欢迎回来'");
} else {
    log("登录失败或未找到'欢迎回来'");
}

// 示例18: aiTxt check + checkWait + checkRetry — 自定义等待和重试次数
// checkWait: 每次检查前等待 ms(默认 500)
// checkRetry: 最大重试次数(默认 3)
var slow = aiTxt("提交", {region: "bottom", check: true, checkWait: 1000, checkRetry: 5});
if (slow) {
    log("提交成功");
} else {
    log("提交失败,重试5次后仍在原位置");
}

// 示例19: aiTxt click + log — 调试模式下的自动点击
// log: true 输出搜索过程日志(UI 文本 + OCR 文本),方便调试
var debug = aiTxt("登录", {click: true, log: true});
if (debug) {
    log("登录按钮已点击: " + debug.text);
}

// 示例20: 统一 (para, options) 写法 — 推荐用法
// 所有可选参数都放在 options 对象中,无需关心参数顺序
var skillsArea = setRect("skillsArea", {hint: "设置学习的技能区域"});

// pair 模式:逐组按优先级匹配
// 每组第一个元素为基准关键词,先检查基准是否在区域内:
//   - 基准在区域内 → 尝试与剩余元素配对(同一条文本同时包含两个关键词)
//     - 配对成功 → 返回 [匹配元素, 基准, 配对]
//     - 配对失败 → 仍返回基准匹配 [匹配元素, 基准, null](不会跳到下一组)
//   - 基准不在区域内 → 跳到下一组继续
// 这确保高优先级组(如"子弹")只要基准存在就不会被低优先级组(如"旋风")抢匹配

// 旧写法: aiTxt(groups, skillsArea, {pair: true})  — region 和 options 分开传
// 新写法: region 放入 options,更清晰
var u1 = aiTxt([
    ["子弹", "全", "伤害", "re=/分裂|弹道/", "穿透", "电磁", "爆炸"],
    ["制导", "re=/获得|学习/", "re=/.+/"],
], {region: skillsArea, pair: true});
if (u1) {
    // u1[0] = 匹配元素({text, center} 或文本字符串)
    // u1.groupIndex = 匹配组索引, u1.pairIndex = 配对索引(-1表示仅基准匹配无配对)
    // u1.base = 基准关键词, u1.other = 配对关键词(null表示无配对)
    click(u1[0]);
    log("组" + u1.groupIndex + " 基准=" + u1.base + " 配对=" + u1.other);
}

// 新写法: click + check 一体化
var u2 = aiTxt("登录", {region: "top", click: true, check: true, log: true});

// 新写法: 多组模式 + 区域 + pair
var u3 = aiTxt([
    ["~=干冰弹", "学习", "获得", "re=/.+/"],
    ["温压弹", "re=/学习|获得/", "爆炸"],
], {region: skillsArea, pair: true});
if (u3) {
    log("匹配组: " + u3.groupIndex + ", 文本: " + u3.matchedText);
}

// 示例20b: pair + score 模式 — 按组合总分选择最佳匹配 (1.9.5 改进)
// 组合总分模式:遍历每条屏幕文本,计算该文本匹配到的所有组关键词的累计得分
// 一条同时包含「电磁」和「制导」的文本,总分 = 85+85=170,
// 会优先于只包含「电磁+追捕」(85+84=169) 的文本被选中
//
// 组内配对项得分按顺序递减:base=80, 第1个配对=79, 第2个=78, 第3个=77...
// 基准单独匹配(无配对)时得分 = groupScore * 0.5(惩罚)
// 适合场景: 屏幕上同时出现"电磁分流带"和"电磁和制导"时,选总分更高的后者
var u4 = aiTxt([
    ["子弹", "全", "分裂", "穿透"],         // score=80: 子弹=80, 全=79, 分裂=78, 穿透=77
    ["电磁", "追捕", "矩阵"],               // score=100: 电磁=100, 追捕=99, 矩阵=98
    ["制导", "学习", "获得"],               // score=60: 制导=60, 学习=59, 获得=58
], {region: skillsArea, pair: true, score: [80, 100, 60]});
if (u4) {
    click(u4[0]);
    log("选中技能: " + u4.base + " + " + u4.other + ", 总分=" + u4.score);
    // u4.score 是组合总分:该文本匹配到的所有关键词的累计得分
    // u4.matchedItems 是该文本匹配到的所有关键词列表
    //   [{base:"电磁", other:"追捕", score:99, groupIndex:1, pairIndex:0}, ...]
    
    // 场景说明:
    //   屏幕文本A "电磁分流带" → 匹配电磁+分流 → 总分=100+(100-2)=198
    //   屏幕文本B "电磁和制导" → 匹配电磁(基准,无配对,100*0.5=50)+制导(基准,无配对,60*0.5=30) → 总分=80
    //   → 选文本A,因为 198 > 80
    
    //   但如果改为: score:[85,85]
    //   屏幕文本A "电磁分流带" → 匹配电磁+分流 → 总分=85+83=168
    //   屏幕文本B "电磁和制导" → 匹配电磁(85*0.5=42.5)+制导(85*0.5=42.5) → 总分=85
    //   → 仍然选文本A
    //
    //   如果文本B是 "电磁追捕和制导学习":
    //   → 匹配电磁+追捕(85+84=169)+制导+学习(85+84=169) → 总分=338 >> 文本A的168
    //   → 选文本B,因为同时匹配了两组的完整配对
}

// 示例20c: pair + score — 配对项单独指定得分
// 数组形式 ["文本", 得分] 可为每个配对项指定独立得分
// 指定得分的配对项不再递减,使用指定值;未指定的仍按组得分递减
// 组合总分模式下:一条文本匹配多个配对时,所有配对得分累加
var u5 = aiTxt([
    ["电磁", ["追捕", 95], ["分流", 70], ["矩阵", 60]],
    ["子弹", ["分裂", 85], ["穿透", 75]],
], {region: skillsArea, pair: true, score: [80, 90]});
if (u5) {
    click(u5[0]);
    log("选中: " + u5.base + " + " + u5.other + ", score=" + u5.score);
    // 如果"电磁+追捕"(score=95)和"子弹+分裂"(score=85)同时匹配,
    // 返回 score=95 的"电磁+追捕"组合
}

// 示例20d: pair + texts — 复用文本池,避免二次截图
// pair 模式返回的结果附带 .__texts 属性(UI+OCR 文本池)
// 传入 texts 参数可复用,跳过截图和 OCR,提高性能
// 适用场景: 先检测界面状态,再根据状态在同一个文本池中搜索技能

// 第一次 aiTxt: 截图 → 识别界面状态,__texts 中包含所有 UI+OCR 文本
var screen = aiTxt([
    ["~=选择技能"],
    ["~=返回"],
    ["~=开始游戏"],
], {pair: true, log: true});

if (screen && screen.base.indexOf("选择技能") >= 0) {
    // 第二次 aiTxt: 复用文本池,不再截图,直接在已有文本中搜索技能
    var skill = aiTxt([
        ["子弹", "全", "分裂", "穿透"],
        ["电磁", "追捕", "矩阵"],
        ["制导", "学习", "获得"],
    ], {pair: true, score: [80, 100, 60], texts: screen.__texts});
    if (skill) {
        click(skill[0]);
        log("选中技能: " + skill.base + " + " + skill.other + ", score=" + skill.score);
    }
}

// 示例20e: reuse — 非 pair 模式下收集文本池,供后续 aiTxt 复用
// reuse: true 让 aiTxt 收集当前屏幕的所有 UI+OCR 文本,附加到返回结果的 .__texts 属性
// 与 pair 模式不同,reuse 不需要配对检测,仅收集文本池
// 即使匹配结果为 null,__texts 仍会被收集(返回 {matched:false, __texts:[...]} 对象)
// 用法: var r = aiTxt([["~=某文本"]], {reuse: true}); → r.__texts 可传入后续 aiTxt 的 texts 参数
var screen2 = aiTxt([
    ["~=选择技能"],
    ["~=返回"],
    ["~=开始游戏"],
], {reuse: true});  // 不写 pair,用 reuse 收集文本池

// 后续 aiTxt 复用文本池,跳过截图和 OCR
if (screen2 && screen2.__texts) {
    var skill2 = aiTxt([
        ["子弹", "全", "分裂", "穿透"],
        ["电磁", "追捕", "矩阵"],
    ], {pair: true, score: [80, 100], texts: screen2.__texts});
    if (skill2) {
        click(skill2[0]);
        log("选中技能: " + skill2.base + " + " + skill2.other);
    }
}

// 示例21: confidence — 过滤低置信度的 OCR 结果
// confidence 参数控制 OCR 匹配的最低置信度阈值 (0~1)
// 仅影响 source='ocr' 的结果(UI 控件树匹配不受影响)
// 默认 0(不过滤),设置为 0.8 表示只返回置信度 ≥ 0.8 的 OCR 结果
// 适用场景:OCR 识别模糊文字时,过滤掉低置信度的误匹配
var r1 = aiTxt("设置", {confidence: 0.8});  // 只返回置信度 ≥ 0.8 的结果
if (r1) {
    log("找到: " + r1.text + " source=" + r1.source);
    if (r1.source === 'ocr') {
        log("  OCR 置信度: " + r1.confidence);  // ≥ 0.8
    }
}

// confidence + 区域过滤
var r2 = aiTxt("确定", {region: "bottom", confidence: 0.85});
if (r2) {
    click(r2);
}

// confidence + 数组模式 — 多文本查找,每个匹配都受阈值约束
var r3 = aiTxt(["登录", "注册"], {confidence: 0.8});
if (r3) {
    r3.forEach(function(item) {
        if (item.source === 'ocr') {
            log(item.text + " 置信度=" + item.confidence);  // 所有都 ≥ 0.8
        }
    });
}

// confidence + AND 模式
var r4 = aiTxt(["确定", "取消"], {region: ["lt", "rt"], confidence: 0.9});
if (r4) {
    log("AND 匹配成功(所有 OCR 结果置信度 ≥ 0.9)");
}

// confidence + click 自动点击
var r5 = aiTxt("立即开始", {confidence: 0.8, click: true});
if (r5) {
    log("已点击高置信度匹配");
}

// findOne 统一写法
var f1 = findOne("text=登录", {timeout: 5000, region: "top", click: true});
var f2 = findOne("text=登录", {timeout: 3000, check: true});

// findAll 统一写法
var fa1 = findAll("text=关闭", {region: "top", non: "~=跳过"});

// waitFor 统一写法(mode: ocr/ui/act/pkg,支持 disappear 等待消失)
var w1 = waitFor("加载完成", {timeout: 10000, region: "top", log: true});
var w2 = waitFor("完成", {region: skillsArea, interval: 500});
var wu1 = waitFor("text=登录", {timeout: 5000, region: "top", log: true});
var wa1 = waitFor("LoginActivity", {mode: "act", timeout: 5000});
var wp1 = waitFor("com.mm.td", {mode: "pkg", timeout: 10000});
var g1 = waitFor("加载中", {timeout: 30000, disappear: true});

// findColor 统一写法
var fc1 = findColor("#FF0000", {tolerance: 10, region: "lt"});

// findImage 统一写法
var fi1 = findImage("template.png", {threshold: 0.9, region: "rt"});

// findMultiColors 统一写法(第三个参数为 options)
var fm1 = findMultiColors({color: "#00FF00", offsets: [[10, 0, "#FF0000"], [20, 0, "#0000FF"]]}, {tolerance: 5, region: "lt"});

全局信息查询

func currentPackage

declare function currentPackage(): string
获取当前前台应用包名 (已过滤系统 UI 包名)
@returns 包名字符串,失败返回 ""

func currentActivity

declare function currentActivity(): string
获取当前前台 Activity 类名
查询优先级:
1. dumpsys activity activities 的 Resumed 行
2. 无障碍事件缓存的 className
3. UsageStatsManager (仅包名)
4. Activity 历史记录回退 (长度 5,元素唯一)
5. 应用自身包名 (最终回退,不返回空字符串)

func currentComponent

declare function currentComponent(): string
获取当前前台组件名
@returns "包名/活动名" 格式字符串

通用工具

func sleep

declare function sleep(ms: number): void
阻塞等待 (可中断)
每 100ms 检查一次 stop_flag,若为 true 则抛出 Error("脚本已被用户停止")
@param ms 等待毫秒
📄 示例:009_sleep.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// sleep(ms)
// ============================================================

// --- sleep(ms) ---
// 阻塞等待。参数:ms (int/number, 毫秒),无默认值。
sleep(1000);   // 等待 1 秒
sleep(500);    // 等待 0.5 秒

func humanPause

declare function humanPause(minMs: number, maxMs?: number): void
阅读停顿(P2.5 行为节律):随机等待 [minMs, maxMs] 毫秒后返回
模拟「打开页面 → 阅读 → 再操作」的人类停顿,避免操作间隔恒定。
maxMs 缺省时区间为 [minMs, minMs*2]。随机源为引擎原生 RNG,
跨运行不重复(Math.random 引擎级可复现,勿用于反节律场景)。
可被用户停止(内部走可中断 sleep);参数非法时按 0 处理。
@param minMs 最短等待毫秒
@param maxMs 最长等待毫秒(缺省 = minMs*2)
@example
```js
openApp("com.x"); // 打开页面后
humanPause(1500, 6000); // 随机阅读 1.5~6 秒再操作
click(540, 1200);
```

func log

declare function log(...args: any[]): void
输出日志
@param args 任意多个参数
📄 示例:010_log.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 1. 基础操作
// log(msg)
// ============================================================

// --- log(msg) ---
// 输出日志到控制台。参数:msg (any),无默认值。
log("这是一条日志");
log(42);
log(true);
log({ key: "value" });

func exit

declare function exit(pushUi?: boolean): void
立即停止当前脚本执行(等效于 engine.stop 当前脚本)
@param pushUi 是否在退出时推送界面分析(截图+UI 树)到 VSCode 控制台
- exit() / exit(false) — 正常退出,不推送
- exit(true) — 退出并推送界面分析(受「脚本退出推送界面分析」总开关控制)
@example
// 正常退出
exit();
// 退出并推送界面分析到 PC 端
exit(true);

func pushUI

declare function pushUI(): string
主动推送界面分析到 PC 端(VSCode 控制台)并保存到文件夹
脚本运行中随时可调用,采集当前界面截图+UI 树+Activity 信息,
推送到 VSCode 控制台 webview 显示,同时保存到 PC 端
{workspace}/.autoengine/ui-snapshots/ 文件夹:
- {timestamp}_{taskName}.json — 完整数据
- {timestamp}_{taskName}.png — 截图图片
与 exit(true) 的区别:
- pushUI() 不退出脚本,只推送界面分析
- exit(true) 退出脚本并推送界面分析
不受「脚本退出推送界面分析」总开关控制(脚本主动请求,始终推送)。
但仍需以下条件才能送达 VSCode 端:
1. 无障碍服务已启用
2. 截图权限已授予
3. WebEditorServer 正在运行
4. VSCode 扩展 webview 已打开
@returns JSON 字符串 {success: true} 或 {success: false, error: "..."}
@example
// 采集当前界面并推送到 PC 端
var result = pushUI();
console.log(result); // {"success":true}
// 在关键步骤推送界面快照,便于后续分析
aiTxt("登录");
pushUI(); // 保存登录界面快照
click(500, 800);
sleep(2000);
pushUI(); // 保存登录后界面快照
📄 示例:177_pushUI.js(点击展开)
// 脚本运行中随时可调用,采集当前界面截图+UI 树+Activity 信息,
// 推送到 VSCode 控制台 webview 显示,同时保存到 PC 端 C:\uianalyze 文件夹。
//
// 与 exit(true) 的区别:
//   - pushUI() 不退出脚本,只推送界面分析
//   - exit(true) 退出脚本并推送界面分析
//
// 不受「脚本退出推送界面分析」总开关控制(脚本主动请求,始终推送)。
// 仍需以下条件才能送达 VSCode 端:
//   1. 无障碍服务已启用
//   2. 截图权限已授予
//   3. WebEditorServer 正在运行
//   4. VSCode 扩展 webview 已打开
//
// 返回: JSON 字符串 {success: true} 或 {success: false, error: "..."}

// ============================================================
// flutter-auto API 示例 — 33. pushUI — 主动推送界面分析到 PC 端
// 33. pushUI — 主动推送界面分析到 PC 端
// ============================================================


// 示例1: 采集当前界面并推送到 PC 端
var result = pushUI();
console.log(result);  // {"success":true}

// 示例2: 在关键步骤推送界面快照
aiTxt("登录");
pushUI();  // 保存登录界面快照

click([500, 800]);
sleep(2000);

if (aiTxt("登录失败")) {
    pushUI();  // 保存失败界面快照,便于调试
    exit(true);  // 退出并再次推送(可选)
}

// 示例3: 循环中定期推送
for (var i = 0; i < 10; i++) {
    var node = findOne("text=第" + (i + 1) + "关", {timeout: 3000});
    if (node) {
        pushUI();  // 每关推送一次界面快照
        sleep(2000);
    }
}

// 保存位置: C:\uianalyze\
// 文件格式:
//   {yyyy-MM-dd_HHmmss}_{taskName}.json — 完整数据(截图 base64 + UI 树 + Activity 信息)
//   {yyyy-MM-dd_HHmmss}_{taskName}.png  — 截图图片

定时器 (基于子线程)

func setTimeout

declare function setTimeout(callback: Function, delay?: number): number
延时执行 (启动子线程,sleep(delay) 后执行 callback)
@param callback 回调函数
@param delay 延时毫秒,默认 0
@returns timerId

func setInterval

declare function setInterval(callback: Function, delay?: number): number
循环执行
@param delay 间隔毫秒,默认 0 (内部强制 ≥1)
@returns timerId

func clearTimeout

declare function clearTimeout(timerId: number): void
清除延时定时器

func clearInterval

declare function clearInterval(timerId: number): void
清除循环定时器

事件监听 (events 模块 — Toast / Notification)

interface ToastEvent

Toast 事件 payload
字段类型说明
textstring Toast 文本内容
packageNamestring Toast 来源包名
📋 类型定义原文
interface ToastEvent {
}

interface NotificationEvent

通知事件 payload
字段类型说明
packagestring 通知来源包名
titlestring 通知标题
textstring 通知正文
timenumber 通知发布时间(毫秒时间戳)
📋 类型定义原文
interface NotificationEvent {
}

interface EventEmitter

EventEmitter 类 — 事件发射器
📋 类型定义原文
interface EventEmitter {
    setMaxListeners(n: number): this;
    getMaxListeners(): number;
    on(eventName: string, listener: Function): this;
    addListener(eventName: string, listener: Function): this;
    once(eventName: string, listener: Function): this;
    prependListener(eventName: string, listener: Function): this;
    prependOnceListener(eventName: string, listener: Function): this;
    removeListener(eventName: string, listener: Function): this;
    removeAllListeners(eventName?: string): this;
    emit(eventName: string, ...args: any[]): boolean;
    listeners(eventName: string): Function[];
    listenerCount(eventName: string): number;
    eventNames(): string[];
}

func sync

declare function sync(func: Function): Function
函数同步锁包装器
返回新函数,执行时自动 lock()/unlock(),保证同一时间只有一个线程执行
@param func 要包装的函数
@returns 包装后的函数
📄 示例:110_sync.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 10. Threads 模块(多线程支持)
// sync(func) — 函数同步锁包装器
// ============================================================

// --- sync(func) — 函数同步锁包装器 ---
// 返回一个新函数,该函数在执行时自动加锁/解锁,保证同一时间只有一个线程执行。
// 参数:func (function),无默认值。
// 返回包装后的函数。

// 示例1: 基本使用
var safeIncrement = sync(function(x) {
    return x + 1;
});
log("safeIncrement(5) = " + safeIncrement(5));  // 6

// 示例2: 保护共享资源
var safeCounter = 0;
var incrementCounter = sync(function() {
    safeCounter++;
    return safeCounter;
});

var syncWorkers = [];
for (var i = 0; i < 10; i++) {
    syncWorkers.push(threads.start(function() {
        for (var j = 0; j < 100; j++) {
            incrementCounter();
        }
    }));
}
for (var i = 0; i < syncWorkers.length; i++) {
    syncWorkers[i].join();
}
log("10 个线程各自增 100 次,最终计数: " + safeCounter);  // 1000

// 示例3: 综合多线程示例 — 并行 OCR
// 启动多个子线程同时执行不同区域的 OCR,使用 disposable 收集结果
var ocrResults = [];
var ocrLock = threads.lock();

// 将屏幕分成上下两半,两个线程分别 OCR
var halfHeight = Math.floor(device.height / 2);

var topResult = threads.disposable();
var bottomResult = threads.disposable();

var ocrThread1 = threads.start(function() {
    // 子线程可以调用 ocr() 等平台 API
    var results = ocr();
    ocrLock.lock();
    try {
        for (var i = 0; i < results.length; i++) {
            if (results[i].center[1] < halfHeight) {
                ocrResults.push(results[i]);
            }
        }
    } finally {
        ocrLock.unlock();
    }
    topResult.setResult("top done");
});

var ocrThread2 = threads.start(function() {
    var results = ocr();
    ocrLock.lock();
    try {
        for (var i = 0; i < results.length; i++) {
            if (results[i].center[1] >= halfHeight) {
                ocrResults.push(results[i]);
            }
        }
    } finally {
        ocrLock.unlock();
    }
    bottomResult.setResult("bottom done");
});

// 等待两个线程都完成
topResult.blockAndGet();
bottomResult.blockAndGet();

log("并行 OCR 完成,共识别 " + ocrResults.length + " 个文本区域");

// 清理所有子线程
threads.shutDownAll();
log("所有子线程已停止");

数据库快捷函数 (config 命名空间)

func setKey

declare function setKey(key: string, value: any): true
存储键值对 (固定 config 命名空间)
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@param key 键名
@param value 任意可 JSON 序列化的值
@returns true

func getKey

declare function getKey(key: string): any
读取键值 (config 命名空间)
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@returns 存储的值或 null

func delKey

declare function delKey(key: string): true
删除键值 (config 命名空间)
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@returns true

func withKeyLock

declare function withKeyLock(key: string, fn: () => T): T
在全局逻辑锁保护下执行回调,保证复合操作原子性
用于"读-修改-写"等需要多步原子操作的场景。锁是可重入的,
回调内调用 setKey/getKey/delKey 不会死锁。
@param key 用于标识的键名(当前实现为全局锁,key 仅作语义标识)
@param fn 受保护的回调函数,返回值会作为 withKeyLock 的返回值
@returns 回调函数的返回值
@example
// 计数器自增(多线程安全)
withKeyLock("counter", function() {
var v = getKey("counter") || 0;
setKey("counter", v + 1);
});
@example
// 转账原子操作
withKeyLock("transfer", function() {
var from = getKey("accountA") || 0;
var to = getKey("accountB") || 0;
if (from < 100) throw new Error("余额不足");
setKey("accountA", from - 100);
setKey("accountB", to + 100);
});
📄 示例:120_withKeyLock.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 20. ThetaDB 数据库 API
// withKeyLock(key, fn) — 复合操作原子性保护
// ============================================================

// --- withKeyLock(key, fn) — 复合操作原子性保护 ---
// setKey/getKey/delKey 单次调用已自动加全局可重入锁,天然线程安全。
// withKeyLock 用于保护"读-修改-写"等多步复合操作的原子性。
//
// 参数:
//   key (string)    — 用于标识的键名(当前为全局锁,key 仅作语义标识)
//   fn (function)   — 受保护的回调,返回值作为 withKeyLock 的返回值
// 返回:
//   回调函数 fn 的返回值(任意类型)

坐标点管理 (setPosition)

interface CaptureOptions

采集配置类函数(setPosition/setSwipe/setJoystick)的选项
字段类型说明
hintstring 说明文本,描述此配置的用途(必填,不能为空字符串)
📋 类型定义原文
interface CaptureOptions {
}

func setPosition

declare function setPosition(keyOrKeys: K | readonly K[], options: CaptureOptions): { [P in K]: Point }
用户手动设置坐标点(圆圈选点 + 放大镜 + 方向键 + 速度调节)
通过透明 Activity 监听用户点击 + 方向键微调 + 放大镜 + ThetaDB 缓存。
圆圈内随机取点:半径 > 0 时每次调用返回圆内不同的随机点。
工作流程:
1. 检查数据库中是否已存储此键的圆圈(cx, cy, radius)
2. 有缓存 → 生成圆内随机点直接返回
3. 无缓存 → 启动透明 Activity:
a. 截图作为背景,用户点击屏幕选圆心
b. 显示放大镜(圆形)+ 十字准星 + 圆圈范围
c. 显示四方向键(上下左右)→ 微调圆心位置(1px/5px/10px/20px 可调)
d. 显示半径调节按钮(+/-)→ 调整随机范围(0=精确点无随机)
e. 用户点击"确定" → 保存 {cx, cy, radius} 到数据库
f. 用户点击"重来" → 清除当前点重新选点
必须使用对象解构赋值: var {loginBtn} = setPosition(["loginBtn"], {hint: "..."})
也兼容字符串写法: var {loginBtn} = setPosition("loginBtn", {hint: "..."})
@param keyOrKeys 键名字符串或键名数组(必填)
@param options 采集选项,hint 必填
@returns {key: Point} 格式,支持解构赋值,Point 为圆内随机点
@throws 用户取消采集时抛出异常
@example
```js
// 数组写法(推荐,支持多键)
var {loginBtn} = setPosition(["loginBtn"], {hint: "请点击登录按钮位置"});
click(loginBtn.x, loginBtn.y); // 每次点击位置略有不同(圆内随机)
// 字符串写法(单键简写)
var {closeBtn} = setPosition("closeBtn", {hint: "请点击关闭按钮位置"});
// 多键一次采集(逐个弹出)
var {p1, p2} = setPosition(["p1", "p2"], {hint: "请点击两个按钮位置"});
// 设置半径为 0 可获得精确点(无随机)
// 在采集界面按 "-" 按钮将半径调为 0
```
📄 示例:138_setPosition.js(点击展开)
// 通过透明 Activity 监听用户点击坐标,并缓存到 ThetaDB。
// 下次调用时若数据库已有所有键的缓存则直接返回,无需再次手动点击。
//
// 工作流程:
//   1. 检查数据库中是否已有所有键的坐标缓存
//   2. 全部有缓存 → 直接返回坐标对象
//   3. 有键未缓存 → 启动透明 Activity 监听用户点击
//   4. 采集完成 → 屏幕各点位置显示标记(编号圆圈+键名标签),底部显示确认栏
//   5. 确认 → 保存到数据库并返回
//   6. 重来 → 清除标记重新采集
//
// 预览截图功能(所有 set 系列 API 通用):
//   - 采集界面会显示当前屏幕截图作为背景
//   - 双击截图:以双击位置为中心放大 2.5 倍,方便查看细节
//   - 放大后单指拖动:平移查看不同区域
//   - 双指缩放:自由调整缩放倍数(1x~5x)
//   - 再次双击:还原原始大小
//   - 缩放状态下不会触发点击采集,还原后正常采集

// ============================================================
// flutter-auto API 示例 — 22. setPosition — 用户手动设置坐标点
// 22. setPosition — 用户手动设置坐标点
// ============================================================
📄 示例:139_setPosition.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 22. setPosition — 用户手动设置坐标点
// setPosition(keys, options)
// ============================================================

// --- setPosition(keys, options) ---
// 参数:
//   keys (string[]) — 键名数组,如 ["loginBtn", "closeBtn"],长度即为需要点击的次数
//   hint (string)   — 说明文本(必填),描述这些点的用途,采集时会显示在屏幕上
// 返回:
//   {key1: {x, y}, key2: {x, y}, ...}
//   可通过解构赋值获取各个点:var {p1, p2} = setPosition(["p1", "p2"], {hint: "说明"})

// 示例 1: 设置单个坐标点
var {closeBtn} = setPosition(["closeBtn"], {hint: "请点击关闭按钮位置"});
if (closeBtn) {
    log("关闭按钮位置: (" + closeBtn.x + ", " + closeBtn.y + ")");
    click(closeBtn.x, closeBtn.y);
}

// 示例 2: 设置多个坐标点(解构赋值)
var {p1, p2, p3} = setPosition(["p1", "p2", "p3"], {hint: "请依次点击三个按钮位置"});
if (p1 && p2 && p3) {
    log("采集到3个坐标点:");
    log("  p1: (" + p1.x + ", " + p1.y + ")");
    log("  p2: (" + p2.x + ", " + p2.y + ")");
    log("  p3: (" + p3.x + ", " + p3.y + ")");
    // 依次点击
    click(p1.x, p1.y);
    sleep(1000);
    click(p2.x, p2.y);
    sleep(1000);
    click(p3.x, p3.y);
}

// 示例 3: 设置登录和注册按钮位置
var {loginBtn, registerBtn} = setPosition(["loginBtn", "registerBtn"], {hint: "请点击登录按钮和注册按钮"});
if (loginBtn) {
    log("登录按钮位置已保存");
    click(loginBtn.x, loginBtn.y);
}

// 示例 4: 第二次运行同一脚本时,直接使用缓存
// 第一次运行: 弹出透明 Activity,用户手动点击
// 第二次运行: 直接从数据库返回坐标,无需手动操作
var {confirmBtn} = setPosition(["confirmBtn"], {hint: "请点击确认按钮"});
if (confirmBtn) {
    click(confirmBtn.x, confirmBtn.y);
    log("已点击确认按钮");
}
📄 示例:143_setPosition.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 22. setPosition 实战示例
// 22. setPosition 实战示例
// ============================================================


// 场景: 游戏自动化中需要点击固定的骰子按钮和确认按钮
// 首次运行时用户手动指定位置,后续自动执行

// 一次性设置两个按钮位置(首次运行弹出采集界面,后续直接使用缓存)
var {dice, confirm} = setPosition(["dice", "confirm"], {hint: "请依次点击骰子按钮和确认按钮"});
if (dice && confirm) {
    log("骰子位置: (" + dice.x + ", " + dice.y + ")");
    log("确认按钮位置: (" + confirm.x + ", " + confirm.y + ")");

    // 使用坐标执行自动化
    for (var round = 0; round < 10; round++) {
        log("第 " + (round + 1) + " 轮");
        click(dice.x, dice.y);
        sleep(2000);
        click(confirm.x, confirm.y);
        sleep(1000);
    }
}

// 清理缓存(需要重新设置位置时调用)
// delPosition("dice");
// delPosition("confirm");

func getPosition

declare function getPosition(key: string): Point | null
查询已存储的坐标点(每次返回圆内随机点)
坐标点存储格式为圆圈(cx, cy, radius),每次调用 getPosition
都会生成圆内随机点返回。半径为 0 时返回圆心(精确点)。
@param key 键名
@returns 圆内随机点 {x, y},或 null(不存在时)
@example
```js
var pos = getPosition("loginBtn");
if (pos) {
click(pos.x, pos.y); // 每次点击位置略有不同
}
```
📄 示例:140_getPosition.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 22. setPosition — 用户手动设置坐标点
// getPosition(key)
// ============================================================

// --- getPosition(key) ---
// 查询已存储的坐标点(不触发采集,仅查询缓存)。
// 参数:
//   key (string) — 存储键名
// 返回:
//   {x, y} 或 null
var cached = getPosition("loginBtn");
if (cached) {
    log("缓存的登录按钮位置: (" + cached.x + ", " + cached.y + ")");
} else {
    log("未找到缓存的坐标点");
}

func delPosition

declare function delPosition(key: string): true
删除坐标 (即使 key 不存在也返回 true)
@returns true
📄 示例:141_delPosition.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 22. setPosition — 用户手动设置坐标点
// delPosition(key)
// ============================================================

// --- delPosition(key) ---
// 删除已存储的坐标点。
// 参数:
//   key (string) — 存储键名
// 返回:true(即使 key 不存在)
delPosition("loginBtn");                              // 删除单个坐标
delPosition("registerBtn");                           // 删除另一个
log("已删除坐标点缓存");

func listPositions

declare function listPositions(): string[]
列出所有坐标键名
@returns 键名数组
📄 示例:142_listPositions.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 22. setPosition — 用户手动设置坐标点
// listPositions()
// ============================================================

// --- listPositions() ---
// 列出所有已存储的坐标键名。
// 返回:键名字符串数组
var posKeys = listPositions();
log("已存储的坐标点: " + JSON.stringify(posKeys));

滑动轨迹管理

interface SwipeTrack

滑动轨迹对象
📋 类型定义原文
interface SwipeTrack {
    x1: number;
    y1: number;
    x2: number;
    y2: number;
    duration: number;
}

func setSwipe

declare function setSwipe(keys: readonly K[], options: CaptureOptions): { [P in K]: SwipeTrack }; // v1.3.16 泛型键(F12 跳到这里=读的是新版声明) /** * 查询已存储的滑动轨迹 * @returns 滑动轨迹对象或 null */ declare function getSwipe(key: string): SwipeTrack | null
用户手动录入滑动轨迹
通过透明 Activity 监听用户滑动 + ThetaDB 缓存。
若所有 keys 已有缓存则直接返回,否则启动滑动录入界面。
必须使用对象解构赋值: var {up, down} = setSwipe(["up", "down"], {hint: "..."})
@param keys 键名数组,每个键对应一条滑动轨迹
@param options 采集选项,hint 必填
@returns {键名: {x1, y1, x2, y2, duration}}
@example
```js
var {s1} = setSwipe(["s1"], {hint: "请画出从下往上的滑动轨迹"});
var {up, down} = setSwipe(["up", "down"], {hint: "请分别画上滑和下滑"});
replay(up); // 重放滑动
```
📄 示例:173_setSwipe.js(点击展开)
// 通过透明 Activity 让用户在屏幕上画出滑动轨迹,自动记录起点/终点/持续时间并保存到数据库。
// 必须使用对象解构赋值: var {up, down} = setSwipe(["up", "down"], {hint: "..."})
//
// 参数:
//   keys (string[]) — 键名数组,每个键对应一条滑动轨迹
//   hint (string)   — 说明文本(必填),录入时显示在屏幕顶部
// 返回: {key1: {x1,y1,x2,y2,duration}, key2: {...}, ...}
//   - x1,y1: 滑动起点坐标
//   - x2,y2: 滑动终点坐标
//   - duration: 滑动持续时间(毫秒)
//   所有键都有缓存时直接返回,否则启动透明 Activity 录入
//   采集界面支持双击截图放大预览(详见 setPosition 说明)

// ============================================================
// flutter-auto API 示例 — 30. setSwipe — 滑动轨迹录入与重放(必须对象解构赋值)
// 30. setSwipe — 滑动轨迹录入与重放(必须对象解构赋值)
// ============================================================


// 示例1: 录入单条滑动
var {s1} = setSwipe(["s1"], {hint: "请画出从下往上的滑动轨迹"});
// s1 = {x1: 500, y1: 1500, x2: 500, y2: 500, duration: 320}
if (s1) {
    log("滑动轨迹: (" + s1.x1 + "," + s1.y1 + ") → (" + s1.x2 + "," + s1.y2 + ") " + s1.duration + "ms");
    replay(s1);  // 重放滑动
}

// 示例2: 录入多条滑动(每个 key 对应一条轨迹)
var {up, down} = setSwipe(["up", "down"], {hint: "请分别画上滑和下滑"});
// up = {x1, y1, x2, y2, duration}
// down = {x1, y1, x2, y2, duration}
if (up && down) {
    replay(up);     // 上滑
    sleep(1000);
    replay(down);   // 下滑
}

// 示例3: 已有缓存时直接返回
var {s1} = setSwipe(["s1"], {hint: "..."});  // 第二次调用直接返回缓存

// 示例4: 批量重放
var {left, right} = setSwipe(["left", "right"], {hint: "请画左滑和右滑"});
replay([left, right]);  // 返回 ["ok", "ok"]

// 示例5: 也可直接用 swipe() 重放
var {scroll} = setSwipe(["scroll"], {hint: "请画出滚动轨迹"});
if (scroll) {
    swipe([[scroll.x1, scroll.y1], [scroll.x2, scroll.y2]], {duration: scroll.duration});
}

// 相关 API:
//   getSwipe(key)      — 查询已存储的滑动,返回 {x1,y1,x2,y2,duration} 或 null
//   delSwipe(key)      — 删除已存储的滑动,返回 true
//   listSwipes()       — 列出所有滑动键名,返回 string[]
//   replay(objOrArray) — 重放滑动(含人类行为模拟),返回 "ok"/["ok",...]/false

func delSwipe

declare function delSwipe(key: string): true
删除滑动轨迹 (即使 key 不存在也返回 true)
@returns true

func listSwipes

declare function listSwipes(): string[]
列出所有滑动键名
@returns 键名数组

func replay

declare function replay( swipeObjOrArray: SwipeTrack | SwipeTrack[], options?: { /** 变换形态:"flick" 快起慢停(默认)| "ease" 缓入缓出 | "linear" 匀速(旧行为) */ easing?: "flick" | "ease" | "linear"; /** 中点垂直弧度 ±px(随机方向,默认 10;0=直线) */ curve?: number; /** 全程逐点横向漂移 ±px(默认 4;模拟手抖) */ drift?: number; /** 时长随机抖动 ±ms(默认 80;消除固定时长信号) */ durationJitter?: number; /** 起终点随机偏移 ±px(默认 3) */ jitter?: number; /** 覆盖录制时长(毫秒) */ duration?: number; } ): "ok" | "ok"[] | false
重放滑动轨迹(4.1.9 起反检测变换默认全开,模拟真人滑动形态)
默认变换:easing="flick" 快起慢停 + 中点弧度 ±10px + 横向漂移 ±4px
+ 时长抖动 ±80ms + 起终点偏移 ±3px;需旧行为时全部显式归零
@param swipeObjOrArray 滑动轨迹对象或数组
@param options 反检测变换参数
@returns 单条返回 "ok",数组返回 ["ok", ...],无效对象返回 false
@example
```js
replay(s1); // 默认反检测形态
replay(s1, {easing: "linear", curve: 0, drift: 0,
durationJitter: 0, jitter: 0}); // 旧行为(精确重放)
replay(s1, {duration: 800}); // 覆盖时长
```

摇杆管理

interface JoystickArea

摇杆区域对象
📋 类型定义原文
interface JoystickArea {
    cx: number;
    cy: number;
    radius: number;
}

func setJoystick

declare function setJoystick(keyOrKeys: K | readonly K[], options: CaptureOptions): { [P in K]: JoystickArea } | null
用户手动录入摇杆区域
通过透明 Activity 让用户以"圆心 + 半径手柄"的方式录入摇杆活动区域。
若该 key 已有缓存则直接返回,否则启动摇杆录入界面。
必须使用对象解构赋值: var {move} = setJoystick(["move"], {hint: "..."})
也兼容字符串写法: var {move} = setJoystick("move", {hint: "..."})
@param keyOrKeys 键名字符串或键名数组
@param options 采集选项,hint 必填
@returns {key: {cx, cy, radius}} 格式,支持解构赋值
@example
```js
var {move} = setJoystick(["moveJoystick"], {hint: "请点击移动摇杆的圆心位置"});
// move = {cx: 360, cy: 1080, radius: 120}
// 也兼容字符串写法:
// var {move} = setJoystick("moveJoystick", {hint: "请点击移动摇杆的圆心位置"});
```
📄 示例:174_setJoystick.js(点击展开)
// 通过透明 Activity 让用户以"圆心 + 半径手柄"的方式录入摇杆活动区域。
// 点击一次确定圆心位置,然后拖动圆心标记移动圆形、拖动半径手柄缩放圆形大小。
// 保存为 {cx, cy, radius} 到数据库。
// 必须使用对象解构赋值: var {move} = setJoystick(["move"], {hint: "..."})
// 也兼容字符串写法: var {move} = setJoystick("move", {hint: "..."})
//
// 参数:
//   keyOrKeys (string | string[]) — 键名字符串或键名数组
//   hint (string) — 说明文本(必填)
// 返回: {key: {cx, cy, radius}} 格式
//   - cx, cy: 圆心坐标
//   - radius: 半径(像素)
//   采集界面支持双击截图放大预览(详见 setPosition 说明)

// ============================================================
// flutter-auto API 示例 — 31. setJoystick — 摇杆区域录入(必须对象解构赋值)
// 31. setJoystick — 摇杆区域录入(必须对象解构赋值)
// ============================================================


// 示例1: 录入移动摇杆 (数组写法 — 推荐)
var {moveJoystick} = setJoystick(["moveJoystick"], {hint: "请点击移动摇杆的圆心位置"});
// moveJoystick = {cx: 360, cy: 1080, radius: 120}
if (moveJoystick) {
    log("摇杆区域: 圆心(" + moveJoystick.cx + "," + moveJoystick.cy + ") 半径" + moveJoystick.radius);
    // 8 方向控制
    joystick(moveJoystick, "up");       // 向上推
    sleep(500);
    joystick(moveJoystick, "down");     // 向下推
    sleep(500);
    joystick(moveJoystick, "center");   // 回中
}

// 示例2: 录入攻击摇杆 (字符串写法 — 兼容)
var {attackJoystick} = setJoystick("attackJoystick", {hint: "请点击攻击摇杆的圆心位置"});
if (attackJoystick) {
    log("攻击摇杆: 圆心(" + attackJoystick.cx + "," + attackJoystick.cy + ") 半径" + attackJoystick.radius);
}

// 相关 API:
//   getJoystick(key)    — 查询已存储的摇杆区域,返回 {cx, cy, radius} 或 null
//   delJoystick(key)    — 删除已存储的摇杆区域,返回 true
//   listJoysticks()     — 列出所有摇杆键名,返回 string[]
//   joystick(jsObj, dir) — 执行摇杆方向控制(dir: up/down/left/right/center 等)

func getJoystick

declare function getJoystick(key: string): JoystickArea | null
查询已存储的摇杆区域
@returns 摇杆区域对象或 null

func delJoystick

declare function delJoystick(key: string): true
删除摇杆区域 (即使 key 不存在也返回 true)
@returns true

func listJoysticks

declare function listJoysticks(): string[]
列出所有摇杆键名
@returns 键名数组

矩形区域管理 (setRect)

interface RectArea

矩形区域对象
字段类型说明
keystring 键名
xMinnumber 矩形左边界 x 坐标
xMaxnumber 矩形右边界 x 坐标
yMinnumber 矩形上边界 y 坐标
yMaxnumber 矩形下边界 y 坐标
tlPoint 左上角坐标
trPoint 右上角坐标
blPoint 左下角坐标
brPoint 右下角坐标
widthnumber 矩形宽度
heightnumber 矩形高度
📋 类型定义原文
interface RectArea {
}

func setRect

declare function setRect(key: string, options: { hint: string; keys?: string[] }): RectArea | null
用户手动录入矩形区域
通过透明 Activity 让用户依次点击矩形的 4 个角点,绘制矩形边框并缓存。
确认阶段支持拖动角点微调 + 方向键整体移动矩形(速度可调 1px/5px/10px/20px)。
若该 key 已有缓存则直接返回。
@param key 键名,用于标识此矩形区域(必填)
@param options 采集选项: hint 说明文本(必填,不能为空字符串);keys 可选,4 个角点的标签名
@returns 矩形对象或 null(用户点击删除时)
@throws 用户取消采集时抛出异常
@example
```js
var rect = setRect("btnArea", {hint: "请依次点击按钮区域的 4 个角"});
// rect = {xMin:100, xMax:500, yMin:200, yMax:800, tl:{x,y}, tr:{x,y}, bl:{x,y}, br:{x,y}, width:400, height:600}
```
📄 示例:144_setRect.js(点击展开)
// 通过透明 Activity 监听用户点击 4 个角点,绘制矩形边框并缓存到 ThetaDB。
// 下次调用时若数据库已有缓存则直接返回,无需再次手动点击。
// 返回的矩形对象可直接传给 region 参数或 .region() 方法。
//
// 工作流程:
//   1. 检查数据库中是否已有此键的矩形缓存
//   2. 有缓存 → 直接返回矩形对象
//   3. 无缓存 → 启动透明 Activity 监听用户点击 4 个角点(左上→右上→左下→右下)
//   4. 采集完成 → 绘制矩形边框 + 4 个角点标记,底部显示确认栏(保存/重来/删除)
//      确认栏支持:拖动角点微调 + 方向键整体移动矩形(速度可调 1px/5px/10px/20px)
//   5. 确认 → 保存到数据库并返回矩形对象
//   6. 重来 → 清除标记重新采集
//   7. 删除 → 删除已存储的矩形并返回 null

// ============================================================
// flutter-auto API 示例 — 23. setRect — 用户手动设置矩形区域(4 个角点)
// 23. setRect — 用户手动设置矩形区域(4 个角点)
// ============================================================
📄 示例:145_setRect.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 23. setRect — 用户手动设置矩形区域(4 个角点)
// setRect(key, {hint, keys?})
// ============================================================

// --- setRect(key, {hint, keys?}) ---
// 参数:
//   key (string)      — 键名,用于标识此矩形区域
//   options.hint      — 说明文本(必填),采集时显示在屏幕上
//   options.keys      — 可选,4 个角点的标签名,默认为 ["左上(tl)","右上(tr)","左下(bl)","右下(br)"]
// 返回:
//   {xMin, xMax, yMin, yMax, tl:{x,y}, tr:{x,y}, bl:{x,y}, br:{x,y}, width, height}
//   此返回值可直接传给 region 参数或 .region() 方法
//
// 拖动调整:
//   采集完 4 个点后进入确认阶段,可拖动任意角点微调位置。
//   也可使用方向键(↑↓←→)整体移动矩形,速度可在 1px/5px/10px/20px 间切换。
//   方向键支持长按连续移动(长按 300ms 后每 80ms 移动一步)。
//   y 轴自动水平对齐(以左和下为基准):
//     - 拖动左上(tl) → 右上(tr).y 自动跟随 tl.y
//     - 拖动右上(tr) → 仅 x 自由移动,y 始终 = tl.y
//     - 拖动左下(bl) → 右下(br).y 自动跟随 bl.y
//     - 拖动右下(br) → 仅 x 自由移动,y 始终 = bl.y
//   x 轴自动垂直对齐(以左上和右上为基准):
//     - 拖动左上(tl) → 左下(bl).x 自动跟随 tl.x
//     - 拖动右上(tr) → 右下(br).x 自动跟随 tr.x
//     - 拖动右下(br) → 反向更新 tr.x 和 bl.y
//   确认栏自动放在不遮挡角点的一侧(顶部或底部)。
//   点击"保存"时弹出编辑对话框,可手动输入 xMin/xMax/yMin/yMax 精确数值
//   (方便设置屏幕最边缘等拖动难以到达的坐标,如 x=0 或 x=屏幕宽度)。

// 示例 1: 设置一个矩形区域,用于限定查找范围
var rect = setRect("gameArea", {hint: "请依次点击游戏区域的左上、右上、左下、右下四个角"});
if (rect) {
    log("矩形区域: x[" + rect.xMin + "~" + rect.xMax + "] × y[" + rect.yMin + "~" + rect.yMax + "]");
    log("宽×高: " + rect.width + " × " + rect.height);
    // 将 rect 直接传给 region 参数,只在矩形区域内查找
    var btn = findOne("text=开始", {timeout: 3000, region: rect});
    if (btn) {
        click(btn);
        log("已点击开始按钮");
    }
}

// 示例 2: 使用 .region() 链式方法
var rect2 = setRect("toolbar", {hint: "请点击工具栏区域的 4 个角"});
if (rect2) {
    // 只在工具栏区域内查找所有可点击控件
    var buttons = findAll("clickable=true").region(rect2);
    log("工具栏内找到 " + buttons.length + " 个可点击控件");
    for (var i = 0; i < buttons.length; i++) {
        log("  按钮" + (i + 1) + ": " + buttons[i].text);
    }
}

// 示例 3: 自定义角点标签
var rect3 = setRect("dialog", {hint: "请点击对话框的 4 个角", keys: ["左上角", "右上角", "左下角", "右下角"]});
if (rect3) {
    // 在对话框区域内 OCR 查找文字
    var text = ocrFind("确定", {region: rect3});
    if (text) {
        click(text);
        log("已点击对话框内的确定按钮");
    }
}

// 示例 4: 将 rect 用于 aiTxt 查找
var rect4 = setRect("searchArea", {hint: "请点击搜索区域的 4 个角"});
if (rect4) {
    var result = aiTxt("搜索", {region: rect4});
    if (result) {
        log("找到搜索: " + JSON.stringify(result));
    }
}

// 示例 5: 第二次运行同一脚本时,直接使用缓存
// 第一次运行: 弹出透明 Activity,用户手动点击 4 个角
// 第二次运行: 直接从数据库返回矩形对象,无需手动操作
var rect5 = setRect("cachedArea", {hint: "请点击需要缓存的矩形区域 4 个角"});
if (rect5) {
    log("使用缓存的矩形区域: " + JSON.stringify(rect5));
}
📄 示例:149_setRect.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 24. setRect 实战示例
// 24. setRect 实战示例
// ============================================================


// 场景: 在游戏某个固定区域内自动点击出现的按钮
// 首次运行时用户手动指定矩形区域,后续自动执行

// 设置游戏区域(首次运行弹出采集界面,后续直接使用缓存)
var gameArea = setRect("gameBtnArea", {hint: "请点击游戏按钮区域的 4 个角"});
if (gameArea) {
    log("游戏按钮区域: " + gameArea.width + " × " + gameArea.height);

    // 在矩形区域内循环查找并点击按钮
    for (var i = 0; i < 20; i++) {
        // 只在 gameArea 范围内查找"领取"按钮
        var btn = aiTxt("领取", gameArea);
        if (btn) {
            click(btn);
            log("已点击领取按钮");
            sleep(2000);
        } else {
            log("未找到领取按钮,等待...");
            sleep(3000);
        }
    }
}

// 清理缓存(需要重新设置矩形时调用)
// delRect("gameBtnArea");

func getRect

declare function getRect(key: string): RectArea | null
查询已存储的矩形区域
@returns 矩形对象或 null
📄 示例:146_getRect.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 23. setRect — 用户手动设置矩形区域(4 个角点)
// getRect(key)
// ============================================================

// --- getRect(key) ---
// 查询已存储的矩形区域(不触发采集,仅查询缓存)。
// 参数:
//   key (string) — 存储键名
// 返回:
//   {xMin, xMax, yMin, yMax, tl, tr, bl, br, width, height} 或 null
var cachedRect = getRect("gameArea");
if (cachedRect) {
    log("缓存的矩形区域: x[" + cachedRect.xMin + "~" + cachedRect.xMax + "]");
} else {
    log("未找到缓存的矩形区域");
}

func delRect

declare function delRect(key: string): true
删除矩形区域 (即使 key 不存在也返回 true)
@returns true
📄 示例:147_delRect.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 23. setRect — 用户手动设置矩形区域(4 个角点)
// delRect(key)
// ============================================================

// --- delRect(key) ---
// 删除已存储的矩形区域。
// 参数:
//   key (string) — 存储键名
// 返回:true(即使 key 不存在)
// delRect("gameArea");  // 删除矩形区域缓存
// log("已删除矩形区域缓存");

func listRects

declare function listRects(): string[]
列出所有矩形键名
@returns 键名数组
📄 示例:148_listRects.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 23. setRect — 用户手动设置矩形区域(4 个角点)
// listRects()
// ============================================================

// --- listRects() ---
// 列出所有已存储的矩形键名。
// 返回:键名字符串数组
var rectKeys = listRects();
log("已存储的矩形区域: " + JSON.stringify(rectKeys));

动态区域 (setBox)

interface BoxConfig

setBox 区域配置(相对锚点文本的动态矩形)
字段类型说明
keystring 键名
textstring 锚点文本(支持匹配前缀: =, ~=, ^=, $=, re=)
wnumber 矩形宽度
hnumber 矩形高度
dxnumber 锚点文本中心到矩形左上角的 X 偏移
dynumber 锚点文本中心到矩形左上角的 Y 偏移
📋 类型定义原文
interface BoxConfig {
}

func setBox

declare function setBox(key: string, text: string, options?: { hint?: string; keys?: string[] }): BoxConfig | null
采集相对锚点文本的动态矩形区域
通过透明 Activity 让用户点击矩形区域的 4 个角点,并在矩形内查找锚点文本计算偏移。
存储相对锚点的尺寸/偏移(锚点在哪框就在哪),与 setRect 的固定坐标相反。
常与 aiTxt 配合: var box = setBox("taskBox", "去完成"); aiTxt("~=浏览", {box: box, non: "限时任务"})
@param key 键名(必填)
@param text 锚点文本,支持匹配前缀语法(必填)
@param options 可选: hint 说明文本;keys 4 个角点的标签名(默认 ["左上(tl)","右上(tr)","左下(bl)","右下(br)"])
@returns {key, text, w, h, dx, dy} 配置对象,或 null(用户选择删除时)
📄 示例:150_setBox.js(点击展开)
// setBox(key, text, options?) 与 setRect 一样通过点击 4 个角点定义矩形,
// 但存储的是相对于锚点文本的尺寸和偏移(运行时动态定位)。
//
// 工作流程:
//   1. 无缓存 → 启动透明 Activity 采集 4 个角点(同 setRect)
//   2. 在采集的矩形内查找锚点文本 → 计算偏移 dx/dy
//   3. 保存 {key, text, w, h, dx, dy} 到数据库
//   4. aiTxt 调用时: 查找锚点 → 画框 → 框内搜索目标文字
//
// 与 setRect 的区别:
//   setRect 存储固定坐标(静态,UI 变化后失效)
//   setBox 存储相对锚点的尺寸/偏移(动态,锚点在哪框就在哪)
//
// 参数:
//   key (string)      — 键名
//   text (string)     — 锚点文本(支持匹配前缀: =, ~=, ^=, $=, re=)
//   options (object?)  — 可选:
//     hint (string)    — 说明文本(采集时显示在屏幕上)
//     keys (string[])  — 4 个角点的标签名,默认 ["左上(tl)","右上(tr)","左下(bl)","右下(br)"]
//
// 返回:{key, text, w, h, dx, dy} 或 null(用户选择删除时)
// 已有缓存时直接返回,不重新采集

// ============================================================
// flutter-auto API 示例 — 25. setBox — 以屏幕文字为锚点动态创建矩形区域(4 点采集)
// 25. setBox — 以屏幕文字为锚点动态创建矩形区域(4 点采集)
// ============================================================


// 示例1: 基本用法 — 点击 4 个角点采集
// 首次调用会弹出透明 Activity,请点击任务卡片的 4 个角
var finishBox = setBox("finishBox", "去完成");
if (finishBox) {
    log("finishBox: anchor=" + finishBox.text +
        " w=" + finishBox.w + " h=" + finishBox.h +
        " dx=" + finishBox.dx + " dy=" + finishBox.dy);
    // 第二次调用直接返回缓存,不再采集
    var cached = setBox("finishBox", "去完成");
}

// 示例2: 自定义提示文本
var smallBox = setBox("smallBox", "~=确定", {
    hint: "请点击确定按钮所在区域的 4 个角"
});
// 系统会在采集的矩形内查找 "确定",自动计算 w/h/dx/dy

// 示例3: 与 aiTxt 配合 — 遍历锚点画框搜索(核心用法)
// 场景: 任务列表中有 N 个任务卡片,每个卡片有 "去完成" 按钮
//       要找到包含 "浏览" 文本的卡片,且排除 "限时任务" 卡片
// 首次调用时点击一个任务卡片的 4 个角(包含 "去完成" 按钮)
var taskBox = setBox("taskBox", "去完成");
if (taskBox) {
    // aiTxt 会遍历每个 "去完成" → 画框 → 框内找 "浏览" → 检查框内无 "限时任务"
    var browse = aiTxt("~=浏览", {box: taskBox, non: "限时任务"});
    if (browse) {
        log("找到浏览任务: " + browse.text + " @ " + browse.center);
        click(browse);
    } else {
        log("未找到包含浏览的非限时任务");
    }
}

// 示例4: box + non 数组 — 多个排除文本
var box2 = setBox("box2", "去完成");
if (box2) {
    // 框内不能有 "限时任务" 也不能有 "已完成"
    var result = aiTxt("~=浏览", {box: box2, non: ["限时任务", "已完成"]});
    if (result) {
        click(result);
    }
}

// 示例5: 多锚点自动遍历 — 无需手动循环
// 屏幕上有多个 "去完成" 按钮(多个任务卡片)
// aiTxt 自动遍历每个锚点画框,找到第一个匹配的
// 不需要手动循环,一次 aiTxt 调用即可
var multiBox = setBox("multiBox", "去完成");
if (multiBox) {
    var task = aiTxt("~=浏览", {box: multiBox, non: "限时任务"});
    if (task) {
        log("在某个任务卡片中找到浏览: " + task.text + " @ " + task.center);
        click(task);
    }
}

// 示例6: 滚动列表 — setBox 只需采集一次,aiTxt 每次动态查找
var scrollBox = setBox("scrollBox", "去完成");
if (scrollBox) {
    for (var si = 0; si < 5; si++) {
        // 每次调用 aiTxt 时重新查找 "去完成" 的位置(因为列表可能滚动)
        var task2 = aiTxt("~=浏览", {box: scrollBox, non: "限时任务"});
        if (task2) {
            log("找到浏览任务: " + task2.text);
            click(task2);
            sleep(3000);
        }
        // 向上滑动查看下一屏
        // swipe(500, 800, 500, 400, 500);
        sleep(1000);
    }
}

// 示例7: log 参数 — 查看 box 搜索过程
var debugBox = setBox("debugBox", "去完成");
if (debugBox) {
    var r = aiTxt("~=浏览", {box: debugBox, non: "限时任务", log: true});
    // 输出示例:
    //   [aiTxt:box] 锚点"去完成" UI 匹配 3 个
    //   [aiTxt:box] 目标文本共 2 个匹配
    //   [aiTxt:box] 锚点[0] @[540,800] box=[340,650~740,950]
    //   [aiTxt:box] 锚点[0] 框内存在排除文本,跳过
    //   [aiTxt:box] 锚点[1] @[540,1200] box=[340,1050~740,1350]
    //   [aiTxt:box] 锚点[1] 框内匹配: 浏览
}

// 示例8: box 配置管理 — getBox / delBox / listBoxes
var existing = getBox("finishBox");  // 查询已存储的配置
if (existing) {
    log("finishBox: w=" + existing.w + " h=" + existing.h +
        " dx=" + existing.dx + " dy=" + existing.dy +
        " anchorW=" + Math.round(existing.anchorW) + " anchorH=" + Math.round(existing.anchorH));
}
// delBox("finishBox");  // 删除配置,下次 setBox 会重新采集
// var allBoxes = listBoxes();  // 列出所有已存储的 box 键名

// 示例9: checkBox — 可视化验证 box 配置
// 在屏幕上弹出透明 Activity,画出每个匹配锚点的 box 框
// 可以直观看到哪些锚点被匹配、框的位置是否准确
// 建议在 setBox 采集后、aiTxt 使用前调用 checkBox 验证
var checkBoxResult = checkBox("finishBox");
log("checkBox: 匹配 " + checkBoxResult + " 个锚点");
// 屏幕上会画出:
//   - 绿色边框 + 半透明填充: box 区域
//   - 橙色圆点: 锚点文本位置
//   - 橙色连线: 锚点到框中心
//   - 黄色标签: key#序号 (锚点文本)
// 点击屏幕关闭

// 示例10: checkBox 带日志 — 查看匹配/过滤过程
checkBox("finishBox", {log: true});
// 输出示例:
//   [checkBox] 锚点"去完成" UI 匹配 5 个
//   [checkBox] 锚点[0] 文本尺寸不匹配,跳过
//   [checkBox] 匹配 4 个锚点
// (第1个锚点可能是页面上方的大号"去完成",尺寸不匹配被过滤)

// 示例11: checkBox 传入配置对象(无需 DB 缓存)
var tempBox = {key: "temp", text: "去完成", w: 400, h: 300, dx: 0, dy: 0, anchorW: 0, anchorH: 0};
// anchorW=0, anchorH=0 表示不校验文本尺寸,所有匹配都画框
checkBox(tempBox, {log: true});

func getBox

declare function getBox(key: string): BoxConfig | null
查询已存储的 box 配置
@param key 键名
@returns 配置对象或 null(不存在时)

func delBox

declare function delBox(key: string): true
删除已存储的 box 配置(即使 key 不存在也返回 true)
@returns true

func listBoxes

declare function listBoxes(): string[]
列出所有已存储的 box 键名
@returns 键名数组

func checkBox

declare function checkBox(keyOrBox: string | BoxConfig, options?: { log?: boolean; confidence?: number }): number
在透明 Activity 上画出 box 配置的框(可视化验证)
@param keyOrBox 键名(从数据库读取配置)或 setBox 返回的配置对象
@param options 可选: log 输出搜索过程日志;confidence 锚点 OCR 置信度过滤阈值
@returns 匹配的锚点数量(0 表示未找到锚点或配置无效)

文本配置管理 (setConf)

func setConf

declare function setConf(key: string, hint: string, defaultValue?: string): string
用户手动输入文本配置
通过透明 Activity + EditText 弹出输入框 + ThetaDB 缓存。
若该 key 已有缓存则直接返回,否则启动透明 Activity 显示输入对话框。
适用场景:
- 不同系统/ROM 的取消按钮文本不同("取消" / "Cancel" / "返回")
- 不同设备的设置项名称不同
- 用户自定义的脚本参数(如等待时长、循环次数的提示文本)
@param key 键名,用于标识此配置项(必填)
@param hint 说明文本,描述此配置的用途(必填,不能为空字符串)
@param defaultValue 可选,输入框默认值
@returns 用户输入的文本
@throws 用户点击"取消"时抛出异常
@example
```js
var cancelText = setConf("cancelText", "请输入系统取消按钮的文本");
var confirmText = setConf("confirmText", "请输入系统确定按钮的文本", "确定");
```

控件点选(setWidget,4.0.8+)

interface WidgetOptions

setWidget 采集选项
字段类型说明
tip?string 点选提示文案
hint?string tip 的别名(同等有效;兼容 setPosition 风格的 hint 写法)
timeout?number 点选超时毫秒(默认与上限 24 小时)
📋 类型定义原文
interface WidgetOptions {
}

interface WidgetPick

setWidget 点选结果:控件节点信息 + findOne 选择器建议
字段类型说明
confirmedtrue 采集确认标记(恒为 true)
keystring 键名
xnumber 横坐标
ynumber 纵坐标
center[number, number] 控件中心点 [cx, cy](可直接传给 click)
bounds[number, number, number, number] 控件边界 [x, y, w, h]
textstring 控件文本
descstring 控件 contentDescription
idstring 控件资源 id
classstring 控件类名
packagestring 所属应用包名
selectorstring 自动生成的 findOne 选择器("text=…"/"desc=…"/"id=…")
createdAtnumber 采集时间戳(毫秒)
📋 类型定义原文
interface WidgetPick {
    clickable: boolean;
    editable: boolean;
    enabled: boolean;
    selected: boolean;
}

func setWidget

declare function setWidget(keyOrKeys: string, options?: WidgetOptions | string): WidgetPick
declare function setWidget(keys: readonly K[], options?: WidgetOptions | string): { [P in K]: WidgetPick }
弹全屏点选层让用户点选一个控件,返回节点信息与 findOne 选择器建议
(setPosition 选坐标,setWidget 选控件;首次采集后缓存,之后不再弹层)
单键返回结果对象;取消/超时/未选中/界面无控件树(游戏自绘)时抛 Error,务必 catch 降级
多键批量返回 {键名: 结果} 映射;已缓存的键直接命中不弹窗(缓存命中不碰控件树,
无障碍关闭后可直接复用无障碍时代保存的位置)
点选结果会注册进配置检查(checkSettings 能感知 widget 是否已配置)
选点规则(4.8.10+):取「包含点击点且中心距点击点最近」的节点(旧版为最深节点,
在可见按钮与其他控件屏幕重叠时会选错);若该点有多个可选控件(可点击或有文本/描述)
重叠,弹出选择列表由用户自行抉择,首项标「★推荐」(离点击最近),点空白处返回重选
取消按钮避让(4.8.9+):首次点在"取消"按钮上(含 16dp 热区)不取消——按钮
自动挪到远离点击点的底角(提示条同步更新),再点原位置即可选取其下控件;
确需取消点按钮新位置
@param keyOrKeys 键名(或键名数组)
@param options {tip: 提示文案(hint 别名同效), timeout: 毫秒(默认与上限 24 小时)};也可直接传提示字符串
@example
```js
try {
var w = setWidget("targetBtn", { tip: "请点击目标控件" })
click(w) // 返回含 center,可直接点
log(w.selector) // "text=..."/"desc=..."/"id=..."
} catch (e) { log("控件点选被取消: " + e) }
var r = setWidget(["btnA", "btnB"], { tip: "请依次点选" }) // r.btnA / r.btnB
```

func delWidget

declare function delWidget(key: string): true
删除已存储的控件配置(下次 setWidget 重新点选)
@param key 键名
@returns true(即使 key 不存在)

func listWidgets

declare function listWidgets(): string[]
列出所有已存储的控件配置键名
@returns 键名数组

setChoose — 采集型选择(4.8.20+,setWidget 同款交互模型)

interface ChoosePick

setChoose 命中的候选对象(ocr 模式含 confidence/bbox,ui 模式含 bounds/id/desc 等)
字段类型说明
textstring 候选文本(如 "3.21元")
center?number[] 中心点 [cx, cy](ocr 模式必有;ui 模式由 bounds 推算,可直接传给 click 坐标用法)
bbox?number[][] OCR 文本框四角 [[x,y]×4](ocr 模式)
bounds?number[] 控件边界 [x, y, w, h](ui 模式)
confidence?number 识别置信度(ocr 模式)
📋 类型定义原文
interface ChoosePick {
    [k: string]: any;
}

interface ChooseRecord

setChoose 的记忆记录(getChoose 返回)
字段类型说明
matcherstring 选择条件(创建时的 matcher 原文)
mode'ocr' | 'ui' 候选采集方式:'ocr' | 'ui'
regionstring 屏幕区域(创建时的 region 原文,未传为空串)
textstring 用户选择/最近自动命中的文本(仅展示用,不参与自动匹配——数值随时会变)
cxnumber | null 最近命中项中心 x(自动匹配锚点,平分时比对)
cynumber | null 最近命中项中心 y(自动匹配主锚点:|Δy| ≤ 文字高度×1.5 内取最近)
hnumber | null 最近命中项文字高度(位置容差基准)
timenumber 最近命中时间戳(毫秒)
📋 类型定义原文
interface ChooseRecord {
}

interface SetChooseOptions

setChoose 参数
字段类型说明
key?string记忆键——记住选择必需(如 'baseMoney');后续运行同 key 自动命中
(不再弹窗),getChoose/delChoose 查删也用它。市场脚本自动按
script_id 前缀隔离,本地脚本全库共享键空间(建议带脚本名前缀)
mode?'ocr' | 'ui' 候选采集方式:'ocr'(默认,截图+识别)| 'ui'(控件树文本,需无障碍)
region?string 屏幕区域:top/bottom/left/right/rt/rb/lb/lt 或矩形,缺省全屏
hint?string 选择弹窗的提示文本(如 "选择当前的金钱基线"),默认 "请选择"
📋 类型定义原文
interface SetChooseOptions {
}

func setChoose

declare function setChoose(matcher: string, options?: SetChooseOptions): ChoosePick
采集型选择(setWidget 同款交互模型):按条件收集屏幕上的候选文本
(OCR 或控件),让用户从列表挑一个并记住;后续运行到同 key 不再弹窗,
按「客观物理位置」自动命中——记忆的是命中项的中心坐标与文字高度
(不记文本数值:数值随时会变,而位置即使变化也不会超过文字本身高度),
本屏候选中 |Δy| 在容差内取最近者(平分比 |Δx|),锚点随每次命中滑动
更新;位置全偏出容差(版式变化)→ 重新弹窗让用户校准。
候选为空时的行为:
- 有 key 且记忆已存在(自动阶段)→ 返回 null(脚本自行判断界面异常)
- 首次运行/无 key → 抛 Error(条件或界面不对,必须暴露)
@param matcher 选择条件,支持多种形态:
- "text$=元" 文本以「元」结尾($= 结尾 / ^= 开头 / *= 与 ~= 包含 / = 精确相等)
- "re=/\\d+(\\.\\d+)?元$/" 正则(re=/模式/标志)
- "id=xxx" / "desc=yyy" 字段可换(ui 模式有效)
- 裸字符串 等价 text=(精确相等)
@param options {key, mode, region, hint}
@returns 命中的候选对象(含 text/center,可直接用于坐标点击或 aiTxt 跟点)
@example
```js
// 首次运行:弹出候选列表让用户选金钱基线;之后按位置自动命中(数值变了不影响)
var base = setChoose("text$=元", { key: "baseMoney", region: "top", hint: "选择当前的金钱基线", mode: "ocr" });
if (!base) throw new Error("屏上没有金额文本");
log("基线: " + base.text + " @ " + base.center);
var rec = getChoose("baseMoney"); // 查记忆 {matcher, mode, region, text, cx, cy, h, time}
delChoose("baseMoney"); // 清除记忆(下次重新弹窗校准)
```
📄 示例:190_setChoose.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 40. setChoose 采集型选择(记住基准,4.8.20 新增)
// setChoose(matcher, options?) / getChoose(key) / delChoose(key)
// ============================================================

// --- setChoose(matcher, options?) ---
// 按条件收集屏幕上的候选文本(OCR 或控件),弹列表让用户挑一个并记住;
// 后续运行到同 key 不再弹窗——按「客观物理位置」自动命中:记忆的是命中项
// 的中心坐标与文字高度(不记文本数值——数值随时会变,而位置即使变化也不
// 会超过文字本身的高度),本屏候选中 |Δy| 在容差内取最近者(平分比 |Δx|),
// 锚点随每次命中滑动更新;位置全偏出容差(版式变化)→ 重新弹窗校准。
//
// 参数:
//   matcher (string,必填) 选择条件,支持多种形态:
//     "text$=元"   文本以「元」结尾($= 结尾 / ^= 开头 / *= 与 ~= 包含 / = 精确
//                  相等;字段可换 desc/id,ui 模式有效)
//     "re=/\\d+(\\.\\d+)?元$/"  正则(re=/模式/标志)
//     裸字符串     等价 text=(精确相等)
//   options:
//     key    (string,推荐) 记忆键(如 'baseMoney'),自动命中与
//            getChoose/delChoose 查删都用它;市场脚本自动按 script_id 隔离
//     mode   (string,可选) 候选采集方式:'ocr'(默认,截图识别)| 'ui'
//            (控件树文本,需无障碍)
//     region (string,可选) 屏幕区域:top/bottom/left/right/rt/rb/lb/lt 或
//            矩形,缺省全屏
//     hint   (string,可选) 选择弹窗的提示文本
//
// 返回: 命中的候选对象(ocr 模式 {text, confidence, bbox, center};ui 模式
//       控件节点 text/bounds/center/...);有 key 且记忆自动阶段本屏无候选
//       返回 null;用户取消/首次运行无候选抛 Error
//
// 记忆存储:ThetaDB 'choices' 命名空间(自动带设备后缀,跨脚本更新保留)。

// 示例1: 你的场景——首次运行弹候选列表选「金钱基线」,之后按位置自动命中
var base = setChoose("text$=元", {
    key: "baseMoney",                     // 记忆键:后续自动命中/查删都用它
    region: "top",                        // 只在屏幕上部找
    hint: "选择当前的金钱基线",            // 弹窗提示文本
    mode: "ocr",                          // 候选来自 OCR(默认,可省略)
});
if (!base) {
    log("本屏没有以「元」结尾的文本");
} else {
    log("基线: " + base.text + " @ " + base.center);
    // 金额数值变了(3.21元 → 3.50元)也不影响:该行的屏幕位置不变,
    // 按记忆的 y 位置(容差=文字高度×1.5)自动命中,文本只是展示
    // 需要点击时: click({ x: base.center[0], y: base.center[1] })
}

// 示例2: 正则条件——金额文本更复杂时用 re
var pick2 = setChoose("re=/\\d+(\\.\\d+)?元$/", {
    key: "baseMoneyRe",
    region: "top",
    hint: "选择金额",
});

// 示例3: 控件模式(mode: 'ui')——候选来自控件树文本(需无障碍开启)
var pick3 = setChoose("text$=金币", {
    key: "coinEntry",
    mode: "ui",
    hint: "选择金币入口",
});
if (pick3) {
    log("入口: " + pick3.text + " bounds=" + JSON.stringify(pick3.bounds));
    // click(pick3.center[0], pick3.center[1]) 之类按坐标点击
}

// 示例4: 无 key = 纯交互不记忆(每次运行都弹,仅 1 个候选时自动选中)
var once = setChoose("text$=元", { region: "top", hint: "选个金额(不记)" });
log("本次选中: " + (once ? once.text : "无"));

// 示例5: getChoose(key) — 查询记忆(不采集不弹窗)
var rec = getChoose("baseMoney");
if (rec) {
    // 记忆字段:{matcher, mode, region, text, cx, cy, h, time}
    // 自动匹配只认 cx/cy/h(物理位置),text 仅展示
    log("记忆: 文本=" + rec.text + " y=" + rec.cy + " 字高=" + rec.h);
}

// 示例6: delChoose(key) — 清除记忆(选错基准后的纠正入口)
// 清除后下次运行到该选择点重新弹窗校准
if (rec && rec.text === "选错了的那条") {
    delChoose("baseMoney");
    log("已清除基线记忆,下次运行重新弹窗");
}

func getChoose

declare function getChoose(key: string): ChooseRecord | null
查询某选择点的记忆记录
@param key 记忆键(与 setChoose 传入的一致)
@returns 记忆对象(matcher/mode/region/text/time),无记忆返回 null

func delChoose

declare function delChoose(key: string): true
清除某选择点的记忆(下次运行到该选择点重新弹窗让用户校准基准)
@param key 记忆键
@returns true(即使 key 不存在)

弹窗规则执行(rulesDialog,4.1.7+)

func rulesDialog

declare function rulesDialog(targetPkg: string, options?: { verify?: boolean; reload?: boolean }): boolean
用户弹窗规则执行:按目标包名过滤「检查配置页-弹窗规则」中启用的规则,
逐条 aiTxt(match, {region}) 匹配,命中即点击规则坐标,可选 OCR 复查弹窗消失。
弹窗自愈一行写法:if (rulesDialog(appkg)) { sleep(500); }
规则列表缓存 30 秒(弹窗循环高频调用不反复查库);单条规则损坏自动跳过不炸任务
@param targetPkg 目标应用包名(规则按此过滤;规则未填包名时对所有包生效)
@param options verify: 点击后 OCR 复查弹窗消失,默认 true(未消失自动试下一条规则);
reload: 强制重载规则列表(默认缓存 30 秒)
@returns true=命中并已处理 / false=无命中

func getConf

declare function getConf(key: string): string | null
查询已存储的文本配置
@param key 键名
@returns 文本值,或 null(不存在时)

func delConf

declare function delConf(key: string): true
删除已存储的文本配置
@param key 键名
@returns true(即使 key 不存在)

func listConfs

declare function listConfs(): string[]
列出所有已存储的文本配置键名
@returns 键名数组

interface ConfirmDialogOptions

showConfirmDialog 的选项
字段类型说明
title?string 对话框标题(默认"确认")
message?string 正文内容
okText?string 确认按钮文本(默认"确定")
cancelText?string 取消按钮文本(默认"取消")
📋 类型定义原文
interface ConfirmDialogOptions {
}

func showConfirmDialog

declare function showConfirmDialog(options?: ConfirmDialogOptions): boolean
阻塞式确认对话框(确定/取消,双端支持)
@param options 标题/正文/按钮文本
@returns true=用户点确定;false=用户点取消
@example
```js
if (showConfirmDialog({ title: "开始", message: "确认开始执行?", okText: "开始" })) {
// 用户确认
}
```

func setActivity

declare function setActivity(key: string, hint: string): string
通过悬浮窗获取并确认当前 Activity 名
用于不同系统/ROM 的安装 Activity 差异(如 MIUI vs Flyme vs 原生)。
弹出悬浮窗(WindowManager overlay),用户可:
1. 点击"获取"按钮读取当前前台 Activity 名
2. 切换到其他界面再点"获取"获取不同的 Activity
3. 点击"确定"保存并返回
4. 点击"取消"放弃
不能使用透明 Activity(会改变前台 Activity),只能用悬浮窗。
@param key 键名,已有缓存则直接返回
@param hint 说明文本
@returns Activity 全限定名(格式: 包名/Activity名)
@throws 用户取消时抛出异常
@example
```js
var installAct = setActivity("miuiInstallAct", "请切换到安装界面后点击获取");
console.log(installAct); // "com.miui.packageinstaller/.ui.InstallConfirmActivity"
```
📄 示例:175_setActivity.js(点击展开)
// 弹出悬浮窗(WindowManager overlay),用户可:
//   1. 点击"获取当前 Activity"按钮读取当前前台 Activity 名
//   2. 切换到其他界面再点"获取"获取不同的 Activity
//   3. 点击"确定"保存并返回
//   4. 点击"取消"放弃
//
// 不能使用透明 Activity(会改变前台 Activity),只能用悬浮窗。
// 数据库缓存:首次调用弹窗,后续直接返回缓存值。

// ============================================================
// flutter-auto API 示例 — 32. setActivity — 悬浮窗获取 Activity 名(用于不同系统/ROM 适配)
// 32. setActivity — 悬浮窗获取 Activity 名(用于不同系统/ROM 适配)
// ============================================================


// 示例1: 获取 MIUI 安装界面的 Activity 名
var miuiInstallAct = setActivity("miuiInstallAct", "请切换到 MIUI 安装界面后点击获取");
log("MIUI 安装 Activity: " + miuiInstallAct);
// 返回值示例: "com.miui.packageinstaller/.ui.InstallConfirmActivity"

// 示例2: 获取 Flyme 安装界面的 Activity 名
var flymeInstallAct = setActivity("flymeInstallAct", "请切换到 Flyme 安装界面后点击获取");
log("Flyme 安装 Activity: " + flymeInstallAct);
// 返回值示例: "com.flyme.systemui/.activity.InstallActivity"

// 示例3: 第二次调用直接返回缓存(不弹窗)
var cachedAct = setActivity("miuiInstallAct", "请切换到 MIUI 安装界面后点击获取");
log("缓存: " + cachedAct);  // 直接返回之前保存的值

// 相关 API:
//   getConf(key)    — 查询已存储的配置(setActivity 也存储在 confs 中)
//   delConf(key)    — 删除已存储的配置,返回 true
//   listConfs()     — 列出所有配置键名,返回 string[]

取色管理 (setColor)

interface ColorResult

setColor 取色结果
字段类型说明
xnumber 取色点 X 坐标(屏幕像素)
ynumber 取色点 Y 坐标(屏幕像素)
colornumber Android Color int(带 alpha 通道,可用于 drawing)
hexstring 十六进制颜色字符串(大写,不含 alpha,如 "#FF1122")
rgb{ r: number; g: number; b: number } RGB 分量 {r, g, b},0~255
shape?"circle" | "rect" | "cross" | "check" 形状类型(通过 options.shape 指定后保存)
subColor?string 副色(如红点内的白色数字,通过 options.subColor 指定后保存)
position?"lt" | "rt" | "lb" | "rb" 红点相对于文本的位置(通过 options.position 指定后保存)
📋 类型定义原文
interface ColorResult {
}

interface SetColorOptions

setColor 取色选项
字段类型说明
hintstring 说明文本,描述此取色的用途(必填,不能为空字符串)
shape?"circle" | "rect" | "cross" | "check"形状类型,指定后 checkColor 找色时会按形状特征过滤匹配区域:
- "circle": 过滤填充率≈0.785 且宽高比≈1.0 的连通域(如红点)
- "rect": 过滤填充率≈1.0 的连通域(如按钮)
- "cross": 过滤填充率<0.35 的连通域(× 关闭按钮)
- "check": 过滤填充率<0.35 的连通域(√ 勾选标记)
subColor?string 副色(如红点内的白色数字),格式 "#FFFFFF" 或颜色 int;checkColor 找到主色区域后会检查区域内是否包含副色像素
position?"lt" | "rt" | "lb" | "rb" 红点相对于 OCR 文本的位置:"lt" 左上 / "rt" 右上 / "lb" 左下 / "rb" 右下;checkColor 返回结果时会根据此位置搜索最近文本
📋 类型定义原文
interface SetColorOptions {
}

func setColor

declare function setColor(key: string, options: SetColorOptions): ColorResult
declare function setColor(keys: readonly K[], options: SetColorOptions): { [P in K]: ColorResult }
用户手动在屏幕上取色
通过透明 Activity 监听用户点击 + 方向键微调 + 放大镜 + 速度调节 + ThetaDB 缓存。
若该 key 已有缓存则直接返回,否则启动取色界面。
工作流程:
1. 检查数据库中是否已存储此键的取色结果
2. 有缓存 → 直接返回
3. 无缓存 → 启动透明 Activity:
a. 用户点击屏幕任意位置 → 在该点取色
b. 显示放大镜(圆形)+ 十字准星 + 当前颜色值
c. 显示四方向键(上下左右)→ 微调取色点位置
d. 显示速度选择器(1px/5px/10px/20px)→ 控制方向键每次移动的像素数
e. 显示"确定"/"重来"按钮
f. 用户点击"确定" → 保存到数据库并返回
g. 用户点击"重来" → 清除当前点重新取色
单键返回 ColorResult,多键返回 {key: ColorResult} 支持解构赋值:
var c = setColor("btnColor", {hint: "..."}) → c.hex
var {c1, c2} = setColor(["c1", "c2"], {hint: "..."}) → c1.hex
@param key 键名字符串,返回单个 ColorResult
@param keys 键名数组,返回 {key: ColorResult} 格式
@param options 取色选项,hint 必填
@throws 用户取消取色时抛出异常
@example
```js
var {btnColor} = setColor(["btnColor"], {hint: "请点击按钮的颜色区域"});
console.log(btnColor.hex); // "#FF1122"
console.log(btnColor.rgb); // {r:255, g:17, b:34}
console.log(btnColor.color); // -15204014 (Android Color int)
console.log(btnColor.x, btnColor.y); // 取色点坐标
// 带形状 + 位置配置(供 checkColor 自动过滤):
setColor(["badge"], {hint: "请点击红点颜色", shape: "circle", position: "rt"});
// 单键直接返回结果对象:
// var c = setColor("btnColor", {hint: "..."});
```
📄 示例:176_setColor.js(点击展开)
// 通过透明 Activity 让用户在屏幕上取色。
// 用户点击屏幕任意位置取色,可用方向键微调取色点(1px/次),
// 显示放大镜+十字准星+当前颜色值。
// 单键直接返回颜色对象: var c = setColor("btnColor", {hint: "..."})
// 单键也兼容解构写法: var {btnColor} = setColor(["btnColor"], {hint: "..."})
// 多键返回 {key: colorObj}: var {c1, c2} = setColor(["c1", "c2"], {hint: "..."})
//
// 参数:
//   keyOrKeys (string | string[]) — 键名字符串或键名数组(必填)
//   hint (string) — 说明文本(必填)
//   shape (string, 可选) — 形状类型: "circle"/"rect"/"cross"/"check"
//     "circle": 过滤填充率≈0.785 且宽高比≈1.0 的连通域(如红点)
//     "rect": 过滤填充率≈1.0 的连通域(如按钮)
//     "cross": 过滤填充率<0.35 的连通域(× 关闭按钮)
//     "check": 过滤填充率<0.35 的连通域(√ 勾选标记)
//   subColor (string, 可选) — 副色(如红点内的白色数字)
//     格式: "#FFFFFF" 或颜色 int
//     checkColor 找到主色区域后,会检查区域内是否包含副色像素
//   position (string, 可选) — 红点相对于文本的位置
//     "lt"/"rt"/"lb"/"rb"(红点在文字的左上/右上/左下/右下角)
//     checkColor 返回结果时会根据此位置搜索最近 OCR 文本
//   采集界面支持双击截图放大预览(详见 setPosition 说明)
// 返回: {key: {x, y, color, hex, rgb, shape?, subColor?, position?}}
//   - x, y: 取色点的屏幕坐标(px)
//   - color: Android Color int(可用于 drawing)
//   - hex: 十六进制颜色字符串(如 "#FF1122",大写,不含 alpha)
//   - rgb: {r, g, b} 0~255
//   - shape: 用户指定的形状类型(如指定了 options.shape)

// ============================================================
// flutter-auto API 示例 — 33. setColor — 取色
// 33. setColor — 取色
// ============================================================


// 示例1: 取按钮颜色 (字符串写法 — 单键直接返回颜色对象)
var btnColor = setColor("btnColor", {hint: "请点击按钮的颜色区域"});
// btnColor = {x: 540, y: 1200, color: -15204014, hex: "#FF1122", rgb: {r:255, g:17, b:34}}
if (btnColor) {
log("取色结果: " + btnColor.hex + " RGB(" + btnColor.rgb.r + "," + btnColor.rgb.g + "," + btnColor.rgb.b + ") @ (" + btnColor.x + "," + btnColor.y + ")");
// 后续可用于 findColor / findMultiColors
var found = findColor(btnColor.color, {tolerance: 10});
    if (found) {
        log("找到颜色位置: (" + found.x + "," + found.y + ")");
        click(found);
    }
}

// 示例2: 取多个颜色点 (数组写法 — 推荐)
var {bgColor} = setColor(["bgColor"], {hint: "请点击背景颜色区域"});
var {textColor} = setColor(["textColor"], {hint: "请点击文字颜色区域"});
if (bgColor && textColor) {
    log("背景色: " + bgColor.hex + ", 文字色: " + textColor.hex);
    // 多点找色
    var offsets = [[0, 0, bgColor.color], [10, 0, textColor.color]];
    var match = findMultiColors({color: bgColor.color, offsets: offsets}, {tolerance: 10});
    if (match) {
        log("多点找色命中: (" + match.x + "," + match.y + ")");
    }
}

// 示例3: 数组写法也兼容 (单键返回颜色对象)
var btnColor2 = setColor(["btnColor2"], {hint: "请点击按钮颜色"});

// 示例4: 已有缓存时直接返回
var btnColor3 = setColor("btnColor", {hint: "..."});  // 第二次调用直接返回缓存

// 示例5: 取红点颜色并指定圆形形状
// 指定 shape: "circle" 后,checkColor 会自动使用形状过滤
var {redDot} = setColor(["redDot"], {hint: "请点击红点颜色", shape: "circle"});
// redDot = {x: 540, y: 600, color: -65536, hex: "#FF0000", rgb: {r:255, g:0, b:0}, shape: "circle"}

// 示例6: 取按钮颜色并指定矩形形状
var {btnBg} = setColor(["btnBg"], {hint: "请点击按钮背景色", shape: "rect"});
// btnBg = {x: 540, y: 1200, color: -1, hex: "#FFFFFF", rgb: {r:255, g:255, b:255}, shape: "rect"}

// 示例7: 取×关闭按钮颜色
var {closeBtn} = setColor(["closeBtn"], {hint: "请点击×关闭按钮颜色", shape: "cross"});

// 示例8: 取√勾选标记颜色
var {checkMark} = setColor(["checkMark"], {hint: "请点击√勾选标记颜色", shape: "check"});

// 示例9: 红点 + 副色 + 位置(完整配置)
// 红点内含白色数字,红点出现在文字的右上角
var {badge} = setColor(["badge"], {
    hint: "请点击红点颜色",
    shape: "circle",
    subColor: "#FFFFFF",        // 副色: 白色(红点内的数字)
    position: "rt"            // 红点在文本的右上角
});
// badge = {x: 800, y: 200, color: -65536, hex: "#FF0000", rgb: {r:255, g:0, b:0},
//          shape: "circle", subColor: "#FFFFFF", position: "rt"}

// 相关 API:
//   getColor(key)    — 查询已存储的取色结果,返回 {x, y, color, hex, rgb, shape?, subColor?, position?} 或 null
//   delColor(key)    — 删除已存储的取色结果,返回 true
//   listColors()     — 列出所有取色键名,返回 string[]


// ============================================================
// 32b. showRect / showPosition / showColor / showSwipe / showJoystick
//      — 可视化展示已保存的数据,方便核对
// ============================================================
// 在透明 Activity 上绘制已保存的 rect/position/color/swipe/joystick 数据,
// 点击屏幕任意位置关闭覆盖层。
//
// showRect(key?)      — 显示矩形区域(绿色边框 + 半透明填充 + 角点标记 + 标签)
// showPosition(key?)  — 显示坐标点(橙色圆圈 + 中心点 + 标签)
// showColor(key?)     — 显示取色点(十字标记 + 色块预览 + hex 标签)
// showSwipe(key?)     — 显示滑动轨迹(绿起点→红终点 + 箭头 + duration 标签)
// showJoystick(key?)  — 显示摇杆区域(紫色圆 + 8方向指示线 + 中心点)
//
// 参数:
//   key (string?) — 指定要显示的键名。省略则显示该类型的所有已保存数据。
//
// 返回: true(找到并显示)或 false(未找到任何数据)
//
// 示例:

// showRect — 核对矩形区域
showRect();              // 显示所有已保存的矩形区域
// showRect("gameArea"); // 只显示指定的矩形

// showPosition — 核对坐标点(圆圈范围)
showPosition();          // 显示所有已保存的坐标点
// showPosition("p1");   // 只显示指定的坐标点

// showColor — 核对取色点
showColor();             // 显示所有已保存的取色点
// showColor("btnColor"); // 只显示指定的取色点

// showSwipe — 核对滑动轨迹
showSwipe();             // 显示所有已保存的滑动轨迹
// showSwipe("up");       // 只显示指定的滑动轨迹

// showJoystick — 核对摇杆区域
showJoystick();          // 显示所有已保存的摇杆区域
// showJoystick("move");  // 只显示指定的摇杆区域

interface NearbyTextInfo

checkColor 附近文本信息(指定 position 后自动附带)
字段类型说明
textstring 匹配到的文本
xnumber 文本中心 X 坐标
ynumber 文本中心 Y 坐标
confidencenumber | null OCR 置信度 0~1(不可用时为 null)
distancenumber 红点质心到文本预期角点的距离(px,四舍五入)
📋 类型定义原文
interface NearbyTextInfo {
}

interface ColorRegion

checkColor 单个匹配区域
字段类型说明
xnumber 区域左上角 X 坐标
ynumber 区域左上角 Y 坐标
wnumber 区域宽度
hnumber 区域高度
areanumber 连通域面积(px²)
fillRationumber 填充率 0~1(circle≈0.785、rect≈1.0、cross/check<0.35)
aspectRationumber 宽高比
hasSubColor?boolean 是否包含副色像素(配置了 subColor 验证时附带)
nearbyText?NearbyTextInfo | null 距离最近的 OCR 文本(配置了 position 时附带,无匹配文本时为 null)
📋 类型定义原文
interface ColorRegion {
}

interface MultiColorRef

checkColor 多点颜色验证对象
字段类型说明
colorstring | number 主色: "#FF0000" 字符串 / 颜色 int / setColor 键名
offsetsArray<[number, number, string | number] | Array<number | string>> 偏移验证点 [dx, dy, 颜色],颜色支持 "#RRGGBB" / int / setColor 键名
(JS 数组字面量推断宽松,兼容 number[][] / 混合嵌套数组写法)
📋 类型定义原文
interface MultiColorRef {
}

interface CheckColorOptions

checkColor 选项
字段类型说明
tolerance?number HSV 颜色容忍度 0~255,默认 0
region?RegionExpr 搜索区域限制(RegionExpr)
title?string 预览窗口标题,默认 "检查颜色"
minArea?number 最小连通域面积过滤,默认 5
shape?"circle" | "rect" | "cross" | "check" 形状过滤(也可通过 setColor 配置自动获取)
shapeTolerance?number 形状匹配容忍度 0~1,默认 0.15
subColor?string 副色验证 "#FFFFFF"(也可通过 setColor 配置自动获取)
subTolerance?number 副色匹配容忍度 0~255,默认 30
position?"lt" | "rt" | "lb" | "rb" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight" 红点相对文本位置 "lt"/"rt"/"lb"/"rb",指定后每个区域附带 nearbyText(兼容旧值 "topLeft"/"topRight"/"bottomLeft"/"bottomRight")
textVerifyFactor?number 文本勾股验证系数,传入后启用勾股验证;越大容忍度越高,不传则仅按方位过滤
show?boolean 是否弹窗显示标注截图,默认 false
nearestText?boolean 是否搜索最近文本,默认 true(position 存在时自动开启)
📋 类型定义原文
interface CheckColorOptions {
}

interface CheckColorResult

checkColor 匹配结果
字段类型说明
matchedboolean 是否有匹配
countnumber 匹配区域数量
regionsColorRegion[] 匹配区域列表
screenshot?string 标注后的截图路径(平台支持预览时附带)
📋 类型定义原文
interface CheckColorResult {
}

func checkColor

declare function checkColor(color: string | number | MultiColorRef, options?: CheckColorOptions): CheckColorResult
检查颜色匹配结果并预览到图片上
在屏幕截图中查找匹配颜色区域,高亮标注后可弹窗预览。
color 支持四种形式: "#FF5722" / 颜色 int / setColor 键名(自动读取颜色/形状/副色/位置配置)/ 多点对象。
@param color 目标颜色: "#FF5722" 字符串 / 颜色 int / setColor 键名 / 多点对象 {color, offsets}
@param options 可选配置
@returns 匹配结果 {matched, count, regions, screenshot?}
@example
```js
var r = checkColor("badge", { tolerance: 30, minArea: 120 });
if (r.count > 0) {
r.regions.forEach(function (rg) {
console.log(rg.x, rg.y, rg.nearbyText && rg.nearbyText.text);
});
}
```
📄 示例:165_checkColor.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 21. 低功耗优化 API — 截图缓存、快速找色、事件驱动等待
// checkColor(color, options?) — 检查颜色匹配结果并预览到图片上
// ============================================================

// --- checkColor(color, options?) — 检查颜色匹配结果并预览到图片上 ---
// 在屏幕截图中查找匹配颜色区域,高亮标注后弹窗预览给用户查看
// 适用于调试颜色设置:查看设置的颜色是否有偏差、哪些地方符合预期
//
// 参数:
//   color (string|number|object) — 目标颜色
//     字符串颜色: "#FF5722"  数字: 0xFF5722
//     字符串键名: "btnColor" (从 setColor 保存的配置读取颜色/形状/副色/位置)
//     多点对象: {color: "#FF0000", offsets: [[10,0,"#00FF00"],[0,20,"#0000FF"]]}
//   options (object, 可选):
//     tolerance: HSV 颜色容忍度 0~255,默认 0
//     region: 搜索区域限制(RegionExpr)
//     title: 预览窗口标题,默认 "检查颜色"
//     minArea: 最小连通域面积过滤,默认 5
//     shape: 形状过滤 "circle"|"rect"|"cross"|"check" (也可通过 setColor 配置自动获取)
//     shapeTolerance: 形状匹配容忍度 0~1,默认 0.15
//     subColor: 副色验证 "#FFFFFF" (也可通过 setColor 配置自动获取)
//       找到主色区域后,检查区域内是否包含副色像素
//     subTolerance: 副色匹配容忍度 0~255,默认 30
//     position: 红点相对于文本的位置 "lt"/"rt"/"lb"/"rb"(红点在文字的左上/右上/左下/右下角)
//       指定后,返回结果中每个区域会附带 nearbyText 字段(距离最近的 OCR 文本)
//     show: boolean, 是否弹窗显示标注截图,默认 false
//     nearestText: boolean, 是否搜索最近文本,默认 true(当 position 存在时自动开启)
// 返回: {matched: bool, count: int, regions: [{x,y,w,h,area,fillRatio,aspectRatio,hasSubColor?,nearbyText?},...], screenshot?}
//   matched: 是否有匹配
//   count: 匹配区域数量
//   regions: 匹配区域列表(按面积降序),含形状特征数据
//   screenshot: 标注后的截图路径(已高亮匹配区域)

// 示例1: 单色精确匹配(tolerance=0)
var r1 = checkColor("#FF5722");
log("检查结果: " + (r1.matched ? "匹配 " + r1.count + " 个区域" : "无匹配"));
if (r1.screenshot) log("标注截图: " + r1.screenshot);

// 示例2: 带容差匹配(HSV 色彩空间,对光照变化更鲁棒)
var r2 = checkColor("#4CAF50", {tolerance: 30, title: "检查绿色按钮"});
log("绿色按钮检查: " + (r2.matched ? "匹配 " + r2.count + " 个区域" : "无匹配"));
for (var i = 0; i < r2.regions.length; i++) {
    log("  [" + i + "] 质心(" + r2.regions[i].x + "," + r2.regions[i].y + ") " +
        r2.regions[i].w + "x" + r2.regions[i].h + " 面积=" + r2.regions[i].area);
}

// 示例3: 限制搜索区域(只在左上角搜索)
var r3 = checkColor("#FF0000", {tolerance: 20, region: "lt", minArea: 10});
// 等价于:
var r3b = checkColor("#FF0000", {tolerance: 20, minArea: 10}).region ? null : null; // 链式不支持 checkColor

// 示例4: 多点颜色检查(锚点+偏移验证)
var r4 = checkColor(
    {color: "#FF0000", offsets: [[10, 0, "#00FF00"], [0, 20, "#0000FF"]]},
    {tolerance: 20, title: "多点颜色检查"}
);
log("多点检查: " + (r4.matched ? "匹配 " + r4.count + " 个位置" : "无匹配"));

// 示例5: 调试 setColor 设置的颜色是否有偏差
// 先用 setColor 设置了一个颜色,现在想看看屏幕上还有哪些地方颜色类似
var btnColor = setColor("btnColor", {hint: "请点击按钮颜色"});
// 用 setColor 设置的颜色来检查屏幕上所有匹配区域
var check = checkColor(btnColor.hex, {tolerance: 15, title: "检查按钮颜色分布"});
if (check.matched) {
    log("找到 " + check.count + " 个类似颜色区域");
    if (check.count > 3) {
        log("警告: 颜色匹配区域过多,可能需要减小 tolerance 或更换取色位置");
    }
}

// 示例6: 使用形状过滤(圆形 — 适用于红点检测)
// setColor 时指定 shape: "circle",checkColor 会自动读取形状配置
var {redDot} = setColor(["redDot"], {hint: "请点击红点颜色", shape: "circle"});
// checkColor 传入键名 "redDot",自动读取颜色和形状配置
var dotCheck = checkColor("redDot", {tolerance: 20, title: "检查红点"});
log("红点检查: " + (dotCheck.matched ? "匹配 " + dotCheck.count + " 个" : "无匹配"));
if (dotCheck.matched) {
    for (var i = 0; i < dotCheck.regions.length; i++) {
        var r = dotCheck.regions[i];
        log("  [" + i + "] 质心(" + r.x + "," + r.y + ") " + r.w + "x" + r.h +
            " 面积=" + r.area + " 填充率=" + r.fillRatio + " 宽高比=" + r.aspectRatio);
    }
}

// 示例7: 手动指定形状过滤(不依赖 setColor 配置)
var rectCheck = checkColor("#4CAF50", {
    tolerance: 25,
    shape: "rect",           // 只匹配矩形形状
    shapeTolerance: 0.1,     // 形状匹配容忍度
    title: "检查矩形按钮"
});
log("矩形按钮检查: " + (rectCheck.matched ? "匹配 " + rectCheck.count + " 个" : "无匹配"));

// 示例8: 使用 show 参数弹窗显示标注截图
var showResult = checkColor("#FF5722", {
    tolerance: 20,
    show: true,              // 弹窗显示标注截图
    title: "查看颜色匹配结果"
});
if (showResult.screenshot) {
    log("标注截图已保存: " + showResult.screenshot);
}

// 示例9: × 形状过滤(关闭按钮检测)
var closeBtn = setColor(["closeBtn"], {hint: "请点击×关闭按钮颜色", shape: "cross"});
var closeCheck = checkColor("closeBtn", {tolerance: 30, show: true});
log("关闭按钮检查: " + (closeCheck.matched ? "匹配 " + closeCheck.count + " 个" : "无匹配"));

// 示例10: √ 形状过滤(勾选标记检测)
var checkMark = setColor(["checkMark"], {hint: "请点击√勾选标记颜色", shape: "check"});
var markCheck = checkColor("checkMark", {tolerance: 30});
log("勾选标记检查: " + (markCheck.matched ? "匹配 " + markCheck.count + " 个" : "无匹配"));

// 示例11: 红点 + 副色 + 位置 + 最近文本(完整功能)
// 红点内含白色数字,红点出现在文字的右上角
var {badge} = setColor(["badge"], {
    hint: "请点击红点颜色",
    shape: "circle",
    subColor: "#FFFFFF",        // 副色: 白色(红点内的数字)
    position: "rt"            // 红点在文本的右上角
});
// checkColor 传入键名,自动读取所有配置
var badgeResult = checkColor("badge", {
    tolerance: 25,
    show: true                  // 弹窗查看结果
});
if (badgeResult.matched) {
    for (var i = 0; i < badgeResult.regions.length; i++) {
        var r = badgeResult.regions[i];
        log("  [" + i + "] 质心(" + r.x + "," + r.y + ") " + r.w + "x" + r.h +
            " 面积=" + r.area +
            " 填充率=" + r.fillRatio +
            " 宽高比=" + r.aspectRatio +
            " 副色=" + (r.hasSubColor ? "有" : "无"));
        if (r.nearbyText) {
            log("    最近文本: \"" + r.nearbyText.text + "\" @ (" + r.nearbyText.x + "," + r.nearbyText.y + ")" +
                " 距离=" + r.nearbyText.distance + "px");
        }
    }
}

// 示例12: 手动指定副色和位置(不依赖 setColor 配置)
var manualCheck = checkColor("#FF0000", {
    tolerance: 20,
    shape: "circle",
    subColor: "#FFFFFF",        // 检查红点内是否有白色
    subTolerance: 40,
    position: "rb",           // 红点在文本右下角
    nearestText: true
});
if (manualCheck.matched) {
    var withText = manualCheck.regions.filter(function(r) { return r.nearbyText; });
    log("有最近文本的红点: " + withText.length + " 个");
}

func getColor

declare function getColor(key: string): ColorResult | null
查询已存储的取色结果
@param key 键名
@returns 取色结果对象,或 null(不存在时)

func delColor

declare function delColor(key: string): true
删除已存储的取色结果
@param key 键名
@returns true(即使 key 不存在)

func listColors

declare function listColors(): string[]
列出所有已存储的取色键名
@returns 键名数组

时间日期比较

interface CompTimeResult

compTime 返回值 — 时间差对象
字段类型说明
greaterboolean target 是否大于 reference
yearsnumber 年差值
monthsnumber 月差值
daysnumber 天差值
hoursnumber 小时差值
minutesnumber 分钟差值
secondsnumber 秒差值
textstring 人类可读的差值文本(如 "大于1年2月3天"),不大于时为空字符串
📋 类型定义原文
interface CompTimeResult {
}

func compTime

declare function compTime(reference: string | number, target: string | number): CompTimeResult
时间日期比较 — 判断 target 时间是否大于 reference 时间
@param reference 基准时间,支持特殊关键字或时间值:
- "today" — 今天 00:00:00
- "hour" — 当前小时起点 (HH:00:00)
- "minute" — 当前分钟起点 (HH:MM:00)
- "month" — 本月 1 号 00:00:00
- "year" — 本年 1 月 1 号 00:00:00
- 也可直接传入 ISO8601 字符串 / 时间戳 / DATETIME 字符串
@param target 要比较的目标时间,支持:
- ISO8601 字符串: "2026-07-14T10:00:00"
- 时间戳 (毫秒或秒): 1720944000000
- DATETIME 字符串: "2026-07-14 10:00:00"
@returns 时间差对象;target <= reference 或解析失败时 greater 为 false,所有单位为 0
@example
```js
var r = compTime("today", getKey("signup"));
if (r.greater) {
console.log("已过去: " + r.text); // "大于1年2月3天"
console.log("年:", r.years, "月:", r.months, "天:", r.days);
}
```

app 命名空间

namespace app

app.launch()

app.launch(packageName: string): boolean
启动应用 (与 launchPackage 互为别名)
@param packageName 包名
@returns 是否成功

app.launchPackage()

app.launchPackage(packageName: string): boolean
启动应用 (launch 的别名)

app.getPackageName()

app.getPackageName(appName: string): string | null
通过应用名获取包名
@returns 包名或 null

app.getAppName()

app.getAppName(packageName: string): string | null
通过包名获取应用名
@returns 应用名或 null

app.getPackageInfo()

app.getPackageInfo(packageName: string): PackageInfo
获取应用详细信息

app.getInstalledPackages()

app.getInstalledPackages(): InstalledPackage[]
获取已安装应用列表

app.openAppSetting()

app.openAppSetting(packageName: string): boolean
打开应用系统设置页
@returns 是否成功

app.viewFile()

app.viewFile(path: string): boolean
查看文件 @returns 是否成功

app.editFile()

app.editFile(path: string): boolean
编辑文件 @returns 是否成功

app.uninstall()

app.uninstall(packageName: string): boolean
卸载应用 @returns 是否成功

app.openUrl()

app.openUrl(url: string): boolean
打开 URL (自动添加 http:// 前缀如果未带协议)
@returns 是否成功

app.sendEmail()

app.sendEmail(options: SendEmailOptions): boolean
发送邮件
@returns 是否成功

app.startActivity()

app.startActivity(name: string): boolean
启动特定界面
@param name 组件名 "pkg/cls"(如 "com.tencent.mm/.ui.LauncherUI");
特殊值 'console' 拉起本应用到前台(Android)
@returns 是否成功(不支持的平台/模式返回 false)

app.currentActivity()

app.currentActivity(): string
获取当前前台 Activity 类名 (全局函数别名)

app.currentPackage()

app.currentPackage(): string
获取当前前台包名 (全局函数别名)

app.currentComponent()

app.currentComponent(): string
获取当前前台组件名 (全局函数别名)

app.windows()

app.windows(): WindowInfo[]
获取所有应用窗口列表(过滤系统 UI 窗口:状态栏/导航栏/输入法等)
不支持的平台/模式(如 Windows ADB)抛 Error

app.bindWindow()

app.bindWindow(windowId: string): WindowInfo | null
绑定当前线程到指定窗口:后续 aiTxt/click/dumpUi 等操作自动适配窗口
(region 基于窗口 bounds 裁剪)
@param windowId 窗口 id,从 app.windows() 获取
@returns 窗口上下文;窗口不存在时返回 null(恢复全屏模式)

app.unbindWindow()

app.unbindWindow(): void
解除窗口绑定,恢复全屏模式

app.currentWindow()

app.currentWindow(): WindowInfo | null
获取当前绑定的窗口上下文(未绑定时返回 null)

app.pauseWindow()

app.pauseWindow(threadId: number): boolean
暂停指定窗口绑定的子线程(设置 pause_flag,线程在 sleep/events.wait
时进入低频轮询等待)。需在 threads.start 后调用,按 thread_id 操作
@returns 是否成功

app.resumeWindow()

app.resumeWindow(threadId: number): boolean
恢复被暂停的子线程 @returns 是否成功

app.stopWindow()

app.stopWindow(threadId: number): boolean
停止指定窗口绑定的子线程 @returns 是否成功

device 命名空间

namespace device

device.getSerial()

device.getSerial(): string
设备序列号

device.getAndroidId()

device.getAndroidId(): string
Android ID

device.getIMEI()

device.getIMEI(): string
IMEI

device.getMacAddress()

device.getMacAddress(): string
MAC 地址 (需 WLAN 连接)

device.keepScreenOn()

device.keepScreenOn(timeout?: number): boolean
保持屏幕常亮(全亮度)
使用 WakeLock 实现系统级屏幕唤醒,即使 App 在后台或屏幕已熄灭也能保持常亮。
适用于定时任务执行前唤醒屏幕。
@param timeout 超时毫秒,0 或省略 = 一直保持
@returns 是否成功

device.keepScreenDim()

device.keepScreenDim(timeout?: number): boolean
保持屏幕常亮(允许变暗以省电)
适用于定时任务唤醒屏幕操作,不需要用户观看屏幕的场景。
@param timeout 超时毫秒,0 或省略 = 一直保持

device.cancelKeepingAwake()

device.cancelKeepingAwake(): boolean
取消屏幕常亮(释放 WakeLock)

device.wakeUp()

device.wakeUp(): boolean
唤醒设备 CPU 和屏幕
使用 ACQUIRE_CAUSES_WAKEUP + FULL_WAKE_LOCK 唤醒屏幕。
适用于定时任务执行前唤醒屏幕,避免锁屏导致任务无法执行。

device.wakeUpIfNeeded()

device.wakeUpIfNeeded(): boolean
如果屏幕未点亮则唤醒

device.isScreenOn()

device.isScreenOn(): boolean
屏幕是否亮着

device.isScreenLocked()

device.isScreenLocked(): boolean
屏幕是否处于锁屏状态

device.unlockScreen()

device.unlockScreen(): boolean
亮屏解锁(弹出钥匙串,适用于无滑动密码的锁屏)

device.slideUnlock()

device.slideUnlock(): boolean
滑动解锁(适用于 unlockScreen 无效的滑动锁屏)

device.getBrightness()

device.getBrightness(): number
获取屏幕亮度 (0-255),失败返回 -1

device.setBrightness()

device.setBrightness(b: number): boolean
设置屏幕亮度 (0-255)
需要修改系统设置权限

device.getBrightnessMode()

device.getBrightnessMode(): number
获取亮度模式 (0=手动, 1=自动)

device.setBrightnessMode()

device.setBrightnessMode(mode: number): boolean
设置亮度模式 (0=手动, 1=自动)

device.canWriteSettings()

device.canWriteSettings(): boolean
检查是否拥有 WRITE_SETTINGS 权限
亮度设置等系统设置修改需要此权限,Android 6+ 需用户手动授予

device.getMusicVolume()

device.getMusicVolume(): number
获取媒体音量

device.setMusicVolume()

device.setMusicVolume(volume: number): boolean
设置媒体音量

device.getNotificationVolume()

device.getNotificationVolume(): number
获取通知音量

device.setNotificationVolume()

device.setNotificationVolume(volume: number): boolean
设置通知音量

device.getAlarmVolume()

device.getAlarmVolume(): number
获取闹钟音量

device.setAlarmVolume()

device.setAlarmVolume(volume: number): boolean
设置闹钟音量

device.getMusicMaxVolume()

device.getMusicMaxVolume(): number
获取媒体最大音量

device.getNotificationMaxVolume()

device.getNotificationMaxVolume(): number
获取通知最大音量

device.getAlarmMaxVolume()

device.getAlarmMaxVolume(): number
获取闹钟最大音量

device.vibrate()

device.vibrate(millis?: number): boolean
震动
@param millis 震动毫秒,默认 500

device.cancelVibration()

device.cancelVibration(): boolean
取消震动

device.getBattery()

device.getBattery(): number
电池电量 0~100,失败返回 -1

device.isCharging()

device.isCharging(): boolean
是否充电

device.getTotalMem()

device.getTotalMem(): number
总内存 (字节)

device.getAvailMem()

device.getAvailMem(): number
可用内存 (字节)

device.getOrientation()

device.getOrientation(): number
屏幕方向 (1=竖屏, 2=横屏)

device.isPortrait()

device.isPortrait(): boolean
是否竖屏

device.isLandscape()

device.isLandscape(): boolean
是否横屏
常量类型说明
widthnumber 屏幕宽度 (只读)
heightnumber 屏幕高度 (只读)
brandstring 设备品牌 (如 "samsung", "Xiaomi")
modelstring 设备型号 (如 "SM-G950F")
productstring 产品名
buildIdstring 构建 ID
codenamestring 开发代号
fingerprintstring 设备指纹 (唯一标识)
sdkIntnumber Android SDK 版本号 (如 33, 34)
batterynumber 电池电量 0~100 (同 getBattery)

ui 命名空间

namespace ui

ui.showForm()

ui.showForm(schema: FormSchema): { [key: string]: any } | null
显示配置表单 (阻塞等待用户填写并提交)
@param schema 表单 Schema
@returns 用户填写结果,取消时返回 null

threads 命名空间

namespace threads

threads.start()

threads.start(func: Function): Thread
启动新线程
将函数序列化为代码字符串提交到 Worker Pool 执行。
注意: 仅序列化函数体,外部变量不传递。
@param func 无参函数
@returns Thread 对象

threads.shutDownAll()

threads.shutDownAll(): void
停止所有子线程 (不等待实际退出)

threads.currentThread()

threads.currentThread(): Thread
获取当前线程对象 (主线程 ID 为 0,方法为空操作)

threads.atomic()

threads.atomic(initialValue?: number): Atomic
创建原子整数对象 (线程安全)
@param initialValue 初始值,默认 0

threads.lock()

threads.lock(): Lock
创建可重入锁对象

threads.disposable()

threads.disposable(): Disposable
创建一次性结果传递对象
常量类型说明
sharedSharedVars跨线程内存级共享变量(基于 Rust 全局 HashMap + Mutex)
替代 db 做高频跨线程通信,无 IO 刷盘,比 db 快 100 倍以上。
解决 Share-Nothing 线程模型下闭包丢失、threads.atomic 不跨线程的问题。
@example
// 主线程设置标志
threads.shared.set("startInstalled", false);
// 子线程轮询
threads.start(function () {
while (!threads.shared.get("startInstalled")) sleep(300);
log("收到通知");
});
// 触发条件
threads.shared.set("startInstalled", true);

db 命名空间 (ThetaDB)

interface DbApi

ThetaDB 数据库接口 (delete 为 JS 保留字,用接口声明)
📋 类型定义原文
interface DbApi {
    set(key: string, value: any): true;
    get(key: string): any;
    delete(key: string): true;
    list(prefix?: string): string[];
    listAll(): { [key: string]: any };
    stats(): DbStats;
}

keys 常量对象 (Android KeyEvent 键码)

namespace keys

常量类型说明
KEYCODE_MENUnumber
KEYCODE_SOFT_RIGHTnumber
KEYCODE_HOMEnumber
KEYCODE_BACKnumber
KEYCODE_CALLnumber
KEYCODE_ENDCALLnumber
KEYCODE_0number
KEYCODE_1number
KEYCODE_2number
KEYCODE_3number
KEYCODE_4number
KEYCODE_5number
KEYCODE_6number
KEYCODE_7number
KEYCODE_8number
KEYCODE_9number
KEYCODE_STARnumber
KEYCODE_POUNDnumber
KEYCODE_DPAD_UPnumber
KEYCODE_DPAD_DOWNnumber
KEYCODE_DPAD_LEFTnumber
KEYCODE_DPAD_RIGHTnumber
KEYCODE_DPAD_CENTERnumber
KEYCODE_VOLUME_UPnumber
KEYCODE_VOLUME_DOWNnumber
KEYCODE_POWERnumber
KEYCODE_CAMERAnumber
KEYCODE_CLEARnumber
KEYCODE_Anumber
KEYCODE_Bnumber
KEYCODE_Cnumber
KEYCODE_Dnumber
KEYCODE_Enumber
KEYCODE_Fnumber
KEYCODE_Gnumber
KEYCODE_Hnumber
KEYCODE_Inumber
KEYCODE_Jnumber
KEYCODE_Knumber
KEYCODE_Lnumber
KEYCODE_Mnumber
KEYCODE_Nnumber
KEYCODE_Onumber
KEYCODE_Pnumber
KEYCODE_Qnumber
KEYCODE_Rnumber
KEYCODE_Snumber
KEYCODE_Tnumber
KEYCODE_Unumber
KEYCODE_Vnumber
KEYCODE_Wnumber
KEYCODE_Xnumber
KEYCODE_Ynumber
KEYCODE_Znumber
KEYCODE_COMMAnumber
KEYCODE_PERIODnumber
KEYCODE_ALT_LEFTnumber
KEYCODE_ALT_RIGHTnumber
KEYCODE_SHIFT_LEFTnumber
KEYCODE_SHIFT_RIGHTnumber
KEYCODE_TABnumber
KEYCODE_SPACEnumber
KEYCODE_SYMnumber
KEYCODE_EXPLORERnumber
KEYCODE_ENVELOPEnumber
KEYCODE_ENTERnumber
KEYCODE_DELnumber
KEYCODE_GRAVEnumber
KEYCODE_MINUSnumber
KEYCODE_EQUALSnumber
KEYCODE_LEFT_BRACKETnumber
KEYCODE_RIGHT_BRACKETnumber
KEYCODE_BACKSLASHnumber
KEYCODE_SEMICOLONnumber
KEYCODE_APOSTROPHEnumber
KEYCODE_SLASHnumber
KEYCODE_ATnumber
KEYCODE_NUMnumber
KEYCODE_HEADSETHOOKnumber
KEYCODE_FOCUSnumber
KEYCODE_PLUSnumber
KEYCODE_NOTIFICATIONnumber
KEYCODE_SEARCHnumber

base64 命名空间 — Base64 编码/解码

namespace base64

Base64 编码/解码模块
底层使用 Rust base64 crate 的 STANDARD engine 实现。
@example
```js
base64.encode("hello") // → "aGVsbG8="
base64.decode("aGVsbG8=") // → "hello"
base64.encodeBytes([104,101,108,108,111]) // → "aGVsbG8="
base64.decodeToBytes("aGVsbG8=") // → [104,101,108,108,111]
```

base64.encode()

base64.encode(str: string): string
将字符串编码为 base64
@param str 要编码的字符串
@returns base64 编码字符串

base64.decode()

base64.decode(b64: string): string
将 base64 字符串解码为原始字符串
@param b64 base64 编码字符串
@returns 解码后的原始字符串

base64.encodeBytes()

base64.encodeBytes(bytes: number[]): string
将字节数组编码为 base64
@param bytes 字节数组 (0~255 的整数数组)
@returns base64 编码字符串

base64.decodeToBytes()

base64.decodeToBytes(b64: string): number[]
将 base64 字符串解码为字节数组
@param b64 base64 编码字符串
@returns 字节数组 (0~255 的整数数组)

http 命名空间 — HTTP 客户端

interface HttpRequestOptions

HTTP 请求选项
字段类型说明
method?HttpMethod 请求方法,默认 "GET"
headers?HttpHeaders 请求头
contentType?string Content-Type
body?string 请求体 (字符串)
timeout?number 超时毫秒,默认 30000
maxRetries?number 最大重试次数,默认 3,最大 10
files?{ [name: string]: string | [string, string] | [string, string, string] } postMultipart 专用: 文件映射 { 字段名: 值 }
📋 类型定义原文
interface HttpRequestOptions {
}

interface HttpResponseBody

HTTP 响应体
字段类型说明
contentTypestring Content-Type
📋 类型定义原文
interface HttpResponseBody {
    string(): string;
    bytes(): number[];
    json(): any;
    close(): void;
}

interface HttpResponse

HTTP 响应
字段类型说明
statusCodenumber HTTP 状态码 (如 200, 404),失败时为 0
statusMessagestring 状态消息 (如 "OK", "Not Found")
methodstring 请求方法
urlstring 请求 URL
headersHttpHeaders 响应头
bodyHttpResponseBody 响应体
📋 类型定义原文
interface HttpResponse {
}

interface HttpRequestBuilder

HTTP 请求构造器返回的配置对象 (不执行请求)
📋 类型定义原文
interface HttpRequestBuilder {
    url: string;
    method: HttpMethod;
    headers: HttpHeaders;
    body?: string;
    contentType?: string;
}

namespace http

HTTP 客户端模块
参考 AutoJs6 http 模块: https://docs.autojs6.com/#/http
底层使用 Rust reqwest crate 实现,支持 GET/POST/PUT/DELETE/HEAD/PATCH/OPTIONS。
所有方法均同步阻塞 (默认超时 30 秒,最大重试 3 次),传入 callback 时为异步模式。
@example
```js
// GET 请求
var res = http.get("https://www.example.com");
console.log(res.statusCode); // 200
console.log(res.body.string()); // 网页 HTML
// POST JSON
var res = http.postJson("https://api.example.com", {a:1, b:2});
var data = res.body.json();
// 带请求头
var res = http.get("https://www.example.com", {
headers: {'User-Agent': 'test'},
timeout: 10000
});
```

http.get()

http.get(url: string, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback): HttpResponse | undefined
发起 GET 请求
@param url 请求 URL (会自动添加 http:// 前缀)
@param options 请求选项
@param callback 回调函数 (传入则为异步模式,返回 undefined)
@returns 同步模式返回 HttpResponse,异步模式返回 undefined

http.head()

http.head(url: string, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback): HttpResponse | undefined
发起 HEAD 请求 (只获取响应头)

http.post()

http.post( url: string, data?: any | HttpCallback, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback ): HttpResponse | undefined
发起 POST 请求
@param data 请求体: 对象自动转为 form-urlencoded,字符串原样发送

http.postJson()

http.postJson( url: string, data?: any | HttpCallback, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback ): HttpResponse | undefined
发起 POST JSON 请求 (自动设置 Content-Type: application/json)
@param data 对象会自动 JSON.stringify

http.postMultipart()

http.postMultipart( url: string, files?: { [name: string]: string | [string, string] | [string, string, string] } | HttpCallback, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback ): HttpResponse | undefined
发起 POST Multipart 请求 (上传文件)
@param files 文件映射: { 字段名: 值 }
- 字符串: 普通字段值
- [fileName, filePath]: 文件
- [fileName, mimeType, filePath]: 带类型的文件

http.put()

http.put( url: string, data?: any | HttpCallback, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback ): HttpResponse | undefined
发起 PUT 请求

http.del()

http.del( url: string, data?: any | HttpCallback, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback ): HttpResponse | undefined
发起 DELETE 请求
注意:delete 是 JS 保留字,TS 无法直接声明。
运行时 http.delete() 仍可用(JS 中作为属性访问合法),
但 TS 类型检查中请使用 http.del() 别名。

http.request()

http.request(url: string, options?: HttpRequestOptions | HttpCallback, callback?: HttpCallback): HttpResponse | undefined
通用请求方法
@param options 必须指定 method

http.buildRequest()

http.buildRequest(url: string, options?: HttpRequestOptions): HttpRequestBuilder
构建请求配置对象 (不实际发起请求)

qrcode 命名空间 — 二维码识别

interface QrcodeResult

二维码识别结果
字段类型说明
textstring 识别出的文本
pointsnumber[][] 二维码定位点数组 [[x, y], ...]
📋 类型定义原文
interface QrcodeResult {
}

namespace qrcode

二维码识别模块
底层使用 Rust rqrr crate 实现,支持从图片文件或 base64 数据中识别二维码。
@example
```js
// 从文件识别
var result = qrcode.decode("/sdcard/qrcode.png");
if (result) {
console.log(result.text); // 二维码内容
console.log(result.points); // 定位点坐标
}
// 从 base64 识别
var result = qrcode.decodeBase64("iVBORw0KGgo...");
```

qrcode.decode()

qrcode.decode(imagePath: string): QrcodeResult | null
从图片文件识别二维码
支持的图片格式: PNG, JPEG, BMP, GIF, WebP 等 (由 image crate 支持)。
支持的路径前缀: /sdcard/, /storage/emulated/0/ 等。
@param imagePath 图片路径
@returns 识别结果,未识别到二维码时返回 null

qrcode.decodeBase64()

qrcode.decodeBase64(base64Str: string): QrcodeResult | null
从 base64 编码的图片识别二维码
自动去除 data:image/...;base64, 前缀。
@param base64Str 图片的 base64 字符串 (可包含或不含 data:image 前缀)
@returns 识别结果,未识别到二维码时返回 null

engine 命名空间 — 脚本引擎管理

interface EngineScriptResult

engine.script() 单任务返回值
字段类型说明
okboolean 是否成功加入执行计划
namestring 脚本名称
engine_namestring 引擎名(单任务=name,多任务=name#1, name#2, ...)
delay?number 延迟毫秒数 (0 表示立即执行)
triggerAt?number 触发时间戳(定时任务)
taskId?string 任务 ID(定时任务,用于取消)
isCron?boolean 是否 cron 周期任务
cronExpr?string cron 表达式
error?string 错误信息 (ok=false 时存在)
📋 类型定义原文
interface EngineScriptResult {
}

interface EngineStopResult

engine.stop() 返回值
字段类型说明
okboolean 是否成功停止
error?string 错误信息 (ok=false 时存在)
📋 类型定义原文
interface EngineStopResult {
}

interface EngineStopAllResult

engine.stopAll() 返回值
字段类型说明
okboolean 是否成功
countnumber 停止的脚本数量
skipped?number 跳过的不可停止脚本数量 (unStoppable=true)
📋 类型定义原文
interface EngineStopAllResult {
}

namespace engine

脚本引擎管理模块
用于在 JS 层管理多个脚本的启动、停止。支持多任务定时和调用参数传递。
脚本来源:
- 本地文件: 如 "test.js" (会读取文件内容,支持 /sdcard/ 等路径)
- 远程 URL: 如 "http://example.com/test.js" (通过 http.get 获取)
启动时间 time 参数:
- 省略/null: 立即启动
- 数字: 视为时间戳 (>1e12 为毫秒,否则视为秒)
- 字符串: ISO8601 ("2026-07-15T10:00:00") / DATETIME ("2026-07-15 10:00:00") / cron ("0 8 * * *")
- 数组: 多任务定时,每个元素对应一个触发时间
调用参数 para:
- 通过 __scriptArgs 全局变量传递给脚本
- 单任务: 任意类型 (string/number/object 等)
- 多任务: 数组,每个元素对应该任务的参数(长度不足用 undefined 填充)
引擎名:
- 单任务: engine_name = name
- 多任务: engine_name = name#1, name#2, ... (用于 stop/list 标识)
定时触发行为:
定时脚本触发时会先停止所有运行中的脚本 (stopAll),再启动定时脚本,
确保定时任务在干净的环境中运行。
@example
```js
// 立即运行本地脚本
engine.script("test.js");
// 定时运行 (字符串)
engine.script("test.js", "2026-07-15 10:00:00");
// 定时运行 + 调用参数
engine.script("test.js", "2026-07-15 10:00:00", "mypara");
// 立即运行 + 调用参数
engine.script("test.js", null, "mypara");
// 多任务定时 + 参数(3 个时间点,前 2 个带参数,第 3 个参数为 undefined)
engine.script("mtxj.js",
["2026-08-04 07:33:00", "2026-08-04 08:33:00", "2026-08-04 09:33:00"],
["para1", "para2"]
);
// 定时运行 (时间戳,1 小时后)
engine.script("test.js", Date.now() + 3600000);
// cron 周期任务 (每天 8:00)
engine.script("test.js", "0 8 * * *");
// cron 周期任务 (每 10 分钟,分钟位 0,10,20,30,40,50)
engine.script("poll.js", "0,10,20,30,40,50 * * * *");
// 不可停止的守护脚本(定时任务触发时不会被 stopAll 停止)
engine.script("guard.js", null, null, true); // 立即运行 + 不可停止
engine.script("guard.js", "0 8 * * *", null, true); // cron + 不可停止
// 运行远程脚本(3.6.1+ 强制 https,明文 http 拒绝)
engine.script("https://example.com/test.js");
// 脚本内获取参数
var args = __scriptArgs; // 单任务: para 值; 多任务: 当前任务的 para
if (args !== undefined) {
console.log('收到参数:', args);
}
// 停止指定脚本
engine.stop("test.js");
// 停止多任务中的第 1 个
engine.stop("test.js#1");
// 停止所有脚本
engine.stopAll();
```

engine.setStuckTimeout()

engine.setStuckTimeout(sec: number): boolean
设置 JS 无响应死线(Layer1 卡死检测,3.6.0+)
@param sec 无响应秒数(默认 120,0 = 关闭 Layer1)
@returns 是否设置成功

engine.watchScreen()

engine.watchScreen(opt?: { interval?: number; samples?: number; hamming?: number }): boolean
开启屏幕停滞检测(Layer2,3.6.0+)。
周期采样屏幕指纹,连续 samples 次汉明距离低于阈值判定停滞。
注意:Windows ADB 模式下屏幕指纹采样不可用,Layer2 实际不生效。
@param opt { interval?: number(秒,默认30), samples?: number(默认5), hamming?: number(百分比,默认2) }
@returns 是否开启成功

engine.clearStuckWatch()

engine.clearStuckWatch(): boolean
关闭屏幕停滞检测(Layer2)
@returns 是否关闭成功

engine.onStuck()

engine.onStuck(fn: (info: { type: string; stuckSeconds: number; hash: string }) => boolean | void): boolean
注册停滞回调。
回调收到 info = { type: string, stuckSeconds: number, hash: string }:
返回 true 表示已处理并重置检测;返回 false 或不返回则终止脚本。
未注册回调时仅记录 WARN 日志,不停止脚本。

engine.script()

engine.script(name: string, time?: ScriptTime | ScriptTime[], para?: any | any[], unStoppable?: boolean): EngineScriptResult | EngineScriptResult[]
engine.script(name: string, options?: { time?: ScriptTime | ScriptTime[]; para?: any; unStoppable?: boolean }): EngineScriptResult | EngineScriptResult[]
engine.script options 写法: engine.script("test.js", {time: Date.now() + 3600000, para: {...}})

engine.stop()

engine.stop(engineName: string): EngineStopResult
停止指定引擎名的脚本
@param engineName 引擎名 (单任务=name,多任务=name#1, name#2, ...)
@returns 停止结果

engine.list()

engine.list(): { ok: boolean; count: number; scripts: Array<{ name: string; engine_name: string; startedAt: number; status: string }> }
列出所有正在运行的脚本
@returns 脚本列表

engine.stopAll()

engine.stopAll(): EngineStopAllResult
停止所有正在运行的脚本
@returns 停止结果 (含停止数量)

模块系统 — require() 加载 JS 模块

interface NodeModule

NodeJS 风格的 Module 对象
📋 类型定义原文
interface NodeModule {
    exports: any;
    id: string;
    filename: string;
    loaded: boolean;
    children: NodeModule[];
    paths: string[];
}

func require

declare function require(path: string): any
加载 JS 模块(支持本地文件和 http(s) URL)。
支持 CommonJS 语法 (module.exports / exports) 和 ES Module 语法 (export / import)。
ES Module 语法会被自动转换为 CommonJS 格式执行。
模块会被缓存,多次 require 同一路径只执行一次。
路径查找优先级:
1. URL(http:// / https://)→ 网络获取
2. 绝对路径(以 / 开头)→ 直接读取
3. 相对路径 → 先从 __scriptDir(应用脚本目录)查找,未找到则按原始路径读取
@param path 模块路径
- 本地路径: '/sdcard/lib/utils.js' 或 './utils.js'(相对当前脚本目录)
- 脚本名: 'test_fun.js'(自动从 __scriptDir 查找已保存的脚本)
- 网络路径: 'http://example.com/lib.js' 或 'https://example.com/lib.js'
- 自动补 .js 扩展名(如果省略)
@returns 模块的 exports 对象
@example
// CommonJS 模块 (lib.js):
// module.exports = { add: function(a, b) { return a + b; } };
var lib = require('/sdcard/lib.js');
log(lib.add(1, 2)); // 3
@example
// ES Module 语法 (主脚本中直接使用):
import { add } from '/sdcard/lib.js';
export function calculate(a, b) { return add(a, b) * 2; }
@example
// 网络模块:
var httpLib = require('https://cdn.example.com/utils.js');

func readFile

declare function readFile(path: string): string
读取脚本数据目录内的文本文件(路径白名单:脚本目录、/sdcard/AutoEngine、
/sdcard/auto_engine、应用专属外部目录;Windows 为 Documents/auto_engine 等)。
含 .. 的路径与应用私有目录会被拒绝

func writeFile

declare function writeFile(path: string, content: string): "ok"
写入文本文件(自动创建父目录,路径白名单同 readFile),失败抛出 Error

namespace require

require.resolve — 解析模块完整路径(不加载执行)

require.resolve()

require.resolve(path: string): string
常量类型说明
cache{ [path: string]: NodeModule } 模块缓存对象

数据采集 (collectData)

interface DataCollectionField

collectData 单个采集字段配置
字段类型说明
keystring 字段键名(存储与返回 data 中的键)
label?string 采集时的界面提示文本(rect: true 时显示)
rect?boolean true 时动态采集矩形区域(配合 count 生成多组)
region?RegionExpr 固定采集区域(RegionExpr),与 rect 二选一
📋 类型定义原文
interface DataCollectionField {
}

interface CollectDataOptions

collectData 选项
字段类型说明
triggerstring 触发文本(支持匹配前缀语法: =, ~=, ^=, $=, re=)
triggerRegion?RegionExpr 触发文本所在区域(RegionExpr)
collectionsDataCollectionField[] 采集区域配置数组(必填,非空)
count?number 动态区域组数(存在 rect: true 字段时生效),默认 1
customFields?{ [field: string]: any } 自定义字段,会合并进每条数据
dataKey?string 数据集名称,默认 "default"
idKey?string 唯一键字段名,默认取第一个 collection 的 key
log?boolean | string true 输出过程日志;传字符串则在采集成功时额外输出该文本
📋 类型定义原文
interface CollectDataOptions {
}

interface CollectDataResult

collectData 单条采集结果
字段类型说明
collectedboolean 采集是否成功
idstring 唯一键值(idKey 字段的值)
data{ [key: string]: any } 采集到的完整数据对象(采集字段 + 自定义字段)
totalnumber 当前数据集总数
📋 类型定义原文
interface CollectDataResult {
}

func collectData

declare function collectData(options: CollectDataOptions): (CollectDataResult & CollectDataResult[]) | null
数据库采集 — 屏幕区域文本采集 + JSON 持久化 + 自定义字段
当屏幕特定区域出现触发文本时,自动采集多个区域的文本数据并保存到 JSON 文件。
单组模式返回单条结果;多组模式(rect: true + count >= 2)返回结果数组;未触发返回 null。
(JS 中两种返回形态都可直接访问 data/id/total/length 等属性,类型为交叉类型以兼容两种用法)
@param options 采集配置
@returns {collected, id, data, total} 或数组(多组模式),未触发时为 null
@example
```js
collectData({
trigger: "~=选择技能",
triggerRegion: "top",
collections: [
{ key: "name", region: skillNameArea, label: "技能名" },
{ key: "desc", region: skillDescArea, label: "描述" },
],
customFields: { level: 1 },
dataKey: "skills",
idKey: "name",
log: true
});
```
📄 示例:125_collectData.js(点击展开)
// 当屏幕特定区域出现触发文本时,自动采集多个区域的文本数据并保存到 JSON 文件。
// 适用场景: 游戏中采集技能名/描述/等级、物品名/属性等数据,方便后续脚本读取和云端共享。
//
// 参数说明:
//   trigger (string)      — 触发文本(支持匹配前缀: =, ~=, ^=, $=, re=)
//   triggerRegion (RegionExpr?) — 触发文本所在区域(可选,不设则全屏检测)
//   collections (array)   — 采集区域配置数组
//     { key: string, region: RegionExpr, label?: string }        — 固定区域模式
//     { key: string, rect: true, label?: string }                — 动态采集区域模式
//     key: 数据字段名(如 "name")
//     region: 采集区域(setRect 返回的对象或区域表达式字符串)
//     rect: true 表示通过 setRect 动态采集区域(与 region 互斥)
//     label: 可选,日志中显示的名称
//   count (number?)       — 生成多组采集区域的数量(仅在 collections 有 rect:true 时生效)
//     count=3 → 为每个 rect:true 的字段生成 3 个 setRect 调用
//     首次调用弹出 Activity 采集 3×N 个区域,后续从缓存读取
//   customFields (object?) — 自定义字段(固定值,追加到每条数据)
//     如 { level: 1, category: "攻击" }
//   dataKey (string)      — 数据集名称(默认 "default")
//   idKey (string)        — 用哪个采集字段作为唯一键去重(默认第一个采集的 key)
//   log (bool|string)    — 输出采集日志
//
// 返回:
//   单组模式: { collected: true, id: "...", data: {...}, total: N } 或 null(未触发)
//   多组模式: [result1, result2, ...] 或 null(未触发)
//   collected: true — 采集成功
//   id: 唯一键值
//   data: 完整数据对象(采集字段 + 自定义字段 + __collectedAt 时间戳)
//   total: 当前数据集总数

// ============================================================
// flutter-auto API 示例 — 21. collectData — 数据库采集(屏幕区域文本采集 + JSON 持久化 + 自定义字段)
// 21. collectData — 数据库采集(屏幕区域文本采集 + JSON 持久化 + 自定义字段)
// ============================================================

func queryData

declare function queryData(dataKey: string, options?: { filter?: { [key: string]: any }; prefix?: string }): { [key: string]: any }
查询数据集
@param dataKey 数据集名称
@param options 可选: filter 按字段筛选;prefix 按 idKey 前缀筛选
@returns 所有匹配数据(键值对对象)

func getDataCount

declare function getDataCount(dataKey: string): number
获取数据集总数
@param dataKey 数据集名称
@returns 数据条数

func clearData

declare function clearData(dataKey: string): true
清空数据集
@param dataKey 数据集名称
@returns true

func deleteData

declare function deleteData(dataKey: string, id: string): true
删除数据集中的单条数据
@param dataKey 数据集名称
@param id 条目的唯一键值(idKey 字段的值)
@returns true

func exportData

declare function exportData(dataKey: string, filePath?: string): string | null
导出数据集为 JSON 文件
@param dataKey 数据集名称
@param filePath 可选导出路径,不传时自动生成
@returns 导出文件路径,失败时为 null

func importData

declare function importData(dataKey: string, filePath: string): number
从 JSON 文件导入数据到数据集
@param dataKey 数据集名称
@param filePath JSON 文件路径
@returns 导入条数,失败时为 0

func listDataSets

declare function listDataSets(): string[]
列出所有数据集名称
@returns 数据集名称数组

可视化核对 (show*)

func showRect

declare function showRect(key?: string): boolean
在透明 Activity 上可视化展示已保存的矩形区域,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容

func showPosition

declare function showPosition(key?: string): boolean
在透明 Activity 上可视化展示已保存的坐标点(圆圈),点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容

func showColor

declare function showColor(key?: string): boolean
在透明 Activity 上可视化展示已保存的取色点,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容

func showSwipe

declare function showSwipe(key?: string): boolean
在透明 Activity 上可视化展示已保存的滑动轨迹,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容

func showJoystick

declare function showJoystick(key?: string): boolean
在透明 Activity 上可视化展示已保存的摇杆区域,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容

func showOcr

declare function showOcr(results?: OcrResult[] | OcrResult | null, options?: { region?: RegionExpr }): boolean
在屏幕上可视化展示 OCR 识别结果(半透明青框 + "文字 (置信度%)" 标签)
@param results 可选,ocr() 返回的结果数组或 ocrFind() 返回的单结果;
不传时内部自动执行 ocr()
@param options 可选: {region: 区域表达式},仅在未传 results 时生效
@returns 是否有可显示的结果
@example
```js
var results = ocr().region("top");
showOcr(results); // 核对 region 过滤后的结果
showOcr(null, {region: "top"}); // 内部执行 ocr() 时限定区域
```

摇杆控制 (joystick)

func joystick

declare function joystick( key: string | JoystickArea, direction: string | number, duration?: number, options?: { strength?: number; pressDuration?: number; releaseDuration?: number; returnToCenter?: boolean; pkg?: string; act?: string; } ): { success: boolean; skipped?: boolean; reason?: string; key?: string; direction?: string }
模拟推动虚拟摇杆(配合 setJoystick 录制的摇杆区域使用)
@param key 摇杆键名(setJoystick 保存的键名)或摇杆对象 {cx, cy, radius}
@param direction 推杆方向: "up"/"down"/"left"/"right" 及斜向("up-left" 等)、
数字 1~9(小键盘方位)、"n"/"s"/"w"/"e"/"ne"/"nw"/"se"/"sw" 简写
@param duration 推杆保持时间(ms),默认 500;0 表示推到位立即释放
@param options 可选: strength 推杆强度 0~1(默认 0.8);pressDuration/releaseDuration(ms,默认 100);
returnToCenter 结束后是否回中(默认 true);pkg/act 前台包名/Activity 限制
@returns 推杆结果 {success, ...},pkg/act 不匹配时 {success: false, skipped: true, ...}

摇杆队列(多线程安全的摇杆操作序列)

func joystickQueue

declare function joystickQueue( key: string, direction: string | number, duration?: number, options?: { strength?: number; pressDuration?: number; releaseDuration?: number; returnToCenter?: boolean; pkg?: string; act?: string; } ): number
入队一个摇杆操作(立即返回不阻塞,由 worker 线程按顺序执行)
参数同 joystick();摇杆须先用 setJoystick 录入,否则抛 Error
@param key 摇杆键名
@param direction 方向
@param duration 持续毫秒(默认 500)
@param options strength 默认 0.8;pressDuration/releaseDuration 默认 100;
returnToCenter 默认 true;pkg/act 前台包名/Activity 校验(可选,
支持 "re=前缀" 正则规则,不匹配时该任务被跳过)
@returns 入队后的队列长度

func pauseJoystick

declare function pauseJoystick(): boolean
暂停摇杆队列执行:当前正在执行的摇杆操作自然完成,完成后 worker 不再取下一个任务
@returns true

func resumeJoystick

declare function resumeJoystick(): number
恢复摇杆队列执行,worker 继续从队列取任务
@returns 当前队列长度

func clearJoystickQueue

declare function clearJoystickQueue(): number
清空摇杆队列(当前正在执行的摇杆操作不受影响,会自然完成)
@returns 清空前的队列长度

func getJoystickQueueStatus

declare function getJoystickQueueStatus(): { length: number; paused: boolean }
获取摇杆队列状态

func startJoystickWorker

declare function startJoystickWorker(): Thread
启动摇杆队列 worker 线程(循环:检查暂停 → FIFO 取任务 → 前台校验 →
执行推杆;队列为空时 50ms 轮询等待新任务;脚本停止时随 threads 一起回收)
@example
```js
var w = startJoystickWorker(); // 主脚本启动 worker
joystickQueue("move", "up", 5000); // 入队操作
pauseJoystick(); // 检测到升级界面 → 暂停,处理完 resumeJoystick()
clearJoystickQueue(); // 清空残留操作
w.interrupt(); // 停止 worker
```
@returns Thread 对象,可通过 thread.interrupt() 停止

配置同步 (checkSettings / exportSettings / importSettings)

func checkSettings

declare function checkSettings(filterKeys?: string | string[]): { /** 配置项总数 */ total: number; /** 已配置数量 */ configured: number; /** 配置明细列表 */ details: Array<{ key: string; type: string; hint: string; configured: boolean }>; }
检查配置完整性 — 列出脚本依赖的配置项及配置状态
@param filterKeys 可选,只检查指定键名(字符串或数组),不传则检查全部已注册配置
@returns 配置报告对象(含 list/details 数组,每项 {key, type, hint, configured})
@example
```js
var report = checkSettings();
report.details.forEach(function (d) {
log((d.configured ? '✓' : '✗') + ' ' + d.key + ' (' + d.type + ') — ' + d.hint);
});
```
📄 示例:179_checkSettings.js(点击展开)
// 遍历 __settingsRegistry(每次 setPosition/setRect/setColor/setSwipe/
// setJoystick/setConf/setBox 调用时自动注册),检查每个设置项是否已在
// 数据库中缓存。
//
// 设置截图自动保存:每次 set* 成功设置后,截图会自动保存到
//   Android: /sdcard/AutoEngine/settings_check/{type}_{key}.png + .txt
//   Windows: C:\settings_check\{type}_{key}.png + .txt
//   在 Flutter 端"检查配置"按钮可查看每个已配置项的截图。
//
// 返回: { total, configured, pending, details: [{key, type, hint, configured}] }
//   - total: 总数
//   - configured: 已配置数
//   - pending: 待配置数
//   - details: 详情列表
//
// 另有 __checkScriptSettings(scriptText) (2.0.0 新增):
//   不执行脚本,静态分析脚本文本,提取所有 set* 调用的键名和类型。
//   Flutter 端"检查配置"按钮通过 evalJs 调用此函数。
//   返回格式同 checkSettings,但额外包含 value 字段(已配置项的数据库值)。

// ============================================================
// flutter-auto API 示例 — 38. checkSettings — 检查脚本中所有配置项的设置情况 (1.9.6 新增)
// 38. checkSettings — 检查脚本中所有配置项的设置情况 (1.9.6 新增)
// ============================================================
📄 示例:180_checkSettings.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 38. checkSettings — 检查脚本中所有配置项的设置情况 (1.9.6 新增)
// checkSettings() — 检查所有设置
// ============================================================

// --- checkSettings() — 检查所有设置 ---
// 检查所有已注册的设置项
var report = checkSettings();
log("已配置: " + report.configured + "/" + report.total + ", 待配置: " + report.pending);
for (var i = 0; i < report.details.length; i++) {
    var d = report.details[i];
    log((d.configured ? '✓' : '✗') + ' ' + d.key + ' (' + d.type + ') — ' + d.hint);
}
📄 示例:181_checkSettings.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 38. checkSettings — 检查脚本中所有配置项的设置情况 (1.9.6 新增)
// checkSettings(filterKeys) — 检查指定键
// ============================================================

// --- checkSettings(filterKeys) — 检查指定键 ---
// 只检查指定的键名
var report2 = checkSettings(["btnArea", "dice", "btnColor", "skillsArea"]);
if (report2.pending > 0) {
    log("有 " + report2.pending + " 个设置尚未配置,请运行脚本进行设置");
} else {
    log("所有设置已配置完毕");
}

func exportSettings

declare function exportSettings(filePath?: string, keys?: string | string[]): string | null
导出配置到 JSON 文件
@param filePath 可选导出文件路径,不传时自动生成
@param keys 可选,只导出指定键名的配置,不传则导出全部
@returns 导出文件路径(成功)或 null(失败)
📄 示例:184_exportSettings.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 39. exportSettings / importSettings — 配置导出和导入 (2.6.6 新增)
// exportSettings(filePath?) — 导出所有配置
// ============================================================

// --- exportSettings(filePath?) — 导出所有配置 ---
// 参数:
//   filePath (string, 可选) — 导出文件路径,默认 /sdcard/auto_engine/settings_export.json
// 返回: 文件路径字符串(成功)或 null(失败)

// 示例1: 导出所有配置到默认路径
var exportPath = exportSettings();
if (exportPath) {
    log("配置已导出到: " + exportPath);
    // 将文件传输到新设备后,在新设备上调用 importSettings 即可
}

// 示例2: 自定义导出路径
var customPath = exportSettings("/sdcard/my_game_config.json");
if (customPath) {
    log("配置已导出到: " + customPath);
}

func importSettings

declare function importSettings(filePath: string, options?: { overwrite?: boolean; keys?: string | string[] }): number
从 JSON 文件导入配置
@param filePath JSON 文件路径
@param options 可选: overwrite 是否覆盖已存在配置(默认 false);keys 只导入指定键名
@returns 导入的配置项数量(0 表示失败或无配置可导入)
📄 示例:185_importSettings.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 39. exportSettings / importSettings — 配置导出和导入 (2.6.6 新增)
// importSettings(filePath, options?) — 从 JSON 文件导入配置
// ============================================================

// --- importSettings(filePath, options?) — 从 JSON 文件导入配置 ---
// 参数:
//   filePath (string) — 要导入的 JSON 文件路径
//   options (object, 可选):
//     overwrite (boolean) — 是否覆盖已存在的配置,默认 false(仅导入不存在的配置)
// 返回: 导入的配置项数量(0 表示失败或无配置可导入)

// 示例3: 从默认路径导入(仅导入不存在的配置,跳过已有的)
var imported = importSettings("/sdcard/auto_engine/settings_export.json");
if (imported > 0) {
    log("成功导入 " + imported + " 个配置项");
    // 导入后可直接运行脚本,无需重新手动配置
} else {
    log("没有新的配置需要导入(可能已全部配置)");
}

// 示例4: 覆盖模式导入(强制覆盖所有已存在的配置)
var imported2 = importSettings("/sdcard/my_game_config.json", {overwrite: true});
log("覆盖导入 " + imported2 + " 个配置项");

// 示例5: 脚本中自动导入(换机后第一次运行时自动导入)
var settingsFile = "/sdcard/auto_engine/my_config.json";
var count = importSettings(settingsFile);
if (count > 0) {
    log("首次导入配置成功: " + count + " 个配置项");
} else {
    // 导入失败或文件不存在,需要手动配置
    log("未找到配置文件或无需导入,请手动配置");
    var skillsArea = setRect("skillsArea", {hint: "请框选技能区域"});
    var dice = setPosition(["dice"], {hint: "请点击骰子按钮"});
    // 配置完成后导出,方便下次使用
    exportSettings(settingsFile);
}

APK 打包 (buildApk)

func buildApk

declare function buildApk(options: { /** APK 显示名称 */ appName?: string; /** 打包进 APK 的脚本内容(缺省用当前脚本) */ code?: string; /** 包名(缺省自动生成) */ pkg?: string; /** 其他打包选项 */ [key: string]: any; }): string
在安卓手机上将脚本打包为独立 APK(仅 Android 端可用,NativeCall 转发到 Kotlin 侧 ApkBuilder)
@param options 打包选项
@returns APK 文件路径(成功)或抛出异常(失败)
@example
```js
var apkPath = buildApk({ appName: "我的脚本", code: "console.log('hello');" });
```
📄 示例:178_buildApk.js(点击展开)
// 仅 Android 端可用。将当前脚本(或指定脚本内容)打包为独立 APK,
// 安装后可直接运行,无需安装主应用。
//
// 打包流程:
//   1. 以当前 App APK 为模板(包含完整自动化引擎)
//   2. 修改包名、应用名、版本号
//   3. 将脚本注入 assets/project/main.js
//   4. V1 签名输出
//
// 参数:
//   options: {
//     appName: String,        // 应用名(桌面图标下显示的名称),默认脚本文件名
//     packageName: String,   // 包名,默认 com.autoengine.script.xxx
//     versionName: String,   // 版本名,默认 "1.0.0"
//     versionCode: Number,   // 版本号,默认 1
//     scriptContent: String,  // 脚本内容,默认当前脚本内容
//     outputPath: String     // 输出路径,默认 /sdcard/AutoEngine/{appName}_v{versionName}.apk
//   }
//
// 返回: 输出 APK 文件路径字符串,失败抛异常

// ============================================================
// flutter-auto API 示例 — 37. buildApk(options) — 在安卓手机上将脚本打包为独立 APK
// 37. buildApk(options) — 在安卓手机上将脚本打包为独立 APK
// ============================================================


// 示例1: 基本打包
var apkPath = buildApk({
    appName: "我的脚本",
    packageName: "com.autoengine.script.myscript",
    versionName: "1.0.0",
    versionCode: 1
});
log("APK 已生成: " + apkPath);

// 示例2: 打包指定脚本内容
buildApk({
    appName: "自动签到",
    packageName: "com.autoengine.script.signin",
    versionName: "2.0.0",
    versionCode: 2,
    scriptContent: "log('Hello from packaged APK'); click(500, 500);"
});