自动化脚本ui编程之复选框控件(checkbox)

我们在进行自动化脚本开发时，UI 交互界面是提升脚本易用性、实现灵活配置的核心模块，而复选框（CheckBox） 作为多选项选择的基础控件，在功能配置、权限开关、批量操作等场景中不可或缺。本文全面讲解 CheckBox 控件的属性、事件、函数用法，并提供完整可运行的 Demo 源码，帮助开发者快速掌握复选框控件的实战应用。

一、CheckBox 控件基础认知

冰狐智能辅助的 UI 体系采用XML 模板描述界面 + JavaScript 处理逻辑的架构，CheckBox 控件作为文本控件（Text）的子类，继承了文本控件的基础特性，同时具备独立的选中状态交互能力，核心定位是支持用户同时选中多个选项，区别于单选框只能选择单一选项的特性。

1. 核心定位与适用场景

CheckBox 控件是自动化脚本 UI 中多选项配置的标准控件，典型应用场景包括：

• 自动化任务的功能开关（如开启 / 关闭通知提醒、自动截图、后台保活）；
• 批量操作的选项勾选（如选择多个 APP 执行启动、清理、签到操作）；
• 权限与参数配置（如勾选需要获取的设备权限、启用特定脚本逻辑）；
• 表单类界面的多选项确认（如用户协议、功能协议勾选）。

2. 控件核心特性

• 继承自 Text 控件，支持文本显示、字体大小、对齐方式等文本属性；
• 自带选中 / 未选中两种状态，状态值为布尔类型（true/false）；
• 支持模板静态初始化与 JS 动态控制两种状态设置方式；
• 提供专属选中事件，实时监听用户勾选 / 取消操作；
• 可通过 ID 精准定位，支持批量操作与状态获取。

二、CheckBox 控件核心属性详解

属性是控件的基础配置项，决定控件的初始状态、显示效果与交互能力，CheckBox 的核心属性为checked，同时兼容 Text 控件的通用属性（如 id、text、size、gravity 等）。

1. 核心属性：checked（选中状态）

checked 是 CheckBox 最关键的属性，用于定义控件的初始选中状态，支持模板静态设置和JS 动态设置两种方式，属性值为布尔类型（true = 选中，false = 未选中，默认值为 false）。

（1）模板中静态设置

直接在<checkbox>标签中添加checked="true"或checked="false"，实现界面加载时的默认状态配置，适合固定初始状态的场景。

<template>
  <linear orientation="vertical" padding="10">
    <!-- 初始选中状态 -->
    <checkbox id="cb_banana" text="香蕉" checked="true" size="16"/>
    <!-- 初始未选中状态 -->
    <checkbox id="cb_apple" text="苹果" size="16"/>
    <checkbox id="cb_orange" text="橘子" size="16"/>
  </linear>
</template>

（2）JS 动态设置

通过ui(控件ID).checked(true/false)方法，在脚本运行中动态修改选中状态，适合根据逻辑自动切换状态的场景（如根据配置文件自动勾选选项）。

2. 通用基础属性

作为 Text 子类，CheckBox 支持以下通用属性，优化界面显示效果：

• id：控件唯一标识，JS 操作控件的核心依据，必须唯一；
• text：控件显示的文本内容，即复选框右侧的说明文字；
• size：文本字体大小，调整显示清晰度；
• gravity：文本对齐方式（left/center/right）；
• layoutWeight：布局权重，适配多控件并排显示。

三、CheckBox 控件专属事件：onChecked（选中事件）

事件是实现用户交互响应的核心，CheckBox 提供onChecked专属事件，当用户勾选或取消勾选控件时触发，回调函数可获取当前控件对象与最新选中状态。

1. 事件绑定方式

在模板中通过onChecked="函数名"绑定回调函数，JS 中定义对应函数处理逻辑，支持多个 CheckBox 绑定同一个回调函数，统一处理逻辑。

2. 回调函数参数

回调函数默认传入两个参数：

• checkbox：当前触发事件的 CheckBox 控件对象，可通过checkbox.text获取显示文本、checkbox.id获取控件 ID；
• checked：最新选中状态（布尔类型，true = 勾选，false = 取消勾选）。

3. 事件基础示例

