ButtonGroup QML Type

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

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

属性

• 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
    }
}

另一种方法是对子项列表进行过滤。如果您使用重复器（repeater）来填充该列表，此方法尤为实用，因为重复器本身也是父布局的子项：

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.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 [attached]

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

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" }
}

该信号在 QtQuick.Controls 2.1（Qt 5.8）中引入。

另请参阅 AbstractButton::clicked()。

方法文档

void addButton(AbstractButton button)

将一个button 添加到按钮组中。

另请参阅 buttons 和group 。

void removeButton(AbstractButton button)

从按钮组中移除一个button 。

另请参阅 buttons 和group 。