在自动化脚本中如何使用图色操作？

一、图色操作概述与适用场景

在安卓自动化脚本开发中，元素定位分为无障碍控件识别、OCR 文字识别、图色视觉识别三大方案。无障碍控件识别依赖应用 UI 树，若目标应用加固、限制无障碍服务，便会出现定位失效；OCR 仅针对文字区域；图色操作基于屏幕像素图像分析，不依赖应用底层控件结构，依靠截图、颜色匹配、模板图像匹配完成界面元素定位，是兼容性最强的兜底定位方案，广泛应用于游戏自动化、封闭类 APP、界面无标准控件的场景。冰狐智能辅助提供一套完整原生 JS 图色 API，覆盖截屏权限申请、图像采集、单点 / 多点取色、单色 / 多点找色、图像模板匹配、图像预处理、位图读写裁剪等全链路能力，所有接口统一依托截屏权限运行，本文梳理完整开发流程、API 使用规范、代码示例与工程优化方案。

二、图色操作前置权限与基础流程

（一）核心前置：截屏权限申请

冰狐所有图色接口（screenShot、findColor、getScreenColor、findImage等）执行前，必须调用requestScreenShot申请截屏权限，否则全部接口失效。

1. 调用时机：建议放置在脚本main函数最开头，脚本启动优先申请权限；
2. 运行环境要求：冰狐 App 处于前台运行，后台休眠易出现黑屏、权限弹窗识别失败；
3. 参数说明：
   • confirmPermissionTag：权限弹窗确认按钮文本，支持|分割多文本自动点击，默认立即开始|允许；
   • retryCount：自动点击重试次数，默认 5 次；
   • usePreBitmap：屏幕静止时复用上次截图，减少重复截屏性能损耗，默认开启true。

基础权限申请示例：

function main() {
    // 脚本首行申请截屏权限，自动识别弹窗确认按钮
    requestScreenShot({
        confirmPermissionTag: "允许|立即开启",
        retryCount: 8,
        usePreBitmap: true
    });
    sleep(1000); // 等待权限加载完成
    // 后续所有图色操作代码写在此处
}

1. 权限释放：脚本结束或长期无需图色时，调用stopScreenShot停止截屏服务，释放系统资源；再次使用图色功能需重新申请权限。

stopScreenShot();

（二）图色标准执行流程

完整图色自动化标准逻辑分为五步：

1. 初始化：申请截屏权限；
2. 图像采集：截屏获取屏幕位图 / 图片文件；
3. 视觉分析：取色、找色、找图、多点比对；
4. 逻辑判断：根据识别坐标执行点击、滑动等操作；
5. 资源回收：位图手动释放、停止截屏服务，避免内存泄漏。

三、基础截屏与位图管理 API 详解

截屏是所有图色操作的数据来源，冰狐提供两种截屏模式：返回位图对象、直接保存图片文件，二者资源管理规则存在明显区别。

1. screenShot 截屏接口

参数options包含文件名、截图区域、图片质量、回调函数等配置：

• fileName为空：返回Bitmap位图对象，使用完毕必须执行bitmap.recycle()释放内存，否则长期运行脚本会内存溢出；
• fileName填写路径：自动将截图保存至sdcard/aznfz目录，返回文件完整路径，无需手动回收；
• region截图区域：支持像素值（大于 1）与屏幕比例（0~1），限定区域可大幅提升识别速度；
• imageType：1=PNG 无损，2=JPG 压缩，配合quality调整画质。

示例 1：保存截图至本地文件

function main() {
    requestScreenShot();
    // 截取屏幕上半部分，保存为jpg图片，质量80
    let imgPath = screenShot({
        fileName: "task_screen.jpg",
        region: [0, 0, 1, 0.5],
        imageType: 2,
        quality: 80
    });
    console.log("截图保存路径：", imgPath);
}

示例 2：获取位图进行后续图像处理（必须回收）

function main() {
    requestScreenShot();
    let bmp = screenShot();
    // 基于位图取色、找色等操作
    let color = getScreenColor([200, 300], bmp);
    console.log("目标点颜色值：", color);
    // 关键：释放位图资源
    bmp.recycle();
}

2. 位图处理工具函数

针对位图的二次加工，冰狐提供灰度化、二值化、裁剪、读写、字节转换接口，用于提升低对比度界面识别准确率：

1. image2Gray(bitmap)：图像灰度化，消除色彩干扰，适合浅色文字识别；
2. imageThreshold(bitmap, threshold)：二值化，阈值 0-255，分离前景与背景；
3. bitmapClip(bitmap, left, top, width, height)：裁剪局部图像，缩小识别范围；
4. readImage(path)：读取本地模板图片，用于findImage模板匹配；
5. writeImage(bitmap, path)：将处理后的位图保存到本地相册。

