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 发布流程与审核
- 本地开发调试(VSCode 扩展提供
auto-engine.d.ts全量类型提示); - 发布:定价
price_cents ≥ 1(积分/天,已无永久免费档),试用时长trial_hours6-12 小时由作者设定; - 发布后进入 pending 审核,管理员通过后才在市场可见;在架脚本更新代码会自动 patch 版本 +1 并重新进入审核;
- 购买按月计费(1-12 月),定价语义为积分/天,成交价 = 单价 × 30 × 月数,作者分成 80%;
- 每个脚本保留最近 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() 方法)
| 字段 | 类型 | 说明 |
|---|---|---|
| region | RegionFilter<UiNodeArray> | 链式区域过滤:返回在指定区域内的子数组 |
📋 类型定义原文
interface UiNodeArray extends Array<UiNode> {
}interface UiNodeGroupResult
findAll 多组模式返回的结果对象
| 字段 | 类型 | 说明 |
|---|---|---|
| groupIndex | number | 匹配组的索引(从 0 开始,-1 不会被返回——全未命中时返回 null) |
| selectors | string[] | 该组的选择器表达式数组 |
| matches | UiNode[][] | 二维数组: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 控件节点
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | null | 控件 ID(通常为 null) |
| text | string | null | 文本内容(无文本时为 null) |
| desc | string | null | 描述文本(无描述时为 null) |
| type | string | 节点类型 (node_type) |
| bounds | Bounds | 边界 [left, top, width, height] |
| center? | Center | 中心点 [cx, cy]。 注意:原始 dumpUiTree 节点可能没有该字段(可由 bounds 计算: cx = bounds[0] + bounds[2]/2, cy = bounds[1] + bounds[3]/2), 引擎内部取坐标时也会自动从 bounds 计算 |
| clickable | boolean | 是否可点击 |
| scrollable | boolean | 是否可滚动 |
| enabled | boolean | 是否启用 |
| package | string | 包名 |
| class_name | string | null | 类名。 字段名说明:引擎直出的控件树为 snake_case 的 class_name (serde 序列化 schema,与 dumpUiTree 输出一致); 部分桌面/兼容路径序列化为 className。两者取其一,建议用 class_name |
| className? | string | null | 类名(camelCase 别名,仅部分兼容路径存在) |
| focusable | boolean | null | 是否可聚焦 |
| focused | boolean | null | 是否已聚焦 |
| checkable | boolean | null | 是否可勾选 |
| checked | boolean | null | 是否已勾选 |
| selected | boolean | null | 是否已选中 |
| long_clickable | boolean | null | 是否可长按 |
| longClickable? | boolean | null | 是否可长按(camelCase 别名,仅部分兼容路径存在) |
| password | boolean | null | 是否密码框 |
| visible_to_user | boolean | null | 是否对用户可见 |
| visibleToUser? | boolean | null | 是否对用户可见(camelCase 别名,仅部分兼容路径存在) |
| parent_class | string | null | 父控件类名 |
| parentClass? | string | null | 父控件类名(camelCase 别名,仅部分兼容路径存在) |
| depth | number | null | 树深度(根节点为 0) |
| index_in_parent | number | null | 在父节点中的索引(原始树中常为 null,JS 层会另算 indexInParent) |
| indexInParent? | number | 在父节点中的索引(JS 层遍历子节点时计算并追加,子节点始终可用) |
| drawing_order | number | null | 绘制顺序 |
| drawingOrder? | number | null | 绘制顺序(camelCase 别名,仅部分兼容路径存在) |
| accessibility_focused | boolean | null | 是否已获得无障碍焦点 |
| dismissable | boolean | null | 是否可消失(如 Toast) |
| editable | boolean | null | 是否可编辑 |
| multi_line | boolean | null | 是否多行文本 |
| content_invalid | boolean | null | 内容是否失效 |
| context_clickable | boolean | null | 是否可长按弹出上下文菜单 |
| column | number | null | 网格布局列索引(无值时为 null) |
| column_count | number | null | 网格布局列数(无值时为 null) |
| column_span | number | null | 网格布局列跨度(无值时为 null) |
| row | number | null | 网格布局行索引(无值时为 null) |
| row_count | number | null | 网格布局行数(无值时为 null) |
| row_span | number | null | 网格布局行跨度(无值时为 null) |
| children? | UiNode[] | 子节点数组(findOne/findAll/dumpUiTree 返回的节点均包含) |
| region | RegionFilter<UiNode | null> | 链式区域过滤:返回在指定区域内的本节点(不在区域内返回 null) |
📋 类型定义原文
interface UiNode {
parent(n?: number): UiNode | null;
child(i: number): UiNode | null;
}颜色查找结果
interface ColorMatch
单个颜色匹配结果
| 字段 | 类型 | 说明 |
|---|---|---|
| x | number | 匹配区域质心 X 坐标 |
| y | number | 匹配区域质心 Y 坐标 |
| w | number | 外接矩形宽度 |
| h | number | 外接矩形高度 |
| area | number | 匹配像素面积 |
| region | RegionFilter<ColorMatch | null> | 链式区域过滤 |
📋 类型定义原文
interface ColorMatch {
}interface MultiColorMatch
多点找色结果
| 字段 | 类型 | 说明 |
|---|---|---|
| x | number | 锚点 X 坐标 |
| y | number | 锚点 Y 坐标 |
| region | RegionFilter<MultiColorMatch | null> | 链式区域过滤 |
📋 类型定义原文
interface MultiColorMatch {
}图像查找结果
interface ImageMatch
单个图像匹配结果
| 字段 | 类型 | 说明 |
|---|---|---|
| x | number | 匹配中心 X 坐标 |
| y | number | 匹配中心 Y 坐标 |
| confidence | number | 置信度 0.0~1.0 (匹配特征点数 / 20) |
| region | RegionFilter<ImageMatch | null> | 链式区域过滤 |
📋 类型定义原文
interface ImageMatch {
}OCR 结果
interface OcrResult
OCR 识别结果
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | 识别文本 |
| confidence | number | 置信度 0~1 |
| bbox | Bounds | 边界框 [x, y, w, h] |
| center | Center | 中心点 [cx, cy] |
| region | RegionFilter<OcrResult[]> | 链式区域过滤 |
📋 类型定义原文
interface OcrResult {
}aiTxt 结果
interface AiTxtMatch
aiTxt 单条匹配(主匹配 data / matched 数组元素的类型)
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | null | 匹配到的文本 |
| desc? | string | null | 描述文本(仅选择器模式附带) |
| center | Center | 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 模式配对信息
都返回同一结构,只是各字段的值随模式不同;未匹配返回 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 模式配对信息
| 字段 | 类型 | 说明 |
|---|---|---|
| index | number | 命中索引:单文本/AND/多文本查找/box 恒为 0;多组/pair 模式为命中的组索引(按传入顺序) |
| data | AiTxtMatch | 主匹配结果,可直接传给 click(ret.data) |
| matched | AiTxtMatch[] | 全部命中(恒有 matched[0] === data): - 单文本/选择器: 区域内全部候选 - AND 模式: 各文本的首个匹配(顺序与传入文本一致) - 多组模式: 命中组内的全部匹配 - pair 模式: [主匹配] |
| text | string | null | 匹配到的文本(= data.text,便捷透传) |
| center | Center | null | 中心点 [cx, cy](= data.center,click(ret) 直接可用) |
| source | "ui" | "ocr" | null | 来源: 'ui' (无障碍控件) 或 'ocr' (文字识别) |
| confidence | number | 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 选项复用,跳过二次截图) |
| groupIndex | number | 兼容别名 = index(旧版多组模式字段名) |
| first | AiTxtMatch | 兼容别名 = 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),不能用返回值判空
只有非枚举的 matched=false 与 __texts 文本池两个字段,text/center/data 等均为 undefined。
判断命中必须用 ret.matched !== false(或 ret.text != null),不能用返回值判空
| 字段 | 类型 | 说明 |
|---|---|---|
| center | undefined | @deprecated 未命中对象上恒为 undefined |
| __texts | Array<{ 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
线程对象
| 字段 | 类型 | 说明 |
|---|---|---|
| _id | number | 线程 ID (主线程为 0) |
| _alive | boolean | 是否存活 |
📋 类型定义原文
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() 返回项,分屏多窗口用)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 窗口 id(bindWindow/pauseWindow 等用) |
| package | string | 窗口所属应用包名 |
| bounds | [number, number, number, number] | 窗口区域 [x, y, w, h] |
| active | boolean | 是否活跃窗口 |
| focused | boolean | 是否持有焦点 |
📋 类型定义原文
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
表单字段定义
| 字段 | 类型 | 说明 |
|---|---|---|
| key | string | 字段键名 (必填) |
| label | string | 显示标签 (必填) |
| 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 | 表单标题,默认 '配置' |
| fields | FormField[] | 字段列表 (必填) |
📋 类型定义原文
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 点击目标,支持多种形式:
-
-
-
-
-
@returns "ok"(成功);目标为 null、文本未找到、类型无效、pkg/act 不匹配、
check 验证失败或内部异常时返回 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
@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"
@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}); // 快速向右滑动 300msfunc 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
@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
@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"
@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"
@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"
@returns "ok"
func KeyCode
declare function KeyCode(code: number | string): boolean
通过键码模拟按键
@param code 数字(Android KeyEvent 键码) 或字符串(按键名)
@returns 是否成功
@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}
@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 为字节数)
@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() 返回的节点统计结果
| 字段 | 类型 | 说明 |
|---|---|---|
| total | number | 总节点数(包含根节点,等于 parents + leaves) |
| parents | number | 父节点数(有至少一个子节点的节点) |
| leaves | number | 子节点数(叶子节点,无子节点) |
📋 类型定义原文
interface WidgetCountResult {
}func widgetCount
declare function widgetCount(): WidgetCountResult
统计当前界面的 UI 节点数量
复用 dumpUiTree 采集整棵控件树并递归统计:
-
-
-
适用场景:
- 判断界面复杂度(如检测是否进入新页面、列表是否加载完成)
- 等待界面稳定(轮询直到 total 不再变化)
- 对比不同状态下的控件数量差异
性能:与 dumpUiTree 共用一次原生调用,统计在 JS 侧递归完成,
1000 节点 < 5ms,不会阻塞脚本。
@returns 节点统计结果,无控件树时返回
@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);
```
复用 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 语法:
-
-
-
-
-
-
- 属性选择器:
- 多条件 AND: 用
@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"});
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"});
@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())
@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"});
@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});
@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]);
@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});
@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(超时仍存在)
@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 像素数据
@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
屏幕无变化时深度休眠(最长 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 加载的文件数量
注册后 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 对象
@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
@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
@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())
@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
支持多模板冗余: 传入路径数组时逐一尝试,返回置信度最高的结果。
底层会自动缓存模板图片。
@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())
@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
@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 等控件消失
```
通过 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"
@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'
@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"
@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 | nulldeclare function aiTxt( texts: string[], options: AiTxtOptions & { reuse: true } ): AiTxtResult | AiTxtReuseMiss | nulldeclare 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 | nulldeclare 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 | nulldeclare 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 被引擎忽略;独立第二参数中的这三项同样被忽略
⚠ 外层数组末尾内联 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 包名字符串,失败返回 ""
@returns 包名字符串,失败返回 ""
func currentActivity
declare function currentActivity(): string
获取当前前台 Activity 类名
查询优先级:
1. dumpsys activity activities 的 Resumed 行
2. 无障碍事件缓存的 className
3. UsageStatsManager (仅包名)
4. Activity 历史记录回退 (长度 5,元素唯一)
5. 应用自身包名 (最终回退,不返回空字符串)
查询优先级:
1. dumpsys activity activities 的 Resumed 行
2. 无障碍事件缓存的 className
3. UsageStatsManager (仅包名)
4. Activity 历史记录回退 (长度 5,元素唯一)
5. 应用自身包名 (最终回退,不返回空字符串)
func currentComponent
declare function currentComponent(): string
获取当前前台组件名
@returns "包名/活动名" 格式字符串
@returns "包名/活动名" 格式字符串
通用工具
func sleep
declare function sleep(ms: number): void
阻塞等待 (可中断)
每 100ms 检查一次 stop_flag,若为 true 则抛出 Error("脚本已被用户停止")
@param ms 等待毫秒
每 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);
```
模拟「打开页面 → 阅读 → 再操作」的人类停顿,避免操作间隔恒定。
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 任意多个参数
@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 控制台
-
-
@example
// 正常退出
exit();
// 退出并推送界面分析到 PC 端
exit(true);
@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 端
-
-
与
-
-
不受「脚本退出推送界面分析」总开关控制(脚本主动请求,始终推送)。
但仍需以下条件才能送达 VSCode 端:
1. 无障碍服务已启用
2. 截图权限已授予
3. WebEditorServer 正在运行
4. VSCode 扩展 webview 已打开
@returns JSON 字符串
@example
// 采集当前界面并推送到 PC 端
var result = pushUI();
console.log(result); // {"success":true}
// 在关键步骤推送界面快照,便于后续分析
aiTxt("登录");
pushUI(); // 保存登录界面快照
click(500, 800);
sleep(2000);
pushUI(); // 保存登录后界面快照
脚本运行中随时可调用,采集当前界面截图+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
@param callback 回调函数
@param delay 延时毫秒,默认 0
@returns timerId
func setInterval
declare function setInterval(callback: Function, delay?: number): number
循环执行
@param delay 间隔毫秒,默认 0 (内部强制 ≥1)
@returns timerId
@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
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | Toast 文本内容 |
| packageName | string | Toast 来源包名 |
📋 类型定义原文
interface ToastEvent {
}interface NotificationEvent
通知事件 payload
| 字段 | 类型 | 说明 |
|---|---|---|
| package | string | 通知来源包名 |
| title | string | 通知标题 |
| text | string | 通知正文 |
| time | number | 通知发布时间(毫秒时间戳) |
📋 类型定义原文
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 包装后的函数
返回新函数,执行时自动 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
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@param key 键名
@param value 任意可 JSON 序列化的值
@returns true
func getKey
declare function getKey(key: string): any
读取键值 (config 命名空间)
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@returns 存储的值或 null
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@returns 存储的值或 null
func delKey
declare function delKey(key: string): true
删除键值 (config 命名空间)
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@returns true
线程安全:内部自动加全局可重入锁,多线程下可安全调用。
@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);
});
用于"读-修改-写"等需要多步原子操作的场景。锁是可重入的,
回调内调用 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)的选项
| 字段 | 类型 | 说明 |
|---|---|---|
| hint | string | 说明文本,描述此配置的用途(必填,不能为空字符串) |
📋 类型定义原文
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. 用户点击"重来" → 清除当前点重新选点
必须使用对象解构赋值:
也兼容字符串写法:
@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
```
通过透明 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); // 每次点击位置略有不同
}
```
坐标点存储格式为圆圈(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
@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 键名数组
@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 已有缓存则直接返回,否则启动滑动录入界面。
必须使用对象解构赋值:
@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); // 重放滑动
```
通过透明 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",...]/falsefunc delSwipe
declare function delSwipe(key: string): true
删除滑动轨迹 (即使 key 不存在也返回 true)
@returns true
@returns true
func listSwipes
declare function listSwipes(): string[]
列出所有滑动键名
@returns 键名数组
@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}); // 覆盖时长
```
默认变换: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 已有缓存则直接返回,否则启动摇杆录入界面。
必须使用对象解构赋值:
也兼容字符串写法:
@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: "请点击移动摇杆的圆心位置"});
```
通过透明 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
@returns 摇杆区域对象或 null
func delJoystick
declare function delJoystick(key: string): true
删除摇杆区域 (即使 key 不存在也返回 true)
@returns true
@returns true
func listJoysticks
declare function listJoysticks(): string[]
列出所有摇杆键名
@returns 键名数组
@returns 键名数组
矩形区域管理 (setRect)
interface RectArea
矩形区域对象
| 字段 | 类型 | 说明 |
|---|---|---|
| key | string | 键名 |
| xMin | number | 矩形左边界 x 坐标 |
| xMax | number | 矩形右边界 x 坐标 |
| yMin | number | 矩形上边界 y 坐标 |
| yMax | number | 矩形下边界 y 坐标 |
| tl | Point | 左上角坐标 |
| tr | Point | 右上角坐标 |
| bl | Point | 左下角坐标 |
| br | Point | 右下角坐标 |
| width | number | 矩形宽度 |
| height | number | 矩形高度 |
📋 类型定义原文
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}
```
通过透明 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
@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
@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 键名数组
@returns 键名数组
📄 示例:148_listRects.js(点击展开)
// ============================================================
// flutter-auto API 示例 — 23. setRect — 用户手动设置矩形区域(4 个角点)
// listRects()
// ============================================================
// --- listRects() ---
// 列出所有已存储的矩形键名。
// 返回:键名字符串数组
var rectKeys = listRects();
log("已存储的矩形区域: " + JSON.stringify(rectKeys));动态区域 (setBox)
interface BoxConfig
setBox 区域配置(相对锚点文本的动态矩形)
| 字段 | 类型 | 说明 |
|---|---|---|
| key | string | 键名 |
| text | string | 锚点文本(支持匹配前缀: =, ~=, ^=, $=, re=) |
| w | number | 矩形宽度 |
| h | number | 矩形高度 |
| dx | number | 锚点文本中心到矩形左上角的 X 偏移 |
| dy | number | 锚点文本中心到矩形左上角的 Y 偏移 |
📋 类型定义原文
interface BoxConfig {
}func setBox
declare function setBox(key: string, text: string, options?: { hint?: string; keys?: string[] }): BoxConfig | null
采集相对锚点文本的动态矩形区域
通过透明 Activity 让用户点击矩形区域的 4 个角点,并在矩形内查找锚点文本计算偏移。
存储相对锚点的尺寸/偏移(锚点在哪框就在哪),与 setRect 的固定坐标相反。
常与 aiTxt 配合:
@param key 键名(必填)
@param text 锚点文本,支持匹配前缀语法(必填)
@param options 可选: hint 说明文本;keys 4 个角点的标签名(默认 ["左上(tl)","右上(tr)","左下(bl)","右下(br)"])
@returns {key, text, w, h, dx, dy} 配置对象,或 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(不存在时)
@param key 键名
@returns 配置对象或 null(不存在时)
func delBox
declare function delBox(key: string): true
删除已存储的 box 配置(即使 key 不存在也返回 true)
@returns true
@returns true
func listBoxes
declare function listBoxes(): string[]
列出所有已存储的 box 键名
@returns 键名数组
@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 表示未找到锚点或配置无效)
@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", "请输入系统确定按钮的文本", "确定");
```
通过透明 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 选择器建议
| 字段 | 类型 | 说明 |
|---|---|---|
| confirmed | true | 采集确认标记(恒为 true) |
| key | string | 键名 |
| x | number | 横坐标 |
| y | number | 纵坐标 |
| center | [number, number] | 控件中心点 [cx, cy](可直接传给 click) |
| bounds | [number, number, number, number] | 控件边界 [x, y, w, h] |
| text | string | 控件文本 |
| desc | string | 控件 contentDescription |
| id | string | 控件资源 id |
| class | string | 控件类名 |
| package | string | 所属应用包名 |
| selector | string | 自动生成的 findOne 选择器("text=…"/"desc=…"/"id=…") |
| createdAt | number | 采集时间戳(毫秒) |
📋 类型定义原文
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
```
(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 不存在)
@param key 键名
@returns true(即使 key 不存在)
func listWidgets
declare function listWidgets(): string[]
列出所有已存储的控件配置键名
@returns 键名数组
@returns 键名数组
setChoose — 采集型选择(4.8.20+,setWidget 同款交互模型)
interface ChoosePick
setChoose 命中的候选对象(ocr 模式含 confidence/bbox,ui 模式含 bounds/id/desc 等)
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | 候选文本(如 "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 返回)
| 字段 | 类型 | 说明 |
|---|---|---|
| matcher | string | 选择条件(创建时的 matcher 原文) |
| mode | 'ocr' | 'ui' | 候选采集方式:'ocr' | 'ui' |
| region | string | 屏幕区域(创建时的 region 原文,未传为空串) |
| text | string | 用户选择/最近自动命中的文本(仅展示用,不参与自动匹配——数值随时会变) |
| cx | number | null | 最近命中项中心 x(自动匹配锚点,平分时比对) |
| cy | number | null | 最近命中项中心 y(自动匹配主锚点:|Δy| ≤ 文字高度×1.5 内取最近) |
| h | number | null | 最近命中项文字高度(位置容差基准) |
| time | number | 最近命中时间戳(毫秒) |
📋 类型定义原文
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 选择条件,支持多种形态:
-
-
-
- 裸字符串 等价
@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"); // 清除记忆(下次重新弹窗校准)
```
(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
@param key 记忆键(与 setChoose 传入的一致)
@returns 记忆对象(matcher/mode/region/text/time),无记忆返回 null
func delChoose
declare function delChoose(key: string): true
清除某选择点的记忆(下次运行到该选择点重新弹窗让用户校准基准)
@param key 记忆键
@returns true(即使 key 不存在)
@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 复查弹窗消失。
弹窗自愈一行写法:
规则列表缓存 30 秒(弹窗循环高频调用不反复查库);单条规则损坏自动跳过不炸任务
@param targetPkg 目标应用包名(规则按此过滤;规则未填包名时对所有包生效)
@param options verify: 点击后 OCR 复查弹窗消失,默认 true(未消失自动试下一条规则);
reload: 强制重载规则列表(默认缓存 30 秒)
@returns true=命中并已处理 / false=无命中
逐条 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(不存在时)
@param key 键名
@returns 文本值,或 null(不存在时)
func delConf
declare function delConf(key: string): true
删除已存储的文本配置
@param key 键名
@returns true(即使 key 不存在)
@param key 键名
@returns true(即使 key 不存在)
func listConfs
declare function listConfs(): string[]
列出所有已存储的文本配置键名
@returns 键名数组
@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: "开始" })) {
// 用户确认
}
```
@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"
```
用于不同系统/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 取色结果
| 字段 | 类型 | 说明 |
|---|---|---|
| x | number | 取色点 X 坐标(屏幕像素) |
| y | number | 取色点 Y 坐标(屏幕像素) |
| color | number | Android Color int(带 alpha 通道,可用于 drawing) |
| hex | string | 十六进制颜色字符串(大写,不含 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 取色选项
| 字段 | 类型 | 说明 |
|---|---|---|
| hint | string | 说明文本,描述此取色的用途(必填,不能为空字符串) |
| 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} 支持解构赋值:
@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: "..."});
```
通过透明 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.hexvar {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 后自动附带)
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | 匹配到的文本 |
| x | number | 文本中心 X 坐标 |
| y | number | 文本中心 Y 坐标 |
| confidence | number | null | OCR 置信度 0~1(不可用时为 null) |
| distance | number | 红点质心到文本预期角点的距离(px,四舍五入) |
📋 类型定义原文
interface NearbyTextInfo {
}interface ColorRegion
checkColor 单个匹配区域
| 字段 | 类型 | 说明 |
|---|---|---|
| x | number | 区域左上角 X 坐标 |
| y | number | 区域左上角 Y 坐标 |
| w | number | 区域宽度 |
| h | number | 区域高度 |
| area | number | 连通域面积(px²) |
| fillRatio | number | 填充率 0~1(circle≈0.785、rect≈1.0、cross/check<0.35) |
| aspectRatio | number | 宽高比 |
| hasSubColor? | boolean | 是否包含副色像素(配置了 subColor 验证时附带) |
| nearbyText? | NearbyTextInfo | null | 距离最近的 OCR 文本(配置了 position 时附带,无匹配文本时为 null) |
📋 类型定义原文
interface ColorRegion {
}interface MultiColorRef
checkColor 多点颜色验证对象
| 字段 | 类型 | 说明 |
|---|---|---|
| color | string | number | 主色: "#FF0000" 字符串 / 颜色 int / setColor 键名 |
| offsets | Array<[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 匹配结果
| 字段 | 类型 | 说明 |
|---|---|---|
| matched | boolean | 是否有匹配 |
| count | number | 匹配区域数量 |
| regions | ColorRegion[] | 匹配区域列表 |
| 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);
});
}
```
在屏幕截图中查找匹配颜色区域,高亮标注后可弹窗预览。
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(不存在时)
@param key 键名
@returns 取色结果对象,或 null(不存在时)
func delColor
declare function delColor(key: string): true
删除已存储的取色结果
@param key 键名
@returns true(即使 key 不存在)
@param key 键名
@returns true(即使 key 不存在)
func listColors
declare function listColors(): string[]
列出所有已存储的取色键名
@returns 键名数组
@returns 键名数组
时间日期比较
interface CompTimeResult
compTime 返回值 — 时间差对象
| 字段 | 类型 | 说明 |
|---|---|---|
| greater | boolean | target 是否大于 reference |
| years | number | 年差值 |
| months | number | 月差值 |
| days | number | 天差值 |
| hours | number | 小时差值 |
| minutes | number | 分钟差值 |
| seconds | number | 秒差值 |
| text | string | 人类可读的差值文本(如 "大于1年2月3天"),不大于时为空字符串 |
📋 类型定义原文
interface CompTimeResult {
}func compTime
declare function compTime(reference: string | number, target: string | number): CompTimeResult
时间日期比较 — 判断 target 时间是否大于 reference 时间
@param reference 基准时间,支持特殊关键字或时间值:
-
-
-
-
-
- 也可直接传入 ISO8601 字符串 / 时间戳 / DATETIME 字符串
@param target 要比较的目标时间,支持:
- ISO8601 字符串:
- 时间戳 (毫秒或秒):
- DATETIME 字符串:
@returns 时间差对象;target <= reference 或解析失败时
@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);
}
```
@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 是否成功
@param packageName 包名
@returns 是否成功
app.launchPackage()
app.launchPackage(packageName: string): boolean
启动应用 (launch 的别名)
app.getPackageName()
app.getPackageName(appName: string): string | null
通过应用名获取包名
@returns 包名或 null
@returns 包名或 null
app.getAppName()
app.getAppName(packageName: string): string | null
通过包名获取应用名
@returns 应用名或 null
@returns 应用名或 null
app.getPackageInfo()
app.getPackageInfo(packageName: string): PackageInfo
获取应用详细信息
app.getInstalledPackages()
app.getInstalledPackages(): InstalledPackage[]
获取已安装应用列表
app.openAppSetting()
app.openAppSetting(packageName: string): boolean
打开应用系统设置页
@returns 是否成功
@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 是否成功
@returns 是否成功
app.sendEmail()
app.sendEmail(options: SendEmailOptions): boolean
发送邮件
@returns 是否成功
@returns 是否成功
app.startActivity()
app.startActivity(name: string): boolean
启动特定界面
@param name 组件名 "pkg/cls"(如 "com.tencent.mm/.ui.LauncherUI");
特殊值 'console' 拉起本应用到前台(Android)
@returns 是否成功(不支持的平台/模式返回 false)
@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
不支持的平台/模式(如 Windows ADB)抛 Error
app.bindWindow()
app.bindWindow(windowId: string): WindowInfo | null
绑定当前线程到指定窗口:后续 aiTxt/click/dumpUi 等操作自动适配窗口
(region 基于窗口 bounds 裁剪)
@param windowId 窗口 id,从 app.windows() 获取
@returns 窗口上下文;窗口不存在时返回 null(恢复全屏模式)
(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 是否成功
时进入低频轮询等待)。需在 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 是否成功
使用 WakeLock 实现系统级屏幕唤醒,即使 App 在后台或屏幕已熄灭也能保持常亮。
适用于定时任务执行前唤醒屏幕。
@param timeout 超时毫秒,0 或省略 = 一直保持
@returns 是否成功
device.keepScreenDim()
device.keepScreenDim(timeout?: number): boolean
保持屏幕常亮(允许变暗以省电)
适用于定时任务唤醒屏幕操作,不需要用户观看屏幕的场景。
@param timeout 超时毫秒,0 或省略 = 一直保持
适用于定时任务唤醒屏幕操作,不需要用户观看屏幕的场景。
@param timeout 超时毫秒,0 或省略 = 一直保持
device.cancelKeepingAwake()
device.cancelKeepingAwake(): boolean
取消屏幕常亮(释放 WakeLock)
device.wakeUp()
device.wakeUp(): boolean
唤醒设备 CPU 和屏幕
使用 ACQUIRE_CAUSES_WAKEUP + FULL_WAKE_LOCK 唤醒屏幕。
适用于定时任务执行前唤醒屏幕,避免锁屏导致任务无法执行。
使用 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+ 需用户手动授予
亮度设置等系统设置修改需要此权限,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
@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
是否横屏
| 常量 | 类型 | 说明 |
|---|---|---|
| width | number | 屏幕宽度 (只读) |
| height | number | 屏幕高度 (只读) |
| brand | string | 设备品牌 (如 "samsung", "Xiaomi") |
| model | string | 设备型号 (如 "SM-G950F") |
| product | string | 产品名 |
| buildId | string | 构建 ID |
| codename | string | 开发代号 |
| fingerprint | string | 设备指纹 (唯一标识) |
| sdkInt | number | Android SDK 版本号 (如 33, 34) |
| battery | number | 电池电量 0~100 (同 getBattery) |
ui 命名空间
namespace ui
ui.showForm()
ui.showForm(schema: FormSchema): { [key: string]: any } | null
显示配置表单 (阻塞等待用户填写并提交)
@param schema 表单 Schema
@returns 用户填写结果,取消时返回 null
@param schema 表单 Schema
@returns 用户填写结果,取消时返回 null
threads 命名空间
namespace threads
threads.start()
threads.start(func: Function): Thread
启动新线程
将函数序列化为代码字符串提交到 Worker Pool 执行。
注意: 仅序列化函数体,外部变量不传递。
@param func 无参函数
@returns 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
@param initialValue 初始值,默认 0
threads.lock()
threads.lock(): Lock
创建可重入锁对象
threads.disposable()
threads.disposable(): Disposable
创建一次性结果传递对象
| 常量 | 类型 | 说明 |
|---|---|---|
| shared | SharedVars | 跨线程内存级共享变量(基于 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_MENU | number | |
| KEYCODE_SOFT_RIGHT | number | |
| KEYCODE_HOME | number | |
| KEYCODE_BACK | number | |
| KEYCODE_CALL | number | |
| KEYCODE_ENDCALL | number | |
| KEYCODE_0 | number | |
| KEYCODE_1 | number | |
| KEYCODE_2 | number | |
| KEYCODE_3 | number | |
| KEYCODE_4 | number | |
| KEYCODE_5 | number | |
| KEYCODE_6 | number | |
| KEYCODE_7 | number | |
| KEYCODE_8 | number | |
| KEYCODE_9 | number | |
| KEYCODE_STAR | number | |
| KEYCODE_POUND | number | |
| KEYCODE_DPAD_UP | number | |
| KEYCODE_DPAD_DOWN | number | |
| KEYCODE_DPAD_LEFT | number | |
| KEYCODE_DPAD_RIGHT | number | |
| KEYCODE_DPAD_CENTER | number | |
| KEYCODE_VOLUME_UP | number | |
| KEYCODE_VOLUME_DOWN | number | |
| KEYCODE_POWER | number | |
| KEYCODE_CAMERA | number | |
| KEYCODE_CLEAR | number | |
| KEYCODE_A | number | |
| KEYCODE_B | number | |
| KEYCODE_C | number | |
| KEYCODE_D | number | |
| KEYCODE_E | number | |
| KEYCODE_F | number | |
| KEYCODE_G | number | |
| KEYCODE_H | number | |
| KEYCODE_I | number | |
| KEYCODE_J | number | |
| KEYCODE_K | number | |
| KEYCODE_L | number | |
| KEYCODE_M | number | |
| KEYCODE_N | number | |
| KEYCODE_O | number | |
| KEYCODE_P | number | |
| KEYCODE_Q | number | |
| KEYCODE_R | number | |
| KEYCODE_S | number | |
| KEYCODE_T | number | |
| KEYCODE_U | number | |
| KEYCODE_V | number | |
| KEYCODE_W | number | |
| KEYCODE_X | number | |
| KEYCODE_Y | number | |
| KEYCODE_Z | number | |
| KEYCODE_COMMA | number | |
| KEYCODE_PERIOD | number | |
| KEYCODE_ALT_LEFT | number | |
| KEYCODE_ALT_RIGHT | number | |
| KEYCODE_SHIFT_LEFT | number | |
| KEYCODE_SHIFT_RIGHT | number | |
| KEYCODE_TAB | number | |
| KEYCODE_SPACE | number | |
| KEYCODE_SYM | number | |
| KEYCODE_EXPLORER | number | |
| KEYCODE_ENVELOPE | number | |
| KEYCODE_ENTER | number | |
| KEYCODE_DEL | number | |
| KEYCODE_GRAVE | number | |
| KEYCODE_MINUS | number | |
| KEYCODE_EQUALS | number | |
| KEYCODE_LEFT_BRACKET | number | |
| KEYCODE_RIGHT_BRACKET | number | |
| KEYCODE_BACKSLASH | number | |
| KEYCODE_SEMICOLON | number | |
| KEYCODE_APOSTROPHE | number | |
| KEYCODE_SLASH | number | |
| KEYCODE_AT | number | |
| KEYCODE_NUM | number | |
| KEYCODE_HEADSETHOOK | number | |
| KEYCODE_FOCUS | number | |
| KEYCODE_PLUS | number | |
| KEYCODE_NOTIFICATION | number | |
| KEYCODE_SEARCH | number |
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]
```
底层使用 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 编码字符串
@param str 要编码的字符串
@returns base64 编码字符串
base64.decode()
base64.decode(b64: string): string
将 base64 字符串解码为原始字符串
@param b64 base64 编码字符串
@returns 解码后的原始字符串
@param b64 base64 编码字符串
@returns 解码后的原始字符串
base64.encodeBytes()
base64.encodeBytes(bytes: number[]): string
将字节数组编码为 base64
@param bytes 字节数组 (0~255 的整数数组)
@returns base64 编码字符串
@param bytes 字节数组 (0~255 的整数数组)
@returns base64 编码字符串
base64.decodeToBytes()
base64.decodeToBytes(b64: string): number[]
将 base64 字符串解码为字节数组
@param b64 base64 编码字符串
@returns 字节数组 (0~255 的整数数组)
@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 响应体
| 字段 | 类型 | 说明 |
|---|---|---|
| contentType | string | Content-Type |
📋 类型定义原文
interface HttpResponseBody {
string(): string;
bytes(): number[];
json(): any;
close(): void;
}interface HttpResponse
HTTP 响应
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | number | HTTP 状态码 (如 200, 404),失败时为 0 |
| statusMessage | string | 状态消息 (如 "OK", "Not Found") |
| method | string | 请求方法 |
| url | string | 请求 URL |
| headers | HttpHeaders | 响应头 |
| body | HttpResponseBody | 响应体 |
📋 类型定义原文
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
});
```
参考 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
@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,字符串原样发送
@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
@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]: 带类型的文件
@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() 别名。
注意: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
@param options 必须指定 method
http.buildRequest()
http.buildRequest(url: string, options?: HttpRequestOptions): HttpRequestBuilder
构建请求配置对象 (不实际发起请求)
qrcode 命名空间 — 二维码识别
interface QrcodeResult
二维码识别结果
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | 识别出的文本 |
| points | number[][] | 二维码定位点数组 [[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...");
```
底层使用 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 支持)。
支持的路径前缀:
@param imagePath 图片路径
@returns 识别结果,未识别到二维码时返回 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 编码的图片识别二维码
自动去除
@param base64Str 图片的 base64 字符串 (可包含或不含 data:image 前缀)
@returns 识别结果,未识别到二维码时返回 null
自动去除
data:image/...;base64, 前缀。@param base64Str 图片的 base64 字符串 (可包含或不含 data:image 前缀)
@returns 识别结果,未识别到二维码时返回 null
engine 命名空间 — 脚本引擎管理
interface EngineScriptResult
engine.script() 单任务返回值
| 字段 | 类型 | 说明 |
|---|---|---|
| ok | boolean | 是否成功加入执行计划 |
| name | string | 脚本名称 |
| engine_name | string | 引擎名(单任务=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() 返回值
| 字段 | 类型 | 说明 |
|---|---|---|
| ok | boolean | 是否成功停止 |
| error? | string | 错误信息 (ok=false 时存在) |
📋 类型定义原文
interface EngineStopResult {
}interface EngineStopAllResult
engine.stopAll() 返回值
| 字段 | 类型 | 说明 |
|---|---|---|
| ok | boolean | 是否成功 |
| count | number | 停止的脚本数量 |
| skipped? | number | 跳过的不可停止脚本数量 (unStoppable=true) |
📋 类型定义原文
interface EngineStopAllResult {
}namespace engine
脚本引擎管理模块
用于在 JS 层管理多个脚本的启动、停止。支持多任务定时和调用参数传递。
脚本来源:
- 本地文件: 如
- 远程 URL: 如
启动时间
- 省略/null: 立即启动
- 数字: 视为时间戳 (>1e12 为毫秒,否则视为秒)
- 字符串: ISO8601 (
- 数组: 多任务定时,每个元素对应一个触发时间
调用参数
- 通过
- 单任务: 任意类型 (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();
```
用于在 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 是否设置成功
@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 是否开启成功
周期采样屏幕指纹,连续 samples 次汉明距离低于阈值判定停滞。
注意:Windows ADB 模式下屏幕指纹采样不可用,Layer2 实际不生效。
@param opt { interval?: number(秒,默认30), samples?: number(默认5), hamming?: number(百分比,默认2) }
@returns 是否开启成功
engine.clearStuckWatch()
engine.clearStuckWatch(): boolean
关闭屏幕停滞检测(Layer2)
@returns 是否关闭成功
@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 日志,不停止脚本。
回调收到 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 停止结果
@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 脚本列表
@returns 脚本列表
engine.stopAll()
engine.stopAll(): EngineStopAllResult
停止所有正在运行的脚本
@returns 停止结果 (含停止数量)
@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(
2. 绝对路径(以
3. 相对路径 → 先从
@param path 模块路径
- 本地路径: '/sdcard/lib/utils.js' 或 './utils.js'(相对当前脚本目录)
- 脚本名: 'test_fun.js'(自动从
- 网络路径: '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');
支持 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 等)。
含
/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 单个采集字段配置
| 字段 | 类型 | 说明 |
|---|---|---|
| key | string | 字段键名(存储与返回 data 中的键) |
| label? | string | 采集时的界面提示文本(rect: true 时显示) |
| rect? | boolean | true 时动态采集矩形区域(配合 count 生成多组) |
| region? | RegionExpr | 固定采集区域(RegionExpr),与 rect 二选一 |
📋 类型定义原文
interface DataCollectionField {
}interface CollectDataOptions
collectData 选项
| 字段 | 类型 | 说明 |
|---|---|---|
| trigger | string | 触发文本(支持匹配前缀语法: =, ~=, ^=, $=, re=) |
| triggerRegion? | RegionExpr | 触发文本所在区域(RegionExpr) |
| collections | DataCollectionField[] | 采集区域配置数组(必填,非空) |
| 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 单条采集结果
| 字段 | 类型 | 说明 |
|---|---|---|
| collected | boolean | 采集是否成功 |
| id | string | 唯一键值(idKey 字段的值) |
| data | { [key: string]: any } | 采集到的完整数据对象(采集字段 + 自定义字段) |
| total | number | 当前数据集总数 |
📋 类型定义原文
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
});
```
当屏幕特定区域出现触发文本时,自动采集多个区域的文本数据并保存到 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 所有匹配数据(键值对对象)
@param dataKey 数据集名称
@param options 可选: filter 按字段筛选;prefix 按 idKey 前缀筛选
@returns 所有匹配数据(键值对对象)
func getDataCount
declare function getDataCount(dataKey: string): number
获取数据集总数
@param dataKey 数据集名称
@returns 数据条数
@param dataKey 数据集名称
@returns 数据条数
func clearData
declare function clearData(dataKey: string): true
清空数据集
@param dataKey 数据集名称
@returns true
@param dataKey 数据集名称
@returns true
func deleteData
declare function deleteData(dataKey: string, id: string): true
删除数据集中的单条数据
@param dataKey 数据集名称
@param id 条目的唯一键值(idKey 字段的值)
@returns 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
@param dataKey 数据集名称
@param filePath 可选导出路径,不传时自动生成
@returns 导出文件路径,失败时为 null
func importData
declare function importData(dataKey: string, filePath: string): number
从 JSON 文件导入数据到数据集
@param dataKey 数据集名称
@param filePath JSON 文件路径
@returns 导入条数,失败时为 0
@param dataKey 数据集名称
@param filePath JSON 文件路径
@returns 导入条数,失败时为 0
func listDataSets
declare function listDataSets(): string[]
列出所有数据集名称
@returns 数据集名称数组
@returns 数据集名称数组
可视化核对 (show*)
func showRect
declare function showRect(key?: string): boolean
在透明 Activity 上可视化展示已保存的矩形区域,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
func showPosition
declare function showPosition(key?: string): boolean
在透明 Activity 上可视化展示已保存的坐标点(圆圈),点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
func showColor
declare function showColor(key?: string): boolean
在透明 Activity 上可视化展示已保存的取色点,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
func showSwipe
declare function showSwipe(key?: string): boolean
在透明 Activity 上可视化展示已保存的滑动轨迹,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
func showJoystick
declare function showJoystick(key?: string): boolean
在透明 Activity 上可视化展示已保存的摇杆区域,点击屏幕任意位置关闭
@param key 可选键名,不传时显示全部
@returns 是否有可显示的内容
@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() 时限定区域
```
@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, ...}
@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 入队后的队列长度
参数同 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
@returns true
func resumeJoystick
declare function resumeJoystick(): number
恢复摇杆队列执行,worker 继续从队列取任务
@returns 当前队列长度
@returns 当前队列长度
func clearJoystickQueue
declare function clearJoystickQueue(): number
清空摇杆队列(当前正在执行的摇杆操作不受影响,会自然完成)
@returns 清空前的队列长度
@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() 停止
执行推杆;队列为空时 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);
});
```
@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(失败)
@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 表示失败或无配置可导入)
@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');" });
```
@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);"
});