QML教程20 - CheckBox：多选功能的王者

原创于 2025-12-12 09:00:00 发布 · 859 阅读

5 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#QML #qt #ui #c++

QML教程20 - CheckBox：多选功能的王者

本文是《QML从入门到实战》系列的第二十篇，讲CheckBox控件的实战用法。

💡 本文配有完整的可运行源码和练习答案，需要的话可以文末获取。

前言：为什么CheckBox这么重要？

做应用的时候，CheckBox可以说是出镜率最高的控件之一。

不管你做什么项目：注册页面的"同意用户协议"、设置界面的功能开关、列表的多选操作…到处都能看到CheckBox的身影。

我刚开始学QML时，总觉得CheckBox很简单，不就是个勾选框吗？结果踩了不少坑：

三态CheckBox显示不正确（忘了启用tristate）
文本太长导致换行问题
CheckBox和RadioButton分不清使用场景
多个CheckBox之间想要互斥，结果用错了控件

后来做了几个项目才发现，CheckBox看似简单，但要用好还真有些技巧。

本节效果预览

学完本节，你能用CheckBox做出这些效果：

在这里插入图片描述

CheckBox的本质：多选之王

CheckBox最大的特点就是可以同时选中多个选项，这点和RadioButton完全不同：

CheckBox：多选，互不影响，适合功能开关、选项设置
RadioButton：单选，同组互斥，适合性别选择、支付方式
Switch：开关，二态切换，适合功能启用/禁用

举个例子，用户注册时选择兴趣爱好：

Column {
    spacing: 10
    
    Text { text: "选择您的兴趣爱好（可多选）" }
    
    CheckBox { text: "🎵 音乐" }
    CheckBox { text: "🎬 电影" }
    CheckBox { text: "📚 阅读" }
    CheckBox { text: "🎮 游戏" }
    // 用户可以同时选择多个
}

这种场景用CheckBox就很合适，因为用户的兴趣可以有多个。

踩过的坑：三态CheckBox的正确用法

最容易踩坑的就是三态CheckBox。我第一次用的时候，设置了checkState但没有启用tristate，结果显示不正确。

// ❌ 错误：没有启用三态
CheckBox {
    text: "全选"
    checkState: Qt.PartiallyChecked  // 无效！
}

// ✅ 正确：必须启用tristate
CheckBox {
    text: "全选"
    tristate: true  // 关键！
    checkState: Qt.PartiallyChecked
}

三态CheckBox特别适合做父子全选功能：

未选中：所有子项都没选
部分选中：有些子项选了，有些没选
全选中：所有子项都选了

文本换行的解决方案

另一个常见问题是文本过长导致布局乱。特别是"我已阅读并同意《用户协议》和《隐私政策》"这种长文本。

解决方法是自定义contentItem：

CheckBox {
    width: 300
    text: "我已阅读并同意非常长的用户协议和隐私政策内容"
    
    contentItem: Text {
        text: parent.text
        wrapMode: Text.WordWrap  // 自动换行
        leftPadding: parent.indicator.width + parent.spacing
        verticalAlignment: Text.AlignVCenter
    }
}

实战案例：设置面板

CheckBox最常用的场景就是设置面板，来看个完整的例子：

GroupBox {
    title: "通知设置"
    width: 400
    
    Column {
        spacing: 15
        
        CheckBox {
            id: emailNotify
            text: "📧 接收邮件通知"
            checked: true
        }
        
        CheckBox {
            text: "📱 接收短信通知"
            checked: false
        }
        
        CheckBox {
            id: pushNotify
            text: "🔔 接收推送通知"
            checked: true
        }
        
        CheckBox {
            text: "🔊 启用声音"
            checked: true
            enabled: pushNotify.checked  // 依赖推送通知
            leftPadding: 30  // 缩进表示层级关系
        }
    }
}

注意这里用了级联启用的技巧：只有开启推送通知，声音设置才可用。

CheckBox vs RadioButton：什么时候用哪个？

这是新手最容易搞混的地方。简单记住：

需要多选：用CheckBox
需要单选：用RadioButton

// ✅ 多选场景：用CheckBox
Text { text: "您熟悉哪些编程语言？（可多选）" }
CheckBox { text: "Python" }
CheckBox { text: "JavaScript" }
CheckBox { text: "Java" }

// ✅ 单选场景：用RadioButton
Text { text: "您的性别是？" }
ButtonGroup { id: genderGroup }
RadioButton { text: "男"; ButtonGroup.group: genderGroup }
RadioButton { text: "女"; ButtonGroup.group: genderGroup }

还有一个判断标准：看选项之间是否互斥。互斥用RadioButton，不互斥用CheckBox。

性能优化小技巧

如果你的CheckBox很多（比如几百个），可以考虑用Repeater来优化：

Column {
    Repeater {
        model: ["选项1", "选项2", "选项3", "选项4", "选项5"]
        
        CheckBox {
            text: modelData
            
            // 只有选中的项才执行复杂逻辑
            onToggled: {
                if (checked) {
                    console.log("选中了:", text)
                }
            }
        }
    }
}