灰度化 + 二值化预处理完整示例：

function main() {
    requestScreenShot();
    let bmp = screenShot();
    // 灰度化
    let grayBmp = image2Gray(bmp);
    // 二值化，阈值120
    let binaryBmp = imageThreshold(grayBmp, 120);
    // 保存处理后的图片
    writeImage(binaryBmp, "/sdcard/gray_binary.png");
    // 分层释放位图
    binaryBmp.recycle();
    grayBmp.recycle();
    bmp.recycle();
}

四、颜色识别系列 API（核心定位工具）

颜色识别是图色脚本最常用能力，分为单点取色、单点比对、单点找色、多点批量找色四类接口，适配不同业务场景。

1. getScreenColor 获取屏幕像素颜色

支持单点、多点批量取色，返回 ARGB 整型颜色值，黑色0xFF000000、透明0x00000000，可直接用于颜色比对。

function main() {
    requestScreenShot();
    // 单点取色
    let singleColor = getScreenColor([350, 600]);
    // 多点同时取色
    let multiColorArr = getScreenColor([[100, 200], [500, 800], [720, 1200]]);
    console.log("单点色值：", singleColor, "多点色组：", multiColorArr);
}

2. compareColors 多点颜色比对

固定坐标校验颜色，仅返回布尔值，适合已知控件坐标、固定分辨率设备，判断按钮、弹窗是否加载完成；参数传入多组[x,y,目标色]，全部匹配才返回true。

function main() {
    requestScreenShot();
    // 校验弹窗两个关键点颜色，相似度0.95
    let isPopupShow = compareColors([
        [420, 310, "#FFFFFF"],
        [450, 360, "#2266EE"]
    ], {similarity: 0.95});
    if (isPopupShow) {
        console.log("弹窗已加载");
    }
}

3. findColor 单颜色全局 / 区域搜索

未知坐标下查找目标颜色，支持邻点颜色校验neighbor、颜色相似度、限定搜索区域，适配多分辨率设备；neighbor参数可添加周边特征色，大幅降低误识别概率，是脚本稳定性优化关键参数。核心配置说明：

• similarity：相似度 0~1，数值越高匹配越严格，浅色界面推荐 0.9，深色游戏界面推荐 0.85；
• findAll：true返回所有匹配坐标，false仅返回第一个匹配点；
• region：限定查找区域，避免全屏扫描，提升运行速度。

实战示例：查找蓝色按钮，附带周边特征色防误判

function main() {
    requestScreenShot();
    // 查找#2266EE按钮，附带上下左右邻点特征色
    let targetPoints = findColor("#2266EE", {
        similarity: 0.9,
        findAll: false,
        region: [0, 800, 1, 1], // 仅屏幕底部区域查找
        neighbor: [
            [0, -5, "#FFFFFF"],
            [0, 5, "#EEEEEE"],
            [-5, 0, "#2266EE"],
            [5, 0, "#2266EE"]
        ]
    });
    if (targetPoints.length > 0) {
        // 点击找到的按钮
        click(targetPoints[0].x, targetPoints[0].y);
    }
}

4. findColors 多类型颜色批量查找

同时检索多种不同颜色，通过category、value区分目标类型，适合界面存在多种按钮、图标同时识别的场景，一次性返回全部匹配结果，减少多次截屏开销。

function main() {
    requestScreenShot();
    let result = findColors([
        {color:"#FF3333", category:"关闭按钮", value:1, neighbor:[[0,3,"#FF5555"]]},
        {color:"#33AA33", category:"确认按钮", value:2, neighbor:[[0,3,"#55BB55"]]}
    ], {similarity:0.9});
    for(let item of result) {
        console.log("识别到：", item.category, "坐标", item.x, item.y);
    }
}

五、模板图像匹配 findImage 找图接口

当界面元素是复杂图标、特殊弹窗、游戏道具时，单纯颜色匹配易受渐变、光影干扰，可使用模板图片匹配findImage，提前截取目标图标保存为模板文件，脚本运行时全局匹配。

1. 模板路径支持三种格式：本地绝对路径、相对存储路径、asset:xxx.png打包内置资源；
2. scale缩放适配：开启后自动缩放模板 0.8~1.2 倍，兼容不同分辨率手机；
3. threshold匹配阈值，默认 0.85，图标复杂可下调至 0.8。

完整找图点击示例：

function main() {
    requestScreenShot();
    // 读取本地模板图片，查找右上角关闭图标
    let targetRegion = findImage("/sdcard/close_icon.png", {
        region: [0.8, 0, 1, 0.15],
        threshold: 0.88,
        scale: {useScale:true, startScale:0.8, endScale:1.2, scaleStep:0.1}
    });
    // 判断是否找到模板
    if(targetRegion.x > 0) {
        click(targetRegion.x + targetRegion.width/2, targetRegion.y + targetRegion.height/2);
    } else {
        console.log("未找到关闭图标");
    }
}

