如何优雅的使用悬浮日志调试自动化脚本？

我们在编写 Android 自动化脚本时，调试效率直接决定开发速度 。传统调试依赖网页端在线 Log、Toast 弹窗或 ADB 日志，要么需要电脑配合、要么信息易丢失、要么遮挡界面操作，复杂流程与多分支逻辑下，定位问题非常耗时。而平台内置的Float 悬浮日志组件 ，无需电脑、不占后台、屏幕实时可视化输出，是本地调试、现场排查、流程监控的首选工具。本文系统讲解悬浮日志的核心 API、配置规范、使用场景，帮你快速掌握用 Float 高效调试自动化脚本的全流程。

一、为什么优先用 Float 悬浮日志调试

冰狐智能辅助脚本基于 JS 运行，调试场景有很强的移动端特性：脱离电脑、实时看运行状态、不干扰界面操作、信息可留存。Float 悬浮日志完美匹配这些需求，优势非常突出：

1. 屏幕实时可见：日志悬浮在所有界面上层，脚本运行时关键信息一目了然，不用切后台、不连电脑；
2. 信息不丢失：支持日志累积、清空、显示 / 隐藏，历史运行轨迹完整保留；
3. 样式高度自定义：颜色、大小、位置、背景、时间戳均可配置，适配不同界面与阅读习惯；
4. 不干扰操作：可设置不可触摸，不影响自动化点击、滑动等核心动作；
5. API 极简：仅 5 个核心方法，上手零成本，一行代码即可输出日志；
6. 适配所有脚本：兼容智能搭建生成脚本、纯 JS 手写脚本，调试模式 / 发布模式均可用。

对比 Toast、在线 Log、console 日志，Float 的移动端调试体验碾压级领先，是复杂自动化流程必备调试手段。

二、Float 悬浮日志核心 API

Float 组件所有 API 均为全局调用，配置必须放在 main 函数第一行，确保初始化优先于业务逻辑，官方文档明确了 5 个核心方法，参数与用法严格遵循以下规范：

1. 配置方法：Float.config

作用：初始化悬浮框样式、行为、布局，main 函数首行执行。参数：object 类型，必填，支持核心配置项：

配置项	类型	说明
itemStyle	object	日志文本样式，color（颜色，#RRGGBB/#AARRGGBB）、size（字号）
floatStyle	object	悬浮框容器样式，width/height（宽高）、gravity（位置）、backgroundColor（背景色）
gravity	string	对齐方式，支持 left/right/top/bottom/center 等组合，如 left
addTime	boolean	是否自动添加时间戳，true = 显示，false = 隐藏
touchable	boolean	是否可触摸拖动，true = 可拖动，false = 不影响自动化操作

官方示例：

Float.config({
    itemStyle:{color: '#994455', size: 12},
    floatStyle:{height:100, width: 100, gravity: 'left|bottom', backgroundColor:'blue'},
    addTime: true,
    touchable: false
});

2. 日志输出：Float.message

作用：向悬浮框输出文本日志，最常用调试方法。参数：string 类型，必填，即要显示的日志内容。

Float.message('hello');

3. 总开关：Float.enable

作用：全局开启 / 关闭悬浮日志功能，默认开启。参数：boolean 类型，必填，true = 开启，false = 关闭。

Float.enable(false); // 关闭悬浮日志

4. 显隐控制：Float.visible

作用：临时显示 / 隐藏悬浮框，隐藏不清除历史日志，再次显示恢复。参数：boolean 类型，必填，true = 显示，false = 隐藏。

Float.visible(false); // 隐藏悬浮框，日志保留

5. 清空日志：Float.clear

作用：一键清除悬浮框内所有历史日志，无参数。

Float.clear(); // 清空所有日志

这 5 个 API 覆盖配置→输出→控制→清理全流程，记住用法即可满足 99% 调试场景。

三、Float 调试最佳实践

结合冰狐智能辅助脚本运行机制，分享 4 个高频实用技巧，大幅提升调试效率：

1. 固定配置模板

为避免每次重复写配置，推荐固定模板，main 函数首行粘贴即可：

function main(){
    // 固定悬浮日志配置（左下、不可触摸、带时间、白底黑字）
    Float.config({
        itemStyle:{color: '#000000', size: 13},
        floatStyle:{width: 280, height: 320, gravity: 'left|bottom', backgroundColor: '#FFFFFF'},
        addTime: true,
        touchable: false
    });
    // 后续写业务逻辑...
}

• 位置选left|bottom：不遮挡顶部标题与中间操作区；
• touchable:false：不拦截自动化点击、滑动；
• addTime:true：精准定位每步执行时间；
• 高对比度配色：黑字白底，任何界面都清晰可读。

2. 关键节点埋点

自动化脚本核心是步骤流转，在以下节点埋点，快速定位卡死点：

• 脚本启动：输出「脚本开始执行」；
• 页面跳转：输出「进入 XX 页面」；
• 控件查找：输出「查找 ID：xxx」「查找结果：成功 / 失败」；
• 条件分支：输出「判断条件：xxx，执行分支 A」；
• 异常捕获：输出「错误信息：xxx」；
• 脚本结束：输出「脚本执行完成」。

3. 显隐 + 清空组合

