En esta página

CheckBox QML Type

Botón de selección que se puede activar o desactivar. Más...

Import Statement: import QtQuick.Controls
Inherits:

AbstractButton

Propiedades

Descripción detallada

CheckBox presenta un botón de opción que se puede activar (marcado) o desactivar (sin marcar). Las casillas de verificación se suelen utilizar para seleccionar una o varias opciones de entre un conjunto de opciones. Para conjuntos de opciones más amplios, como los que aparecen en una lista, se recomienda utilizar en su lugar CheckDelegate.

CheckBox hereda su API de ` AbstractButton`. Por ejemplo, el estado de la casilla de selección se puede establecer mediante la propiedad ` checked `.

Además de los estados «marcado» y «desmarcado», existe un tercer estado: «parcialmente marcado». El estado «parcialmente marcado» se puede habilitar mediante la propiedad ` tristate `. Este estado indica que no se puede determinar el estado habitual de marcado o desmarcado; generalmente debido a otros estados que afectan a la casilla de selección. Este estado resulta útil cuando se seleccionan varios nodos secundarios en una vista de árbol, por ejemplo.

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

Los grupos jerárquicos de casillas de selección se pueden gestionar con una propiedad ` ButtonGroup` no exclusiva.

Conjunto de casillas de selección para selección múltiple

El siguiente ejemplo ilustra cómo se puede vincular el estado de selección combinado de los elementos hijos al estado de selección de la casilla de verificación principal:

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

Véase también Personalización de los controlesCheckBox, ButtonGroup y Button.

Documentación de propiedades

checkState : enumeration

Esta propiedad almacena el estado de selección de la casilla de verificación.

Estados disponibles:

ConstanteDescripción
Qt.UncheckedLa casilla de selección no está marcada.
Qt.PartiallyCheckedLa casilla de selección está parcialmente marcada. Este estado solo se utiliza cuando está activada la opción « tristate » (La casilla de selección no puede estar parcialmente marcada).
Qt.CheckedLa casilla está marcada.

Véase también « tristate » y « checked ».

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

Esta propiedad contiene una función de devolución de llamada que se ejecuta para determinar el siguiente estado de la casilla de selección cada vez que el usuario la activa o desactiva de forma interactiva mediante el tacto, el ratón o el teclado.

Por defecto, una casilla de selección normal alterna entre los estados « Qt.Unchecked » y « Qt.Checked », mientras que una casilla de selección de tres estados alterna entre los estados « Qt.Unchecked », « Qt.PartiallyChecked » y « Qt.Checked ».

La función de llamada de retorno nextCheckState puede anular el comportamiento predeterminado. El siguiente ejemplo implementa una casilla de selección de tres estados que puede presentar un estado parcialmente marcado en función de condiciones externas, pero que nunca pasa al estado parcialmente marcado cuando el usuario la activa o desactiva de forma interactiva.

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

Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).

tristate : bool

Esta propiedad indica si la casilla de selección es de tres estados.

En la animación siguiente, la primera casilla de selección es de tres estados:

El valor predeterminado es « false », es decir, la casilla de verificación solo tiene dos estados.

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