ButtonGroup QML Type

一组互斥的可选中按钮。更多

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

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

属性

buttons : list<AbstractButton>
checkState : enumeration (since QtQuick.Controls 2.4 (Qt 5.11))
checkedButton : AbstractButton
exclusive : bool (since QtQuick.Controls 2.3 (Qt 5.10))

附属物业

group : ButtonGroup

信号

clicked(AbstractButton button) (since QtQuick.Controls 2.1 (Qt 5.8))

方法

void addButton(AbstractButton button)
void removeButton(AbstractButton button)

详细说明

ButtonGroup 是一组非可视、互斥的按钮。它与RadioButton 等控件一起使用，在这些控件中，一次只能选择一个选项。

使用 ButtonGroup 的最直接方法是分配一个按钮列表。例如，定位器的子控件列表或管理一组互斥按钮的布局。

ButtonGroup {
    buttons: column.children
}

Column {
    id: column

    RadioButton {
        checked: true
        text: qsTr("DAB")
    }

    RadioButton {
        text: qsTr("FM")
    }

    RadioButton {
        text: qsTr("AM")
    }
}

互斥按钮并不总是共享相同的父项，或者父布局有时可能包含不应包含在按钮组中的项。在这种情况下，最好使用group 附加属性来处理。

ButtonGroup { id: radioGroup }

Column {
    Label {
        text: qsTr("Radio:")
    }

    RadioButton {
        checked: true
        text: qsTr("DAB")
        ButtonGroup.group: radioGroup
    }

    RadioButton {
        text: qsTr("FM")
        ButtonGroup.group: radioGroup
    }

    RadioButton {
        text: qsTr("AM")
        ButtonGroup.group: radioGroup
    }
}

另一种方法是过滤子代列表。这在使用中继器填充时尤其方便，因为中继器也是父布局的子布局：

ButtonGroup {
    buttons: column.children.filter((child) => child !== repeater)
}

Column {
    id: column

    Repeater {
        id: repeater
        model: [ qsTr("DAB"), qsTr("AM"), qsTr("FM") ]
        RadioButton {
            required property string modelData
            text: modelData
        }
    }
}

使用addButton() 和removeButton() 方法可以处理更高级的用例。

另请参阅 RadioButton 和按钮控件。

属性文档

buttons : list<AbstractButton>

该属性包含按钮列表。

ButtonGroup {
    buttons: column.children
}

Column {
    id: column

    RadioButton {
        checked: true
        text: qsTr("Option A")
    }

    RadioButton {
        text: qsTr("Option B")
    }
}

另请参阅 group 。

checkState : enumeration [since QtQuick.Controls 2.4 (Qt 5.11)]

该属性保存按钮组的组合检查状态。

可用状态：

常量	说明
`Qt.Unchecked`	所有按钮都未选中。
`Qt.PartiallyChecked`	部分按钮已选中。
`Qt.Checked`	所有按钮都被选中。

将非排他性按钮组的检查状态设置为Qt.Unchecked 或Qt.Checked ，可分别取消或检查该组中的所有按钮。Qt.PartiallyChecked 将被忽略。

将排他性按钮组的检查状态设置为Qt.Unchecked 时，将取消对checkedButton 的检查。Qt.Checked 和Qt.PartiallyChecked 将被忽略。

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

checkedButton : AbstractButton

该属性在一个排他性组中保留当前选择的按钮，如果没有该组或该组是非排他性的，则保留null 。

默认情况下，它是添加到排他性按钮组中的第一个选中按钮。

另请参阅 exclusive 。

exclusive : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

该属性表示按钮组是否为独占组。默认值为true 。

如果该属性为true ，则在任何时候都只能选中组中的一个按钮。用户可以单击任何按钮进行选中，该按钮将取代现有按钮成为组中的选中按钮。

在排他性组中，用户不能通过单击当前选中的按钮来取消选中，而是必须单击组中的另一个按钮来设置该组的新选中按钮。

在非排他性组中，选中和取消选中按钮不会影响组中的其他按钮。此外，checkedButton 属性的值是null 。

该属性在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

附加属性文档

ButtonGroup.group : ButtonGroup

该属性将一个按钮附加到一个按钮组。

ButtonGroup { id: group }

RadioButton {
    checked: true
    text: qsTr("Option A")
    ButtonGroup.group: group
}

RadioButton {
    text: qsTr("Option B")
    ButtonGroup.group: group
}

另请参阅 buttons 。

信号文档

[since QtQuick.Controls 2.1 (Qt 5.8)] clicked(AbstractButton button)

该组中的button 被点击时会发出该信号。

该信号便于为同组中的所有按钮实现通用信号处理程序。

ButtonGroup {
    buttons: column.children
    onClicked: button => {
        console.log("clicked:", button.text)
    }
}

Column {
    id: column
    Button { text: "First" }
    Button { text: "Second" }
    Button { text: "Third" }
}

注：相应的处理程序是onClicked 。

该信号在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 AbstractButton::clicked() 。

方法文档

void addButton(AbstractButton button)

添加一个button 到按钮组。

注：手动添加对象到按钮组通常是不必要的。buttons 属性和group 附加属性提供了方便的声明式语法。

另请参阅 buttons 和group 。

void removeButton(AbstractButton button)

从按钮组中删除button 。

注：通常没有必要手动从按钮组中删除对象。buttons 属性和group 附加属性提供了方便的声明式语法。

另请参阅 buttons 和group 。

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