Hello！我是程序员Feri—— 13 年编程老炮，实战派技术人，拆解编程技巧、分享副业心得，记录程序员的进阶路，AI 时代一起稳稳向前。

在App开发中，"选择"是用户交互的高频场景——从"周末想去哪玩"到"订单需要哪些服务"，都离不开勾选操作。今天我们就来聊聊多选框组件（Checkbox），这个看似简单却暗藏玄机的交互小能手，以及它的最佳拍档CheckboxGroup。

一、为什么多选框需要"组队"？

想象一个场景：你设计了一个"爱好选择"界面，放了10个独立的多选框。当用户想"全选"时，你需要一个个判断每个框的状态并修改；当用户取消某个选项时，又要检查是否还需要取消"全选"状态——这就像管理一群各自为政的散兵，累到脱发。

而CheckboxGroup的出现，就像给这些多选框找了个"组长"：同一group名称的多选框会自动关联，组长会统一记录选中状态、处理全选逻辑。从此，开发者只需和"组长"沟通，不用再逐个点名，效率直接拉满。

二、多选框组件的"技能说明书"

1. 核心成员：CheckboxGroup（组长）

它是整个多选组的管理者，负责记录组内所有选项的选中状态，并对外提供"状态变更"的消息通知。

CheckboxGroup({ group: "groupName" })  // group参数：给组起个名字，方便多选框"认亲"  .onChange((selectedInfo) => {        // 当组内选中状态变化时触发    console.log("当前选中的选项：", selectedInfo.name);  // selectedInfo.name是选中项name的数组  })  .checkboxShape(CheckBoxShape.ROUNDED_SQUARE)  // 统一设置组内多选框的形状（圆形/方形）

这里有个小细节：selectedInfo.name返回的是数组（因为多选可以选多个），比如选了"看电影"和"刷短剧"，会得到["看电影", "刷短剧"]。

2. 团队成员：Checkbox（组员）

每个多选框都是组里的一员，必须通过group参数"报团"，否则就是"流浪的孤魂"（无法被组长管理）。

Checkbox({   group: "groupName",  // 必须和组长的group名称一致，才能加入团队  name: "reading"      // 选项的唯一标识，会被组长记录到selectedInfo.name中})  .selectedColor("#FF007DFF")  // 选中时的颜色（给组员换件"工作服"）  .disabled(false)             // 是否禁用（true=罢工状态，无法勾选）

三、实战演练：打造一个"周末计划选择器"

光说不练假把式，我们来做一个实用场景：让用户选择周末想做的事，支持全选/取消全选，还能实时显示选中结果。

@Entry@Componentstruct WeekendPlanner {  @State selectedPlans: string = "";  // 记录选中的计划  build() {    Column({ space: 20 }) {      Text("这个周末，你想做什么？")        .fontSize(18)        .fontWeight(FontWeight.Bold)      // 多选组"组长"：管理所有周末计划选项      Row(){        CheckboxGroup({ group: "weekend" })          .onChange((info) => {            // 把选中的数组转成字符串，用逗号分隔（比toString()更友好）            this.selectedPlans = info.name.join("、");          })          .checkboxShape(CheckBoxShape.CIRCLE)  // 这次用圆形造型          .padding({ left: 20 })        Text("全选/取消全选").fontSize(14)      }            // 组内选项：每个选项单独占一行，搭配文字说明      this.createPlanItem("看一场新上映的电影", "movie")      this.createPlanItem("去公园野餐", "picnic")      this.createPlanItem("在家躺平看剧", "relax")      this.createPlanItem("约朋友打羽毛球", "sports")      // 显示用户的选择结果      Text(`你的周末计划：${this.selectedPlans || "还没选好？快挑一个吧～"}`)        .fontSize(14)        .fontColor("#666666")    }    .padding(30)    .height('100%')    .width('100%')  }  // 封装一个创建选项的方法，避免重复代码（代码洁癖福音）  @Builder createPlanItem(label: string, planName: string) {    Row({ space: 10 }) {      Checkbox({ group: "weekend", name: planName })      Text(label).fontSize(16)    }    .padding({ left: 20 })  // 和组长对齐，视觉更整齐  }}

这个例子里有几个小心机：

• 用@Builder封装了选项样式，避免重复写Row和Checkbox，代码更清爽；
• 选中结果用join("、")格式化，比默认的数组字符串（带逗号和中括号）更符合中文阅读习惯；
• 当没有选中项时，显示引导文字，提升用户体验。

四、进阶技巧：让多选框更懂用户

1. 限制最大选择数量

比如"最多选3个爱好"，可以在onChange里判断选中数组的长度：

CheckboxGroup({ group: "hobby" })  .onChange((info) => {    if (info.name.length > 3) {      // 超过3个时，这里可以做提示或自动取消最后一个选择（需要结合状态管理实现）      promptAction.showToast({ message: "最多选3个哦～" });    }  })

2. 禁用部分选项

比如"已售罄的活动"不能选，给Checkbox加disabled(true)：

Row({ space: 10 }) {  Checkbox({ group: "activity", name: "concert" })    .disabled(true)  // 禁用状态，灰显且无法点击  Text("演唱会（已售罄）").fontSize(16).opacity(0.6)  // 文字也灰显，保持视觉一致}

3. 反选功能

想要一个"反选"按钮？可以用状态管理记录当前选中项，点击时计算反选后的结果（需要结合@Link或全局状态，适合有一定基础后尝试）。

五、小试牛刀：练习题升级

1. 基础题：用CheckboxGroup做一个" pizza配料选择器"，包含"芝士、培根、洋葱、青椒"4个选项，实时显示"你选了X种配料"。
2. 进阶题：在基础题上增加： 最多选3种配料；禁用"菠萝"（毕竟有人觉得菠萝不该出现在pizza上😜）；加一个"清除选择"按钮，点击后取消所有勾选。

多选框看似简单，但用好CheckboxGroup的"团队协作"能力，能让你的交互逻辑更清晰、代码更简洁。下次开发选择类界面时，记得给多选框找个"组长"哦～