复选框 QML 类型

可切换开/关状态的复选按钮。更多信息...

导入语句	import QtQuick.Controls
继承	AbstractButton

所有成员列表，包括继承成员

属性

checkState : 枚举
nextCheckState : 函数 (自 QtQuick.Controls 2.4 (Qt 5.11))
tristate : 布尔值

详细信息

复选框展示了一个可切换开（选中）或关（未选中）的选项按钮。复选框通常用于从一个选项集中选择一个或多个选项。对于较大的选项集，如在列表中，请考虑使用CheckDelegate代替。

复选框从AbstractButton继承了其 API。例如，可以通过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
    }
}

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

属性文档

checkState : 枚举

此属性保存复选框的选中状态。

可用状态

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

另请参阅tristate和checked。

nextCheckState : 函数 [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，即复选框只有两种状态。