六、图色脚本开发规范与性能优化方案

（一）内存泄漏规避规范

1. 凡通过screenShot()、readImage()、image2Gray()等获取的Bitmap对象，使用结束必须调用.recycle()释放；循环内频繁截屏时，每次循环结束及时回收，不可堆积位图；
2. 脚本异常退出、分支判断时，务必补充位图回收逻辑，避免长期运行 APP 卡顿、闪退。

（二）运行速度优化核心技巧

1. 限定查找区域：所有findColor、findImage、compareColors必须配置region，缩小扫描范围，全屏扫描耗时会提升 3~10 倍；
2. 合理复用截图：开启usePreBitmap:true，页面无变化时复用上次位图，减少截屏系统调用；
3. 控制相似度阈值：非高精度场景无需设置 1.0，0.85~0.9 区间平衡识别准确率与运行速度；
4. 减少循环截屏频次：单次循环内仅截屏一次，复用同一张位图完成多次取色、找色，避免重复截图。

（三）稳定性提升方案

1. 邻点颜色neighbor必填：单一纯色极易被界面其他色块误匹配，增加 2~4 组周边特征色可大幅降低误识别；
2. 权限前置 + 等待延时：申请截屏后增加sleep(800~1500)，等待系统渲染完成再执行识别；
3. 混合定位兜底：优先无障碍控件识别，识别失败后再启用图色作为备用方案，兼顾效率与兼容性；
4. 远程图色工具辅助取色：登录冰狐网页端「移动端 - 我的设备 - 远程控制」，鼠标直接拾取界面颜色、自动生成找色代码，手动输入色值易出现偏差。

（四）常见故障排查

1. 所有图色接口无返回结果：未调用requestScreenShot、冰狐 App 后台休眠、系统弹窗遮挡屏幕；
2. 频繁黑屏、截屏失败：关闭手机省电策略、锁定冰狐后台，保持前台运行；
3. 识别坐标偏移：未开启 scale 缩放适配、模板图片尺寸与界面图标差异过大；
4. 脚本运行一段时间闪退：位图未执行 recycle，内存持续占用溢出。

七、完整综合实战脚本（自动弹窗关闭逻辑）

整合权限申请、截屏、找色、找图、资源回收全流程，可直接用于弹窗自动关闭场景：

function main() {
    // 1. 初始化截屏权限
    requestScreenShot({confirmPermissionTag:"允许|立即开始", retryCount:6});
    sleep(1000);
    let loopMax = 10;
    for(let i=0; i<loopMax; i++) {
        let bmp = screenShot();
        // 方式1：颜色匹配查找关闭按钮
        let closePoints = findColor("#FF4444", {
            similarity:0.9,
            region:[0.82, 0.02, 0.98, 0.12],
            neighbor:[[3,0,"#FFFFFF"],[0,3,"#FF6666"]],
            bitmap:bmp
        });
        if(closePoints.length > 0) {
            click(closePoints[0].x, closePoints[0].y);
            console.log("通过颜色找到关闭按钮，执行点击");
            bmp.recycle();
            sleep(1200);
            continue;
        }
        // 方式2：模板图片匹配兜底
        let closeImg = findImage("/sdcard/close_template.png", {
            region:[0.8,0,1,0.15],
            threshold:0.85,
            bitmap:bmp
        });
        if(closeImg.x > 0) {
            click(closeImg.x + closeImg.width/2, closeImg.y + closeImg.height/2);
            console.log("通过模板图片找到关闭弹窗");
            bmp.recycle();
            sleep(1200);
            continue;
        }
        // 无弹窗，释放位图退出循环
        bmp.recycle();
        console.log("未检测到弹窗，结束循环");
        break;
    }
    // 停止截屏服务，释放系统权限
    stopScreenShot();
}

八、总结

冰狐智能辅助的图色操作体系完整覆盖图像采集、像素分析、模板匹配、图像预处理全链路，核心逻辑围绕截屏权限先行、位图及时回收、限定识别区域、增加邻点特征校验四大原则开发。在无障碍控件识别失效的场景下，图色方案能够跨分辨率、跨应用实现界面自动化定位。开发过程中，优先利用网页端远程图色工具自动生成色值与代码，配合灰度化、二值化预处理提升低对比度界面识别效果；同时做好内存管理与区域限制优化，平衡脚本运行速度、识别准确率与长期运行稳定性。图色能力与无障碍、OCR 结合使用，可搭建兼容性、鲁棒性更强的移动端自动化脚本体系。