屏幕截图 — images.captureScreen 同步与异步截图

前置条件

截图功能需要 屏幕捕获权限。首次调用截图方法时，Android 系统会弹出授权窗口：

"允许 AutoJs6 截取屏幕上显示的所有内容吗？"

点击「立即开始」或「允许」即可授权。授权后在当前 AutoJs6 会话内持续有效。

避免权限弹窗遮挡

v6.7 新增「屏幕捕获权限申请延迟」设置项：设置 → 无障碍 → 屏幕捕获权限申请延迟

设一个较大的值（如 500ms），可以让脚本先完成必要的界面操作再弹出权限窗口，避免覆盖目标界面。

基本截图

保存到文件

// 截取当前屏幕并保存为 PNG 文件
images.captureScreen("/sdcard/screenshot.png");

// 自动添加时间戳文件名
let filename = "/sdcard/screenshots/auto_" + Date.now() + ".png";
images.captureScreen(filename);

返回 Image 对象

// 截图并返回 Image 对象（后续可用于找色找图）
let screen = images.captureScreen();

// Image 对象属性
console.log("宽度: " + screen.width);
console.log("高度: " + screen.height);
console.log("格式: " + screen.format); // png, jpeg, webp

全局函数形式

截图也可以作为全局函数调用：

// 全局函数（等同 images.captureScreen）
let screen = captureScreen();
captureScreen("/sdcard/test.png");

异步截图

v6.7 新增异步方法，避免截图时阻塞脚本执行：

// 异步获取网络图片（v6.7）
let imgPromise = images.loadAsync("https://example.com/image.png");
imgPromise.then(img => {
    console.log("图片宽高: " + img.width + "x" + img.height);
});

// 也可以用 await（需测试 Rhino Promise 支持）
// let img = await images.loadAsync("https://...");

Image 对象操作

保存图片

let screen = images.captureScreen();

// 保存到文件
images.save(screen, "/sdcard/latest.png");

// 保存并指定格式
images.save(screen, "/sdcard/latest.jpg", "jpg", 80); // 质量 80

区域剪裁

let screen = images.captureScreen();

// 剪裁指定区域
let cropped = images.clip(screen, 100, 200, 500, 300);
// 参数: image, x, y, width, height

images.save(cropped, "/sdcard/cropped.png");

释放资源

Image 对象占用内存，用完后记得释放：

let screen = images.captureScreen();
// 使用 screen 做找色找图...
screen.recycle(); // 释放内存

// 或用 recycle 全局函数
recycle(screen);

AutoJs6 文档特别提醒：Image 对象用完后必须 recycle，否则大量截图会导致内存不足被系统回收。

区域连续截图

某些场景需要对屏幕变化进行监控：

// 每秒截图一次，持续 10 秒
for (let i = 0; i < 10; i++) {
    let path = `/sdcard/monitor_${i}.png`;
    images.captureScreen(path);
    console.log("已截取: " + path);
    sleep(1000);
}

截图与窗口变化

有时需要等待某个界面出现后再截图：

// 等待 Activity 出现
if (waitForActivity("com.target.app/.MainActivity", 5000)) {
    // Activity 加载完了再截图
    let screen = images.captureScreen();
    // ...
}

常见问题

截图返回 null

let screen = images.captureScreen();
if (!screen) {
    // 可能原因：
    // 1. 屏幕捕获权限被撤销
    // 2. 当前界面不允许截图（部分安全应用）
    // 3. 应用在后台
    console.error("截图失败");
}

截图是黑屏

部分应用（银行类、支付类）使用 FLAG_SECURE 禁止系统截图，AutoJs6 也会受到影响。这种情况无法绕过，需要换其他方案（如控件选择器或坐标点击）。

Android 版本差异

关于区域截图

AutoJs6 不直接支持区域截图（如只截某个控件的范围）。推荐做法：

// 先全屏截图
let full = images.captureScreen();

// 再剪裁出需要的区域
let cropped = images.clip(full, x, y, w, h);

full.recycle();
images.save(cropped, "region.png");
cropped.recycle();