En esta página

Enfoques de estilo para Qt Widgets

Qt Widgets ofrece tres formas de modificar el aspecto de los widgets:

  • Un « style » dibuja cada widget. Subclasifica ` QProxyStyle ` para ajustar el estilo de la plataforma, o ` QCommonStyle ` para implementar un aspecto personalizado completo. Este es el mecanismo que utilizan los propios estilos de Qt, y el que se debe emplear en aplicaciones de producción.
  • StyleKit describe un diseño de forma declarativa en QML y lo aplica a los widgets a través de ` QStyleKitStyle`, una implementación de ` QStyle `. El mismo archivo de estilo también aplica estilos a los controles ` Qt Quick `.
  • Las hojas de estilo anulan propiedades visuales individuales mediante reglas similares a las de CSS. Son una herramienta para la creación de prototipos y para pequeños ajustes locales, no para el aspecto definitivo de una aplicación.

En esta página se explica qué implica cada enfoque y cuándo elegirlo.

Elige un enfoque

La siguiente tabla relaciona un objetivo de estilo con el mecanismo que mejor se adapta a él.

ObjetivoEnfoque
Mantener el aspecto nativo pero cambiar algunos detalles, como una medida, un color o una sugerencia de estiloUna subclase de ` QProxyStyle `
Dar a la aplicación un aspecto propio, independiente del estilo de la plataforma, por ejemplo, en un dispositivo integradoUna subclase de ` QCommonStyle ` o un estilo de StyleKit
Compartir un diseño entre los controles de « Qt Widgets » y « Qt Quick »Un estilo de StyleKit
Ofrecer variantes clara y oscura del mismo diseñoUn « QPalette » diferente para el mismo estilo, o un tema de StyleKit
Probar colores, bordes y espaciado rápidamente, o cambiar el estilo de un único widget durante el desarrolloUna hoja de estilo

Implementar un estilo para aplicaciones de producción

Una subclase de ` QStyle ` dibuja los widgets directamente con ` QPainter`, utilizando la información del ` QStyleOption ` que cada widget pasa al estilo. Un estilo tiene control total sobre cada elemento, desde el bisel de un botón hasta las ramas de una vista de árbol, y ejerce ese control con el coste de una operación de dibujo ordinaria: no hay reglas que hacer coincidir ni estado por widget que recalcular.

Elige la clase base en función de cuánto quieras modificar:

  • QProxyStyle envuelve otro estilo —por defecto, el estilo de la plataforma— y te permite sobrescribir funciones seleccionadas como ` drawPrimitive()`, ` pixelMetric()` o ` styleHint()`. Todo lo que no sobrescribas conserva el aspecto y el comportamiento nativos. Úsalo para ajustar el estilo de la plataforma.
  • QCommonStyle implementa el comportamiento que comparten todos los estilos de Qt y te deja a ti la tarea de dibujar. Úsalo como base para crear un aspecto totalmente personalizado. La sección «Estilos y widgets sensibles al estilo » repasa los elementos de estilo y muestra cómo se dibuja cada widget.

Establece el estilo una sola vez, antes de que la aplicación cree sus ventanas:

#include <QtWidgets>

#include "customstyle.h"

int main(int argc, char *argv[])
{
    QApplication::setStyle(new CustomStyle);
    QApplication app(argc, argv);
    QSpinBox spinBox;
    spinBox.show();
    return app.exec();
}

Dibuja con los colores de la paleta « QPalette » en la opción de estilo, en lugar de con colores codificados de forma fija. De este modo, el mismo estilo genera una variante clara y otra oscura del diseño a partir de dos paletas, sin necesidad de cambiar de estilo. El estilo «Fusion» de Qt funciona así.

Para que los usuarios puedan seleccionar el estilo desde la línea de comandos con la opción « -style », o para compartirlo entre aplicaciones, crea el estilo como un complemento. Consulta « QStylePlugin » y «How to Create Qt Plugins».

Describe el diseño en QML con StyleKit

StyleKit es un sistema de estilos declarativo. Un estilo es un archivo QML cuyo objeto raíz es un ` Style`, que establece colores, tamaños, radios, bordes y variaciones dependientes del estado para cada tipo de control. Las propiedades se propagan a través de una jerarquía de controles, por lo que un valor establecido una vez en ` abstractButton ` se aplica a todo tipo de botones, y un estilo puede definir varios temas con nombre.

QStyleKitStyle es una implementación de ` QStyle ` que lee dicho estilo y dibuja los widgets con ` QPainter`. ` Qt Quick ` no interviene en la representación. El mismo archivo ` Style ` también aplica estilos a los controles de ` Qt Quick `, por lo que una aplicación que utilice ambos kits de herramientas mantiene una única definición de diseño. Los temas definidos en el estilo se seleccionan con ` setThemeName()`.

auto *style = new QStyleKitStyle(QStringLiteral(":/styles/MyStyle.qml"));
QApplication::setStyle(style);

QStyleKitStyle está disponible desde Qt 6.12. StyleKit es un módulo de Qt Labs, y su API puede cambiar entre las distintas versiones de Qt. El ejemplo «StyleKit Widgets» muestra una aplicación de widgets con varios estilos y temas de StyleKit.

Utiliza hojas de estilo para la creación de prototipos

