Resolución de propiedades de StyleKit
Una propiedad de estilo —como background.color — puede tener muchos valores diferentes en función del state del control, del Theme activo y del style variations efectivo. Por ejemplo, puede variar entre los estados pressed y hovered, o entre los temas light y dark. Este documento detalla cómo StyleKit resuelve el valor que adoptará una propiedad cuando se utilice para aplicar estilos a un Control concreto.
Estados de los controles
Los controles cambian de aspecto en función de la interacción: hovered, pressed, checked, focused, disabled, etc. Al resolver una propiedad, StyleKit agota primero todos los valores específicos de cada estado, antes de comprobar el estado normal.
Por ejemplo, si un « Button » es « hovered », se comprueba « hovered.button.background.color » antes que « button.background.color ». Y si además es « pressed », se comprueba « pressed.button.background.color » antes que ambos. El orden de prioridad entre los estados se documenta en ControlStateStyle documentation.
Los estados también pueden anidarse. Una combinación como pressed.hovered.button.background.color es más específica que cualquiera de las dos opciones por separado ( pressed.button.background.color o hovered.button.background.color ) y tiene prioridad sobre ambas.
Propiedades de reserva
Algunas propiedades de estilo pueden establecerse de más de una forma. Por ejemplo, el radio de la esquina superior izquierda del fondo puede establecerse directamente mediante background.topLeftRadius, o indirectamente mediante background.radius (que establece el mismo radio en todas las esquinas). Para este tipo de propiedades, StyleKit comprueba primero la propiedad específica, luego la alternativa, y agota ambas en el estado actual antes de pasar a un estado menos específico. Por ejemplo, button.hovered.background.radius tiene prioridad sobre button.background.topLeftRadius si se pasa el cursor por encima del control. Y, por supuesto, button.hovered.background.topLeftRadius tiene prioridad sobre ambas.
Jerarquía de tipos de control
The controls forman una jerarquía. Un « button » recurre a « abstractButton », que a su vez recurre a « control ». Un « groupBox » recurre a « frame », que recurre a « pane », que a su vez recurre a « control », y así sucesivamente. « control » es el tipo raíz de la jerarquía, reflejando la jerarquía de tipos de los controles deQt Quick . Consulte la « documentation » de cada tipo de control para ver su tipo de recurso alternativo directo.
Cuando se han agotado todos los estados y propiedades de reserva para un tipo de control específico, StyleKit remonta la jerarquía para comprobar si está establecido en un tipo base. Por ejemplo, si button.background.color no está establecido, StyleKit comprobará abstractButton.background.color en su lugar, y así sucesivamente. Esto anima al diseñador a agrupar los valores de las propiedades que son comunes a varios controles en un tipo base común, con el fin de maximizar la reutilización y minimizar la duplicación. Por ejemplo, puedes colocar todos los valores de las propiedades comunes a los botones, casillas de selección y botones de opción en abstractButton, y establecer únicamente las propiedades que difieren en los subtipos específicos.
Ten en cuenta que cualquier estado (incluido el estado normal) de un tipo más específico tiene prioridad sobre cualquier estado de un tipo base. Por ejemplo, ` button.background.color ` tiene prioridad sobre ` hovered.abstractButton.background.color`, incluso si el cursor pasa por encima del control. Y, por supuesto, ` hovered.button.background.color ` tiene prioridad sobre ambos.
Estilo y tema
La jerarquía de tipos de control se repite tanto dentro de un ` Style ` como de un ` Theme`. Al resolver una propiedad, ` StyleKit ` examina primero la jerarquía de tipos de control en el tema activo ` Theme` y, a continuación, en el estilo activo ` Style`. Esto significa que las propiedades establecidas en el tema activo tienen prioridad sobre las establecidas en el estilo. En consecuencia, un tipo base del tema también anula un tipo más específico del estilo. Por ejemplo, theme.control.background.color tiene prioridad sobre style.button.background.color.
Variaciones de estilo
La jerarquía de tipos de control se repite dentro de un ` StyleVariation`. Las variaciones de estilo pueden definirse tanto en un estilo como en un tema, y una variación de estilo en un tema tiene prioridad sobre el propio tema. Dado que un tema tiene prioridad sobre un estilo, las propiedades de estilo del tema actual también tendrán prioridad sobre las variaciones de estilo del estilo. Por ejemplo, theme.button.background.color tiene prioridad sobre style.variation.button.background.color.
Estilo de reserva
Cada « Style » tiene un « fallback style », es decir, un estilo completo que actúa como último recurso cuando no se puede resolver una propiedad dentro del estilo activo. Si el proceso completo de resolución (que abarca los tipos de control, los estados, el tema activo y cualquier variación de estilo) no logra encontrar un valor, StyleKit repite todo el proceso en el estilo de reserva. El estilo de reserva predeterminado es similar al estilo básico, por lo que incluso un estilo vacío seguirá generando controles con un estilo completo.
El estilo de reserva puede tener a su vez un estilo de reserva, y StyleKit sigue esta cadena de forma recursiva hasta que encuentra un valor o agota la cadena. Si no se encuentra ningún valor, se utiliza un valor por defecto.
Poniéndolo todo en práctica
A modo de ejemplo, supongamos que StyleKit necesita resolver background.color para un hovered Button . El estilo tiene un tema, y tanto el estilo como el tema tienen una variación activa. StyleKit comprueba entonces las siguientes ubicaciones por orden, utilizando el primer valor que encuentre:
theme.variation.hovered.button.background.colortheme.variation.button.background.colortheme.variation.hovered.abstractButton.background.colortheme.variation.abstractButton.background.colortheme.variation.hovered.control.background.colortheme.variation.control.background.colortheme.hovered.button.background.colortheme.button.background.colortheme.hovered.abstractButton.background.colortheme.abstractButton.background.colortheme.hovered.control.background.colortheme.control.background.colorstyle.variation.hovered.button.background.colorstyle.variation.button.background.colorstyle.variation.hovered.abstractButton.background.colorstyle.variation.abstractButton.background.colorstyle.variation.hovered.control.background.colorstyle.variation.control.background.colorstyle.hovered.button.background.colorstyle.button.background.colorstyle.hovered.abstractButton.background.colorstyle.abstractButton.background.colorstyle.hovered.control.background.colorstyle.control.background.color
Si se agotan todas estas ubicaciones sin encontrar un valor, se repite el mismo proceso en el estilo de reserva (de forma recursiva, si el estilo de reserva también tiene un estilo de reserva). Si aún así no se encuentra, se utiliza un valor por defecto.
Depuración de la resolución de propiedades
Dado que hay múltiples tipos de controles, temas, variaciones y estilos de reserva que contribuyen al valor final de una propiedad, a veces puede resultar difícil determinar por qué un control concreto acaba teniendo una apariencia determinada. « StyleKitDebug » es una herramienta de diagnóstico integrada en la aplicación que registra cada propiedad de estilo leída en la salida de depuración, mostrando exactamente de qué capa y tipo de control se ha resuelto una propiedad.
Para iniciar el seguimiento, asigna el control que deseas analizar a la propiedad ` StyleKit.debug.control `:
ApplicationWindow {
id: app
width: 1024
height: 800
visible: true
StyleKit.debug.control: someButton
StyleKit.debug.filter: "background.color"
StyleKit.style: Style {
button {
background.color: "gray"
hovered.background.color: "dimgray"
}
dark: Theme {
button {
background.color: "skyblue"
hovered.background.color: "lightblue"
}
}
}
Column {
anchors.fill: parent
anchors.margins: 10
spacing: 10
Button {
id: someButton
text: "A Button"
}
}
}Cada propiedad resuelta se muestra en una línea individual, por ejemplo:
[read] StyleReader[Hovered].button.background.color -> Style.Theme(Dark).button[Hovered] = #add8e6El « StyleReader » de la salida hace referencia al « StyleReader » que el « Button » utiliza internamente para leer los valores de sus propiedades de estilo.
Utiliza la propiedad ` filter ` para limitar la salida a las propiedades de interés.
Nota: Habilitar « StyleKitDebug » reducirá considerablemente el rendimiento. Úsalo solo durante la depuración.
Véase también « Style» , « Theme », « StyleVariation », « StyleKitDebug » y «Descripción general de las características de StyleKit».
© 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.