CheckBox QML Type

可打开或关闭的校验按钮。更多

Import Statement:	`import QtQuick.Controls`
Inherits:	AbstractButton

所有成员（包括继承成员）的列表

属性

checkState : enumeration
nextCheckState : function (since QtQuick.Controls 2.4 (Qt 5.11))
tristate : bool

详细说明

复选框（CheckBox）是一个可以打开（选中）或关闭（取消选中）的选项按钮。复选框通常用于从一组选项中选择一个或多个选项。对于较大的选项集（如列表中的选项），可考虑使用CheckDelegate 代替。

复选框的 API 继承自AbstractButton 。例如，可以使用checked 属性设置复选框的状态。

除了选中和未选中状态外，还有第三种状态：部分选中。可以使用tristate 属性启用部分选中状态。这种状态表示无法确定常规的已选中/未选中状态，通常是因为其他状态影响了复选框。例如，在树状视图中选择了多个子节点时，这种状态就很有用。

ColumnLayout {
    CheckBox {
        checked: true
        text: qsTr("First")
    }
    CheckBox {
        text: qsTr("Second")
    }
    CheckBox {
        checked: true
        text: qsTr("Third")
    }
}

可以使用非排他性ButtonGroup 管理分层复选框组。

下面的示例说明了如何将子节点的组合复选状态与父复选框的复选状态绑定：

Column {
    ButtonGroup {
        id: childGroup
        exclusive: false
        checkState: parentBox.checkState
    }

    CheckBox {
        id: parentBox
        text: qsTr("Parent")
        checkState: childGroup.checkState
    }

    CheckBox {
        checked: true
        text: qsTr("Child 1")
        leftPadding: indicator.width
        ButtonGroup.group: childGroup
    }

    CheckBox {
        text: qsTr("Child 2")
        leftPadding: indicator.width
        ButtonGroup.group: childGroup
    }
}

另请参阅 自定义复选框、ButtonGroup 和按钮控件。

属性文档

checkState : enumeration

该属性保存复选框的复选状态。

可用状态：

常量	说明
`Qt.Unchecked`	复选框未选中。
`Qt.PartiallyChecked`	复选框部分选中。此状态仅在tristate 启用时使用。
`Qt.Checked`	复选框已选中。

另请参阅 tristate 和checked 。

nextCheckState : function [since QtQuick.Controls 2.4 (Qt 5.11)]

该属性包含一个回调函数，每当用户通过触摸、鼠标或键盘交互式切换复选框时，都会调用该函数来确定下一个复选状态。

默认情况下，普通复选框在Qt.Unchecked 和Qt.Checked 状态之间循环，三态复选框在Qt.Unchecked 、Qt.PartiallyChecked 和Qt.Checked 状态之间循环。

nextCheckState 回调函数可以覆盖默认行为。下面的示例实现了一个三态复选框，该复选框可根据外部条件显示部分选中状态，但当用户交互式切换时，该复选框永远不会循环到部分选中状态。

CheckBox {
    tristate: true
    checkState: allChildrenChecked ? Qt.Checked :
                   anyChildChecked ? Qt.PartiallyChecked : Qt.Unchecked

    nextCheckState: function() {
        if (checkState === Qt.Checked)
            return Qt.Unchecked
        else
            return Qt.Checked
    }
}

该属性在 QtQuick.Controls 2.4 (Qt 5.11) 中引入。

tristate : bool

该属性确定复选框是否为三态复选框。

在下面的动画中，第一个复选框是三态复选框：

默认值为false ，即复选框只有两种状态。

© 2025 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.