Las hojas de estilo de Qt modifican la apariencia de los widgets mediante reglas en una sintaxis similar a la de CSS, sin necesidad de escribir código en C++. Resultan muy prácticas para probar un diseño: basta con editar un archivo .qss y reiniciar la aplicación, o bien pasar el archivo con la opción de línea de comandos -stylesheet, y Qt Widgets Designer se previsualizarán las mismas reglas. También son la forma más rápida de resaltar un único widget, como un campo obligatorio con fondo amarillo.

Las hojas de estilo tienen unos costes que las hacen inadecuadas como mecanismo de estilo para una aplicación en producción:

  • Cada widget afectado se dibuja a través del motor de hojas de estilo. Cuando se establece una hoja de estilo, QWidget::style() devuelve un estilo de hoja de estilo que envuelve el style subyacente. Para cada widget, compara los selectores con la clase, el nombre del objeto, las propiedades y el estado del widget, calcula las reglas de representación y las almacena en caché por widget. El consumo de memoria y el coste de procesamiento aumentan con el número de widgets y reglas.
  • Al cambiar una hoja de estilo, se vuelve a aplicar el estilo a todo aquello a lo que se aplica. Cada llamada a ` QApplication::setStyleSheet()` descarta las cachés y vuelve a aplicar el estilo a todos los widgets de la aplicación, lo que recalcula las fuentes, las paletas, la geometría y las indicaciones de tamaño, y puede provocar un parpadeo visible. No bases el cambio de tema en hojas de estilo.
  • Una regla parcial descarta el aspecto nativo. Cuando una regla solicita algo que el estilo nativo no puede cumplir, como un color de fondo para un QPushButton, el motor de hojas de estilo dibuja él mismo todo el elemento, sin la decoración nativa. Entonces tienes que especificar tú mismo los bordes, el relleno y cada estado, y un pequeño ajuste se convierte en una descripción completa del aspecto. Consulta «Personalización de Qt Widgets mediante hojas de estilo».
  • Los selectores vinculan el diseño a los detalles de implementación. Las reglas coinciden con nombres de clases, nombres de objetos y valores de propiedades. Cambiar el nombre de un objeto o sustituir una clase de widget impide de forma implícita que la regla coincida. Las reglas no afectan a los widgets personalizados que se dibujan sin el estilo.
  • Las hojas de estilo prevalecen sobre la configuración mediante programación. Una hoja de estilo anula las fuentes, las paletas y los colores de los elementos establecidos con funciones como QWidget::setFont() o QTreeWidgetItem::setBackground(), por lo que el estilo de un widget ya no es visible en un único lugar.

Para ver una comparación detallada entre las hojas de estilo y las subclases de ` QStyle `, consulta el artículo de KDAB «Say No to Qt Style Sheets».

Si, a pesar de todo, utilizas hojas de estilo

Para un prototipo, o para los pocos ajustes locales que necesite una aplicación en producción, mantén la hoja de estilos manejable:

  • Guarda las reglas en un archivo « .qss », integrado en el sistema de recursos de Qt. Configúralo una sola vez en la aplicación con ` QApplication::setStyleSheet()` antes de que se muestre la primera ventana, y déjalo tal cual. Reserva ` QWidget::setStyleSheet()` para ajustes que sean verdaderamente locales a un widget y sus hijos.
  • No crees hojas de estilo a partir de cadenas de C++. Una hoja de estilo aplicada a un widget se analiza una vez por cada widget al que se le aplique, no una vez por cada cadena, y cada llamada a QWidget::setStyleSheet() actualiza el widget y todos sus hijos, incluso cuando la cadena no haya cambiado. Una cadena creada con QString::arg() para reflejar datos, como un borde rojo para un valor no válido, actualiza el widget en cada actualización. En su lugar, expresa la diferencia mediante un selector sobre el nombre de un objeto o una propiedad de Qt en una única hoja de estilo, y reevalúala tal y como se describe en «Personalización mediante propiedades dinámicas».
  • No codifiques colores de forma fija. Un color literal como #ffffff solo se adapta a un tema. Utiliza palette(window), palette(text) y las demás funciones de la paleta para que la hoja de estilo siga la paleta de la aplicación, incluido un esquema de colores oscuros.
  • No defina todos los tamaños en píxeles. Un valor de « px » se adapta al tamaño de la pantalla, pero no al tipo de letra del usuario. Utilice longitudes de « em » y « ex » para los rellenos, los márgenes y los tamaños que deban adaptarse al tipo de letra, y « pt » para los tamaños de letra.

Pasar de una hoja de estilo a un estilo

Cuando un prototipo se convierte en un producto, transfiere el diseño a un estilo. La mayoría de los elementos de las hojas de estilo tienen un equivalente directo:

Hoja de estiloQStyleStyleKit
ColoresQPalette roles, leídos a partir de QStyleOption::palettelas propiedades de color del control o de un tema
border, padding, marginpixelMetric() y subElementRect()Propiedades de borde y tamaño del control
Pseudoestados como :hover y :pressedQStyle::State indicadores en QStyleOption::stateGrupos de estados como hovered y pressed
subcontroles como ::indicatordrawPrimitive() y drawControl() para el elementoPropiedades delegadas como indicator

Véase también «Estilos y widgets sensibles al estilo», « QStyle », « QProxyStyle », « QCommonStyle », «Qt Labs StyleKit» y «Hojas de estilo de Qt».

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