<template>
  <linear orientation="vertical" padding="10">
    <checkbox text="香蕉" onChecked="handleCheckChange" size="16"/>
    <checkbox text="苹果" onChecked="handleCheckChange" size="16"/>
    <checkbox text="橘子" onChecked="handleCheckChange" size="16"/>
  </linear>
</template>

// 入口函数：初始化UI
function main() {
  setupUI(); // 加载界面模板
}

// 复选框选中事件回调
function handleCheckChange(checkbox, checked) {
  // 打印操作日志
  console.log("选中控件：" + checkbox.text + "，当前状态：" + checked);
  // 可根据状态执行后续逻辑（如更新配置、控制任务开关）
}

四、CheckBox 控件核心操作函数

冰狐智能辅助为 CheckBox 提供了checked()/value() 两个等效函数，用于获取或设置控件选中状态，函数返回值为布尔类型，支持传参设置状态、不传参获取状态两种用法。

1. 函数用法对比

2. 动态操作示例

<template>
  <linear orientation="vertical" padding="10">
    <checkbox id="cb_demo" text="测试复选框" size="16"/>
    <!-- 操作按钮 -->
    <button id="btn_get" text="获取状态" onClick="getCheckStatus" size="16"/>
    <button id="btn_set" text="设置选中" onClick="setCheckStatus" size="16"/>
  </linear>
</template>

function main() {
  setupUI();
}

// 界面显示时自动初始化状态
function onUIResume() {
  // 动态设置为选中状态（两种写法等效）
  ui("cb_demo").checked(true);
  // ui("cb_demo").value(true);
}

// 获取选中状态
function getCheckStatus() {
  var status = ui("cb_demo").checked();
  console.log("当前选中状态：" + status);
  toast("当前状态：" + (status ? "已选中" : "未选中"));
}

// 设置选中状态
function setCheckStatus() {
  ui("cb_demo").checked(true);
  toast("已设置为选中状态");
}

五、完整实战 Demo：多选项批量选择与任务控制

为了让开发者快速落地应用，本文提供完整可运行的 CheckBox 实战 Demo，实现多水果选项勾选、批量获取选中结果、控制自动化任务执行的功能，代码符合冰狐智能辅助官方规范，可直接复制运行。

Demo 功能说明

1. 界面加载时默认勾选第一个选项；
2. 支持多个复选框独立勾选 / 取消；
3. 点击 "获取选中结果" 按钮，批量打印所有选中的选项；
4. 点击 "执行任务" 按钮，根据勾选状态执行对应自动化逻辑；
5. 点击 "清空选择" 按钮，取消所有复选框选中状态。

完整源码

<template>
  <linear orientation="vertical" padding="15" width="match_parent">
    <!-- 标题 -->
    <text text="水果选择器" size="20" gravity="center" marginBottom="10"/>
    
    <!-- 复选框选项组 -->
    <checkbox id="cb1" text="香蕉" checked="true" size="16" marginBottom="8"/>
    <checkbox id="cb2" text="苹果" size="16" marginBottom="8"/>
    <checkbox id="cb3" text="橘子" size="16" marginBottom="8"/>
    <checkbox id="cb4" text="葡萄" size="16" marginBottom="15"/>
    
    <!-- 操作按钮组 -->
    <linear orientation="horizontal" width="match_parent" marginBottom="10">
      <button id="btn_get" text="获取选中结果" layoutWeight="1" size="14" onClick="getAllChecked"/>
      <button id="btn_clear" text="清空选择" layoutWeight="1" size="14" onClick="clearAllChecked" marginLeft="5"/>
    </linear>
    <button id="btn_task" text="执行自动化任务" width="match_parent" size="16" onClick="doAutoTask"/>
    
    <!-- 结果显示 -->
    <text id="tv_result" text="选中结果：无" size="16" marginTop="10" color="#FF0000"/>
  </linear>
</template>

// 入口函数
function main() {
  setupUI(); // 初始化UI界面
  console.log("=== 复选框Demo启动 ===");
}

// 界面恢复时初始化（保证状态生效）
function onUIResume() {
  // 可选：再次确认初始状态
  ui("cb1").checked(true);
}

/**
 * 批量获取所有复选框选中状态
 */
