QCheckBox Class
QCheckBox 控件提供了一个带有文本标签的复选框。更多内容...
| 标题: | #include <QCheckBox> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 继承自: | QAbstractButton |
属性
- tristate : bool
公共函数
| QCheckBox(QWidget *parent = nullptr) | |
| QCheckBox(const QString &text, QWidget *parent = nullptr) | |
| virtual | ~QCheckBox() |
| Qt::CheckState | checkState() const |
| bool | isTristate() const |
| void | setCheckState(Qt::CheckState state) |
| void | setTristate(bool y = true) |
重新实现的公共函数
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
信号
(since 6.7) void | checkStateChanged(Qt::CheckState state) |
受保护函数
| virtual void | initStyleOption(QStyleOptionButton *option) const |
重新实现的受保护函数
| virtual void | checkStateSet() override |
| virtual bool | event(QEvent *e) override |
| virtual bool | hitButton(const QPoint &pos) const override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | nextCheckState() override |
| virtual void | paintEvent(QPaintEvent *) override |
详细说明

QCheckBox 是一个选项按钮,可以被启用(选中)或禁用(未选中)。 复选框通常用于表示应用程序中那些可以启用或禁用且不会影响其他功能的功能。可以实现不同类型的行为。例如,可以使用QButtonGroup 将复选框进行逻辑分组,从而支持互斥复选框。但是,QButtonGroup 并不提供任何视觉呈现。
下图进一步说明了互斥复选框与非互斥复选框之间的区别。
![]() | ![]() |
每当复选框被选中或取消选中时,它都会发出checkStateChanged() 信号。若希望在复选框状态每次发生变化时触发某个操作,请连接此信号。您可以使用isChecked() 来查询复选框是否已被选中。
除了常见的“已选中”和“未选中”状态外,QCheckBox 还提供了一个可选的第三种状态,用于表示“无变化”。当您需要让用户既不选中也不取消选中复选框时,此功能非常有用。 若需要此第三种状态,请使用setTristate() 启用它,并使用checkState() 查询当前的切换状态。
与QPushButton 一样,复选框会显示文本,并可选地显示一个小图标。图标通过setIcon()设置。文本可在构造函数中设置,也可通过setText()设置。若要在首选字符前添加“&”符号,即可指定快捷键。例如:
在此示例中,快捷键为Alt+A。详情请参阅QShortcut 文档。若要显示实际的“&”符号,请使用 '&&'。
另请参阅 QAbstractButton 和QRadioButton 。
属性文档
tristate : bool
该属性用于指定复选框是否为三态复选框
默认值为 false,即该复选框只有两种状态。
访问函数:
| bool | isTristate() const |
| void | setTristate(bool y = true) |
成员函数文档
[explicit] QCheckBox::QCheckBox(QWidget *parent = nullptr)
根据给定的parent 创建一个复选框,但不显示文本。
parent 将该参数传递给QAbstractButton 的构造函数。
[explicit] QCheckBox::QCheckBox(const QString &text, QWidget *parent = nullptr)
根据给定的parent 和text 创建一个复选框。
parent 将传递给QAbstractButton 构造函数。
[virtual noexcept] QCheckBox::~QCheckBox()
析构函数。
Qt::CheckState QCheckBox::checkState() const
返回复选框的选中状态。如果不需要三态支持,也可以使用QAbstractButton::isChecked(),该函数返回一个布尔值。
另请参阅 setCheckState() 和Qt::CheckState 。
[signal, since 6.7] void QCheckBox::checkStateChanged(Qt::CheckState state)
每当复选框的状态发生变化时(即用户勾选或取消勾选时),都会触发此信号。
state 包含复选框的新Qt::CheckState 。
该函数在 Qt 6.7 中引入。
[override virtual protected] void QCheckBox::checkStateSet()
重写了:QAbstractButton::checkStateSet()。
[override virtual protected] bool QCheckBox::event(QEvent *e)
重写了:QAbstractButton::event(QEvent *e)。
[override virtual protected] bool QCheckBox::hitButton(const QPoint &pos) const
重写了:QAbstractButton::hitButton(const QPoint &pos) const。
[virtual protected] void QCheckBox::initStyleOption(QStyleOptionButton *option) const
使用此QCheckBox 中的值初始化option 。此方法对于需要QStyleOptionButton 但又不希望自行填写所有信息的子类非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual] QSize QCheckBox::minimumSizeHint() const
重新实现了属性QWidget::minimumSizeHint 的访问函数。
[override virtual protected] void QCheckBox::mouseMoveEvent(QMouseEvent *e)
重写了:QAbstractButton::mouseMoveEvent(QMouseEvent *e)。
[override virtual protected] void QCheckBox::nextCheckState()
重写了:QAbstractButton::nextCheckState()。
[override virtual protected] void QCheckBox::paintEvent(QPaintEvent *)
重写了:QAbstractButton::paintEvent(QPaintEvent *e)。
void QCheckBox::setCheckState(Qt::CheckState state)
将复选框的选中状态设置为state 。如果您不需要三态支持,也可以使用QAbstractButton::setChecked(),该函数接受一个布尔值。
另请参阅 checkState() 和Qt::CheckState 。
[override virtual] QSize QCheckBox::sizeHint() const
重新实现了属性QWidget::sizeHint 的访问函数。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.

