PyQt5 QCheckBox控件详解：状态、信号与三态复选框实战

青禾

发布时间：2026-10-12 | 2人浏览过

原创

本文深入解析PyQt5中QCheckBox控件的核心用法，涵盖常用方法、状态信号处理及三态复选框的高级配置。通过完整代码实例，演示如何绑定stateChanged信号、设置快捷键、判断选中状态，并详细讲解setTristate()与半选状态的实现逻辑，帮助开发者掌握GUI界面中复选框的灵活应用。

QCheckBox类中常用方法如表

方法	描述
setChecked()	设置复选框的状态，设置为True表示选中，False表示取消选中的复选框
setText()	设置复选框的显示文本
text()	返回复选框的显示文本
isChecked()	检查复选框是否被选中
setTriState()	设置复选框为一个三态复选框
setCheckState()	三态复选框的状态设置，具体设置可以见下表

三态复选框的三种状态

名称	值	含义
Qt.Checked	2	组件没有被选中（默认）
Qt.PartiallyChecked	1	组件被半选中
Qt.Unchecked	0	组件被选中

QCheckBox按钮的使用实例

import sys
from PyQt5.QtCore import *
from PyQt5.QtGui import *
from PyQt5.QtWidgets import *
from PyQt5.QtCore import Qt


class CheckBoxDemo(QWidget):

  def __init__(self, parent=None):
    super(CheckBoxDemo, self).__init__(parent)

    #创建一个GroupBox组
    groupBox = QGroupBox("Checkboxes")
    groupBox.setFlat(False)

    #创建复选框1，并默认选中，当状态改变时信号触发事件
    self.checkBox1 = QCheckBox("&Checkbox1")
    self.checkBox1.setChecked(True)
    self.checkBox1.stateChanged.connect(lambda: self.btnstate(self.checkBox1))

    #创建复选框，标记状态改变时信号触发事件
    self.checkBox2 = QCheckBox("Checkbox2")
    self.checkBox2.toggled.connect(lambda: self.btnstate(self.checkBox2))

    #创建复选框3，设置为3状态，设置默认选中状态为半选状态，当状态改变时信号触发事件
    self.checkBox3 = QCheckBox("tristateBox")
    self.checkBox3.setTristate(True)
    self.checkBox3.setCheckState(Qt.PartiallyChecked)
    self.checkBox3.stateChanged.connect(lambda: self.btnstate(self.checkBox3))

    #水平布局
    layout = QHBoxLayout()
    #控件添加到水平布局中
    layout.addWidget(self.checkBox1)
    layout.addWidget(self.checkBox2)
    layout.addWidget(self.checkBox3)

    #设置QGroupBox组的布局方式
    groupBox.setLayout(layout)

    #设置主界面布局垂直布局
    mainLayout = QVBoxLayout()
    #QgroupBox的控件添加到主界面布局中
    mainLayout.addWidget(groupBox)

    #设置主界面布局
    self.setLayout(mainLayout)
    #设置主界面标题
    self.setWindowTitle("checkbox demo")

  #输出三个复选框当前的状态，0选中，1半选，2没选中
  def btnstate(self, btn):
    chk1Status = self.checkBox1.text() + ", isChecked=" + str(self.checkBox1.isChecked()) + ', chekState=' + str(
      self.checkBox1.checkState()) + "\n"
    chk2Status = self.checkBox2.text() + ", isChecked=" + str(self.checkBox2.isChecked()) + ', checkState=' + str(
      self.checkBox2.checkState()) + "\n"
    chk3Status = self.checkBox3.text() + ", isChecked=" + str(self.checkBox3.isChecked()) + ', checkState=' + str(
      self.checkBox3.checkState()) + "\n"
    print(chk1Status + chk2Status + chk3Status)


if __name__ == '__main__':
  app = QApplication(sys.argv)
  checkboxDemo = CheckBoxDemo()
  checkboxDemo.show()
  sys.exit(app.exec_())

效果图如下

QCheckBox代码分析：

在此示例中，三个复选框被添加至水平布局管理器，并整体嵌入到一个QGroupBox组容器中。

 groupBox = QGroupBox("Checkboxes")
 groupBox.setFlat(False)

将三个复选框的stateChanged信号均连接至槽函数stateChanged()，并通过lambda表达式将对象作为参数传递给槽函数。

当QCheckBox的状态发生变化时，会发射stateChanged信号；一旦信号触发，便会执行自定义的槽函数btnstate()。

self.checkBox1.stateChanged.connect(lambda: self.btnstate(self.checkBox1))
self.checkBox2.toggled.connect(lambda: self.btnstate(self.checkBox2))
self.checkBox3.stateChanged.connect(lambda: self.btnstate(self.checkBox3))

实例化CheckBox1和CheckBox2两个对象，将CheckBox1的状态设为选中，并为CheckBox1设置快捷键，使用‘&'符号，则可以通过快捷键Alt+C选中checkbox1复选框。

self.checkBox1 = QCheckBox("&Checkbox1")
self.checkBox1.setChecked(True)

使用按钮的isChecked()方法，判断复选框是否被选中，其核心代码是：

chk1Status = self.checkBox1.text() + ", isChecked=" + str(self.checkBox1.isChecked()) + ', chekState=' + str(
      self.checkBox1.checkState()) + "\n"

实例化一个QCheckBox类的对象checkBox3，然后使用setTristate()开启三态模式,然后设置为半选状态并连接槽函数

self.checkBox3 = QCheckBox("tristateBox")
self.checkBox3.setTristate(True)
self.checkBox3.setCheckState(Qt.PartiallyChecked)
self.checkBox3.stateChanged.connect(lambda: self.btnstate(self.checkBox3))

本文详细讲解了PyQt5复选框控件QCheckBox详细使用方法与实例，更多关于PyQt5控件知识请查看下面的相关链接