• 进入敏感页面（如登录、支付）：Float.visible (false) 隐藏，避免遮挡；
• 页面返回后：Float.visible (true) 恢复，日志不丢；
• 重新运行脚本：开头 Float.clear ()，避免旧日志干扰。

4. 发布前一键关闭

脚本上线时，只需一行 Float.enable (false)，无需删除所有日志代码，下次调试改回 true 即可，维护成本极低。

四、完整 Demo 源码

以下是冰狐智能辅助可直接保存执行的 Demo，模拟「自动打开应用→查找控件→判断分支→执行操作」完整流程，用 Float 全程输出调试信息，你可替换包名、控件 ID 直接用于自己的脚本。

/**
 * 冰狐智能辅助 - 悬浮日志Float调试Demo
 * 功能：模拟自动化流程，用Float输出每一步执行状态
 */
function main() {
    // ========== 1. 悬浮日志初始化（main首行，必须！）==========
    Float.config({
        itemStyle: { color: '#000000', size: 13 }, // 文本：黑色、13号字
        floatStyle: {
            width: 290,
            height: 350,
            gravity: 'left|bottom', // 左下位置
            backgroundColor: '#F5F5F5' // 浅灰背景
        },
        addTime: true, // 开启时间戳
        touchable: false // 不可触摸，不影响自动化
    });

    // 清空历史日志
    Float.clear();
    Float.message("====== 自动化脚本启动 ======");

    // ========== 2. 基础配置 ==========
    const targetPackage = "com.example.testapp"; // 替换为你的目标App包名
    Float.message("目标应用包名：" + targetPackage);

    // ========== 3. 检查应用是否安装 ==========
    Float.message("步骤1：检查目标应用是否安装");
    let isInstalled = app.isInstalled(targetPackage); // 冰狐全局API，判断应用是否安装
    if (isInstalled) {
        Float.message("✅ 应用已安装，准备启动");
    } else {
        Float.message("❌ 应用未安装，脚本终止");
        Float.message("====== 脚本执行失败 ======");
        return; // 退出脚本
    }

    // ========== 4. 启动应用 ==========
    Float.message("步骤2：启动目标应用");
    let launchResult = app.launch(targetPackage); // 冰狐全局API，启动应用
    if (launchResult) {
        Float.message("✅ 应用启动成功，等待页面加载");
    } else {
        Float.message("❌ 应用启动失败");
        Float.message("====== 脚本执行失败 ======");
        return;
    }

    // 等待3秒，模拟页面加载
    Float.message("等待3秒，页面加载中...");
    sleep(3000);

    // ========== 5. 查找控件（模拟）==========
    Float.message("步骤3：查找首页按钮控件");
    let hasButton = true; // 实际替换为控件查找API结果
    if (hasButton) {
        Float.message("✅ 找到目标控件，准备点击");
        // 执行点击操作
        Float.message("执行点击控件操作");
        sleep(1000);
        Float.message("✅ 控件点击成功");
    } else {
        Float.message("❌ 未找到控件，执行备用逻辑");
        // 备用逻辑
        Float.message("执行备用滑动操作");
        sleep(1000);
    }

    // ========== 6. 执行结果判断 ==========
    Float.message("步骤4：校验操作结果");
    let isSuccess = true; // 实际替换为校验逻辑
    if (isSuccess) {
        Float.message("🎉 自动化流程执行完成");
    } else {
        Float.message("⚠️ 流程执行异常，请检查步骤");
    }

    Float.message("====== 脚本运行结束 ======");

    // 发布时打开下面注释，一键关闭悬浮日志
    // Float.enable(false);
}

Demo 使用说明

1. 打开冰狐智能辅助网页端「移动端→移动端脚本」，新建 JS 脚本；
2. 复制全部代码，替换targetPackage为你要调试的 App 包名；
3. 保存脚本，选择设备执行，手机屏幕左下角会出现悬浮日志框；
4. 实时查看每一步执行状态，快速定位启动失败、控件找不到、分支走错等问题。

五、常见问题与避坑指南

1. 悬浮框不显示

   • 检查是否授予悬浮窗权限（冰狐 APP 必须开启）；
   • 确认 Float.config 在 main 函数第一行；
   • 排除 Float.enable (false) 或 Float.visible (false)。

2. 日志被遮挡 / 看不清

   • 修改 gravity 为 left|bottom 或 right|top，避开操作区；
   • 调大 width/height，提升字号 size；
   • 用高对比配色，如黑底白字、白底黑字。

3. 自动化操作失效

   • 必须设置 touchable:false，否则悬浮框拦截触摸事件；
   • 不要把位置放在控件密集区。

4. 日志乱码 / 重叠

   • 输出内容用纯文本，避免特殊符号；
   • 每次输出不要过长，分行输出更清晰。

六、总结

对于冰狐智能辅助自动化脚本开发，Float 悬浮日志是最贴合移动端场景的调试工具：

• 不用电脑、实时可视化、信息可留存；
• API 极简、配置灵活、零学习成本；
• 不干扰自动化操作，适配所有脚本类型。

按照Demo 模板你可以快速搭建专属调试日志体系，把「盲猜问题」变成「可视化追踪」，大幅缩短脚本开发与 bug 修复时间，可结合冰狐 UI 树工具、在线 Log，形成 「Float 本地实时 + 网页端远程」双日志体系，实现全场景无死角调试。