小木自动点击器 JS 接口文档

概述

小木自动点击器 JS 接口提供了一套用于自动化操作 Android 设备的 JavaScript API。通过 window.mumudroid 对象，您可以实现屏幕点击、滑动、应用启动以及基于文本识别的自动化任务。

⚠️ 安全警告：运行不受信任的脚本可能会泄露您的个人隐私或导致账号风险。请务必只运行来源可靠、您自己编写或完全理解的代码。

坐标系统说明

所有涉及坐标的接口都支持两种定位方式：

相对比例定位（推荐）：坐标值在 0-1 之间，表示屏幕的相对位置（如 0.5 表示屏幕正中心）。这种方式可完美适配不同分辨率的设备。
绝对坐标定位：坐标值大于 1 时生效，表示屏幕的绝对像素位置（如 500 表示第 500 个像素点）。

1. 标准脚本结构模板

为了保证脚本能够异步执行（如使用 sleep 延迟和持续循环），建议使用 IIFE（立即调用的函数表达式） 结合 async/await 作为脚本的基础骨架：

(function() {
  'use strict';
  
  // 定义异步主循环函数
  async function loop() {
    // 1. 注册全局回调（如文本查找结果回调）
    // window.onFindTextResult = ...

    // 2. 开启无限循环监控
    while (true) {
      // 必须添加 sleep 防止死循环卡死主线程
      await sleep(1000); 
      
      // 在此处编写您的自动化逻辑
      console.log("脚本运行中...");
    }
  }
  
  // 启动脚本
  loop();
})();

2. 核心事件回调

window.onFindTextResult

功能说明：这是一个全局回调函数，用于接收 find_text() 方法的异步查找结果。当底层引擎完成屏幕文本识别后，会自动触发此函数。

参数说明：

参数	类型	说明
result	boolean	是否成功找到目标文本（`true` 为找到，`false` 为未找到）
text	string	实际匹配到的具体文本内容
centerX	number	匹配文本在屏幕上的中心点 X 坐标（可直接传给 `click` 函数）
centerY	number	匹配文本在屏幕上的中心点 Y 坐标（可直接传给 `click` 函数）

使用示例：

window.onFindTextResult = function(result, text, centerX, centerY) {
    if (result) {
        console.log(`找到文本: ${text}，准备点击中心点: ${centerX}, ${centerY}`);
        // 自动点击找到的文本
        click(centerX, centerY);
    } else {
        console.log("当前屏幕未找到目标文本");
    }
};

3. API 接口详细说明

3.1 sleep(ms)

功能说明：异步暂停脚本执行指定的毫秒数，用于等待页面加载或动画结束。

参数：ms (number) - 暂停的毫秒数。
示例：await sleep(2000); // 暂停 2 秒

3.2 click(x, y, [duration])

功能说明：点击屏幕指定坐标。支持普通点击和长按。

参数：
- x, y (number): 目标坐标。
- duration (number, 可选): 按住时长（毫秒）。不传则由系统处理默认点击时长。
示例：click(0.5, 0.5); // 点击屏幕中心

3.3 clickBack() / clickHome()

功能说明：模拟按下 Android 系统的「返回键」或「Home（桌面）键」。

示例：clickBack();

3.4 swipe(x1, y1, x2, y2, [duration])

功能说明：执行屏幕滑动操作。

参数：
- x1, y1 (number, 默认 0.5, 0.8): 起始点坐标。
- x2, y2 (number, 默认 0.5, 0.2): 终点坐标。
- duration (number, 可选): 滑动时长（毫秒）。不传则生成 300~500ms 随机时长。
示例：swipe(0.5, 0.8, 0.5, 0.2); // 向上滑动屏幕

3.5 find_text(text, [x1, y1, x2, y2])

功能说明：在屏幕（或指定区域）内异步查找文本。

💡 高级特性：支持使用英文逗号 , 分隔多个关键字，只要屏幕中出现其中任意一个关键词即视为匹配成功。

参数：
- text (string): 要查找的文本，支持多关键字（如 'skip,跳过,跳過'）。
- x1, y1, x2, y2 (number, 可选): 限定查找的矩形区域（相对比例 0~1），默认为全屏（0,0,1,1）。
示例：find_text('确定,确认,OK');

3.6 openApp(packageName)

功能说明：通过包名启动应用。

示例：openApp('com.tencent.mm'); // 启动微信

3.7 openScheme(schemeUrl)

功能说明：通过 DeepLink / Scheme 协议拉起应用或跳转特定页面。

示例：openScheme('taobao://...');

4. 实战示例：自动跳过广告/开屏页

以下是一个完整的实战脚本，常用于自动识别并点击各类 App 的“跳过”按钮。它结合了标准模板、多关键字查找以及异步回调机制。

(function() {
  'use strict';
  
  // ⚠️ Warning: Running untrusted scripts can compromise your personal privacy. 
  // Only run code from sources you trust.

  async function loop() {
    // 1. 注册文本查找结果回调
    window.onFindTextResult = function(result, text, centerX, centerY) {
        console.log("onFindTextResult: " + result + " " + text + " " + centerX + " " + centerY);
        
        // 2. 如果找到了目标文本，直接点击其中心坐标
        if (result) {
          click(centerX, centerY);
          console.log("成功点击跳过按钮！");
        }
    };

    // 3. 开启无限循环监控
    while (true) {
       // 每隔 1 秒扫描一次屏幕（防止过度消耗性能）
       await sleep(1000);
       
       console.log("正在扫描屏幕...");
       
       // 4. 发起文本查找（支持逗号分隔的多个中英文关键字）
       // 系统会在后台识别屏幕文字，完成后触发 onFindTextResult
       find_text('skip,跳过,跳過,关闭广告');
    }
  }
  
  // 启动主循环
  loop();
})();

示例逻辑解析：

防卡死机制：while(true) 中必须包含 await sleep(1000)，否则会导致 JS 引擎死锁，应用卡死。
异步解耦：find_text 只是发起一个查找请求，真正的处理逻辑写在 window.onFindTextResult 中。这种设计避免了阻塞主线程。
精准点击：回调函数返回的 centerX 和 centerY 是引擎计算出的文本几何中心点，直接传给 click() 可以确保最高点击成功率。
多语言/多场景兼容：'skip,跳过,跳過' 利用了接口支持逗号分隔的特性，一次性覆盖了英文、简体、繁体三种常见的跳过按钮文案。

5. 注意事项与最佳实践

异步回调意识：记住 find_text() 不是同步返回结果的。不要在 find_text() 之后立即写 if 判断，必须依赖 window.onFindTextResult 回调。
合理使用 Sleep：在 click、swipe 或 openApp 之后，建议加上 await sleep(1000~3000)，给系统足够的时间渲染下一个页面，否则下一步的 find_text 可能会抓取到旧页面的内容。
区域查找优化性能：如果明确知道“跳过”按钮只出现在屏幕右上角，可以使用 find_text('跳过', 0.7, 0, 1, 0.2) 限定查找区域，这将大幅提升 OCR 识别速度并降低 CPU 占用。
环境静默保护：所有 API 内部均包含 if (!window.mumudroid) return; 校验。如果在普通浏览器环境中测试脚本，接口不会报错，但也不会执行实际操作。