function getAllChecked() {
  // 定义选项数组，存储ID与文本
  var checkList = [
    {id: "cb1", name: "香蕉"},
    {id: "cb2", name: "苹果"},
    {id: "cb3", name: "橘子"},
    {id: "cb4", name: "葡萄"}
  ];
  var result = [];
  
  // 遍历获取选中状态
  for (var i = 0; i < checkList.length; i++) {
    var item = checkList[i];
    var isChecked = ui(item.id).checked();
    if (isChecked) {
      result.push(item.name);
    }
  }
  
  // 处理结果显示
  var showText = result.length > 0 ? "选中结果：" + result.join("、") : "选中结果：无";
  ui("tv_result").setText(showText);
  console.log(showText);
  toast("获取成功！");
}

/**
 * 清空所有复选框选择
 */
function clearAllChecked() {
  ui("cb1").checked(false);
  ui("cb2").checked(false);
  ui("cb3").checked(false);
  ui("cb4").checked(false);
  ui("tv_result").setText("选中结果：无");
  toast("已清空所有选择！");
}

/**
 * 根据勾选状态执行自动化任务
 */
function doAutoTask() {
  var hasChecked = ui("cb1").checked() || ui("cb2").checked() || ui("cb3").checked() || ui("cb4").checked();
  
  if (!hasChecked) {
    toast("请至少选择一个选项！");
    return;
  }
  
  toast("开始执行自动化任务...");
  console.log("=== 开始执行任务 ===");
  
  // 模拟自动化逻辑：根据勾选执行对应操作
  if (ui("cb1").checked()) {
    console.log("执行【香蕉】相关任务");
    // 可替换为真实自动化操作（如点击、启动APP等）
  }
  if (ui("cb2").checked()) {
    console.log("执行【苹果】相关任务");
  }
  if (ui("cb3").checked()) {
    console.log("执行【橘子】相关任务");
  }
  if (ui("cb4").checked()) {
    console.log("执行【葡萄】相关任务");
  }
  
  console.log("=== 任务执行完成 ===");
  toast("任务执行完成！");
}

// 返回键关闭界面
function onBackPressed() {
  closeUI();
}

Demo 运行说明

1. 打开冰狐智能辅助 Web IDE，新建脚本；
2. 复制上述完整源码，粘贴到脚本编辑区；
3. 点击运行，即可看到多选项复选框界面；
4. 测试勾选、获取结果、清空选择、执行任务等功能，查看日志与界面反馈。

六、CheckBox 控件开发常见问题与技巧

1. 常见问题解决

• 问题 1：模板中设置 checked="true"，但界面加载未选中解决：确保在main函数中调用setupUI()，并可在onUIResume生命周期函数中再次动态设置状态。
• 问题 2：onChecked 事件不触发解决：检查模板中onChecked绑定的函数名与 JS 中函数名是否一致，无拼写错误。
• 问题 3：批量获取状态时部分控件获取失败解决：确认控件 ID 唯一，遍历数组中的 ID 与模板中 ID 完全匹配。

2. 开发实用技巧

• 批量操作优化：将多个 CheckBox 的 ID 存入数组，通过循环批量设置 / 获取状态，减少重复代码；
• 状态同步：将选中状态存入全局变量，实现界面与自动化任务逻辑的状态同步；
• 样式优化：结合 margin、padding、size 等属性，调整复选框间距与字体，提升界面美观度；
• 逻辑判断：执行任务前先判断是否有勾选选项，避免空操作，提升用户体验。

七、总结

CheckBox 控件是自动化脚本 UI 开发的基础核心控件，掌握其属性、事件、函数用法，是实现灵活交互界面的关键。本文从基础认知、属性、事件、函数到完整实战 Demo，全方位讲解了 CheckBox 的应用方法，所提供的 Demo 源码可直接用于自动化脚本开发，适配批量配置、功能开关、任务控制等多种场景。在实际开发中，可结合线性布局（linear）、按钮（button）、文本（text）等控件，组合出更复杂的交互界面，让自动化脚本更易用、更灵活。后续可深入学习冰狐智能辅助 UI 体系的其他控件（如单选框、下拉框、输入框），构建完整的自动化配置界面，提升脚本的实用性与专业性。