Personalización de los controles de Qt Quick
Estilos disponibles
Qt Quick Los controles incluyen una selección de estilos.
Estilo básico

El estilo básico es un estilo sencillo, ligero y versátil que ofrece el máximo rendimiento para los controles de Qt Quick.
Estilo «Fusion»
El tema claro del estilo «Fusion». |
El tema oscuro del estilo «Fusion». |
El estilo «Fusion» es un estilo independiente de la plataforma que ofrece una apariencia orientada al escritorio para los controles de Qt Quick.
Estilo «Imagine»

El estilo Imagine se basa en recursos gráficos. El estilo incluye un conjunto predeterminado de imágenes que se puede cambiar fácilmente proporcionando un directorio con imágenes que sigan una convención de nomenclatura predefinida.
Estilo macOS
El tema claro del estilo macOS. |
El tema oscuro del estilo macOS. |
El estilo macOS es un estilo con aspecto nativo para macOS.
Nota: este estilo solo está disponible para aplicaciones que se ejecutan en macOS.
Estilo iOS
El tema claro del estilo iOS. |
El tema oscuro del estilo iOS. |
El estilo iOS es un estilo con aspecto nativo para iOS basado en recursos gráficos.
Nota: este estilo solo está disponible para aplicaciones que se ejecutan en iOS.
Estilo Material
El tema claro del estilo Material. |
El tema oscuro del estilo Material. |
El estilo Material ofrece un diseño atractivo basado en las directrices de Google Material Design, pero requiere más recursos del sistema que el estilo básico.
Estilo universal
El tema claro del estilo Universal. |
El tema oscuro del estilo «Universal». |
El estilo «Universal» ofrece un diseño atractivo basado en las directrices de diseño universal de Microsoft, pero requiere más recursos del sistema que el estilo «Básico».
Estilo Windows

El estilo Windows es un estilo con aspecto nativo para Windows.
Nota: este estilo solo está disponible para aplicaciones que se ejecutan en Windows.
Estilo FluentWinUI3
El tema claro del estilo FluentWinUI3. |
El tema oscuro del estilo FluentWinUI3. |
El estilo FluentWinUI3 es un estilo moderno con aspecto nativo diseñado para plataformas que ejecutan Windows 11 y versiones posteriores, y que sigue las directrices de diseño de Fluent UI y WinUI 3. FluentWinUI3 se puede ejecutar en todas las plataformas compatibles.
Uso de estilos en los controles de « Qt Quick »
Estilos predeterminados
Si no se establece ningún estilo de forma explícita, se utilizará un estilo predeterminado. El estilo que se utilice dependerá del sistema operativo:
- Android: estilo Material
- iOS: Estilo iOS
- Linux: Estilo Fusion
- macOS: Estilo de macOS
- Windows: Estilo Windows
Para el resto de sistemas operativos, se utiliza el estilo básico.
Selección de estilo en tiempo de compilación
La selección de estilo en tiempo de compilación es una forma de especificar el estilo que se va a utilizar importándolo directa o indirectamente en QML. Dado que se selecciona en tiempo de compilación, no es posible cambiar el estilo en tiempo de ejecución si se utiliza la selección de estilo en tiempo de compilación.
La forma más cómoda de utilizar la selección de estilo en tiempo de compilación es importar el estilo «QtQuick.Controls.Native ». A su vez, « QtQuick.Controls.Native » importa el estilo predeterminado para la plataforma de destino. Si importas « QtQuick.Controls.Native », no debes importar ningún otro estilo específico, ni el módulo « QtQuick.Controls » (seleccionado en tiempo de ejecución). « QtQuick.Controls.Native » importa automáticamente el estilo predeterminado de la plataforma y ese estilo se encarga de su alternativa. No puedes tener más de un estilo de nivel superior al mismo tiempo. Por ejemplo:
// Refrain from importing QtQuick.Controls or specific styles.
import QtQuick.Controls.Native
ApplicationWindow {
// ...
}Sin embargo, también puedes importar un estilo específico en tiempo de compilación, sin tener en cuenta los valores predeterminados de la plataforma. Por ejemplo, para importar el estilo Material:
// The style must be imported before any other QtQuick.Controls imports
// in order for run-time style selection API like QQuickStyle::name() to
// work.
import QtQuick.Controls.Material
ApplicationWindow {
// ...
}Fíjate en que no se importa « QtQuick.Controls » (que se encarga de la selección de estilos en tiempo de ejecución). El estilo de reserva viene determinado por el «qmldir» del estilo:
module QtQuick.Controls.Material
# ...
import QtQuick.Controls.Basic autoLa ventaja de la selección de estilos en tiempo de compilación es que el compilador de QML sabe qué estilo específico se está utilizando y puede generar código C++ para los enlaces.
Otra ventaja es que no se utiliza el complemento QtQuick.Controls y, por lo tanto, no es necesario implementarlo junto con la aplicación.
Las importaciones explícitas también son necesarias si la aplicación se compila de forma estática.
Una desventaja de la selección de estilos en tiempo de compilación es que un ejecutable no puede admitir varios estilos, ya que cada estilo requiere el suyo propio.
Consulta «Combinación de la selección de estilos » para obtener información sobre cómo combinar la selección de estilos en tiempo de compilación y en tiempo de ejecución.
Selección de estilo en tiempo de ejecución
La selección de estilo en tiempo de ejecución es una forma de especificar el estilo que se va a utilizar importando QtQuick.Controls:
import QtQuick.ControlsEl complemento « QtQuick.Controls » importará el estilo establecido en tiempo de ejecución mediante uno de los siguientes métodos:
- QQuickStyle::setStyle()
- El argumento de línea de comandos `
-style` - La variable de entorno QT_QUICK_CONTROLS_STYLE
- El archivo de configuración `qtquickcontrols2.conf`
La prioridad de estos métodos sigue el orden en que aparecen, de mayor a menor. Es decir, utilizar QQuickStyle para establecer el estilo siempre tendrá prioridad sobre el uso del argumento de línea de comandos, por ejemplo.
Del mismo modo, el estilo por defecto se puede establecer mediante uno de los siguientes métodos:
- QQuickStyle::setFallbackStyle()
- La variable de entorno QT_QUICK_CONTROLS_FALLBACK_STYLE
- El archivo de configuración `qtquickcontrols2.conf`
Nota: solose puede elegir dinámicamente el estilo de reserva si no se ha seleccionado de forma estática en el archivo qmldir del estilo principal.
La ventaja de la selección de estilos en tiempo de ejecución es que un único binario de la aplicación puede admitir varios estilos, lo que significa que el usuario final puede elegir con qué estilo ejecutar la aplicación.
Una desventaja de este enfoque es que el compilador de QML no puede saber qué estilo específico se está utilizando y, por lo tanto, no puede generar código C++ para los enlaces a las propiedades de los tipos de controles de « Qt Quick ». Esto no afecta a la capacidad del compilador de QML para generar código C++ para los enlaces a tipos de otros módulos.
Consulta «Selección mixta de estilos » para obtener información sobre cómo combinar la selección de estilos en tiempo de ejecución y en tiempo de compilación.
API específicas de cada estilo
Varios estilos exponen API específicas de ese estilo, por ejemplo, el objeto asociado al estilo «Material» o el objeto asociado al estilo «Universal ». Estas API específicas de cada estilo solo están disponibles cuando dicho estilo está realmente seleccionado, ya sea de forma directa o indirecta, mediante la selección de estilo en tiempo de compilación o en tiempo de ejecución.
Combinación de la selección de estilos
Se recomienda utilizar únicamente la selección de estilo en tiempo de compilación o en tiempo de ejecución en su aplicación. Sin embargo, si su aplicación carga código QML de terceros, por ejemplo, puede que no sea posible controlar qué importaciones se utilizan. Si combina ambos enfoques, tenga en cuenta las siguientes limitaciones:
- La selección de estilos en tiempo de compilación anula la selección de estilos en tiempo de ejecución.
- El estilo que desees utilizar debe importarse siempre de forma explícita antes que cualquier otra importación de controles. Si no lo haces, la personalización (como las fuentes y las paletas) no funcionará como se espera. El primer estilo importado explícitamente es también el que indicará la función ` QQuickStyle::name()`.
- El último estilo importado explícitamente es el que se utilizará realmente. Por ejemplo, si importas primero
QtQuick.Controlsy luegoQtQuick.Controls.Material, se utilizará el archivo Button.qml del estilo Material cuando se cree un botón. Debido al punto anterior sobre la personalización de temas, por esta razón nunca debes importar explícitamente dos estilos diferentes en la misma aplicación. - Si tienes intención de utilizar la selección de estilos en tiempo de compilación pero cargas código que importa
QtQuick.Controls, ten en cuenta que llamar a QQuickStyle::name() antes de que se haya importado explícitamente un estilo hará que se utilice el estilo predeterminado de la plataforma. Si no puedes evitarlo, configura el estilo para que coincida con el de tiempo de compilación de antemano mediante QQuickStyle::setStyle() o cualquiera de las otras formas enumeradas en «Selección de estilos en tiempo de ejecución».
Uso de QQuickStyle en C++
QQuickStyle proporciona una API de C++ para configurar un estilo específico. El siguiente ejemplo ejecuta una aplicación de controles de Qt Quick con el estilo «Material»:
QQuickStyle::setStyle("Material");Consulta la descripción detallada de QQuickStyle para obtener más información.
Argumento de línea de comandos
Pasar un argumento de línea de comandos de « -style » es la forma más cómoda de probar diferentes estilos. Tiene prioridad sobre los demás métodos que se enumeran a continuación. El siguiente ejemplo ejecuta una aplicación de controles « Qt Quick » con el estilo «Material»:
./app -style MaterialVariable de entorno
La configuración de la variable de entorno « QT_QUICK_CONTROLS_STYLE » permite establecer una preferencia de estilo para todo el sistema. Tiene prioridad sobre el archivo de configuración que se menciona a continuación. El siguiente ejemplo ejecuta una aplicación de Qt Quick Controls con el estilo «Universal»:
QT_QUICK_CONTROLS_STYLE=Universal ./appConsulte «Variables de entorno compatibles» en Qt Quick Controls para obtener la lista completa de variables de entorno compatibles.
Archivo de configuración
Qt Quick Los controles admiten un archivo de configuración especial, :/qtquickcontrols2.conf, que está integrado en los recursos de la aplicación.
El archivo de configuración puede especificar el estilo preferido (que puede anularse mediante cualquiera de los métodos descritos anteriormente) y determinados atributos específicos del estilo. El siguiente ejemplo especifica que el estilo preferido es el estilo «Material».
[Controls]
Style=MaterialConsulte «Archivo de configuración de los controlesQt Quick » para obtener más detalles sobre el archivo de configuración.
Información relacionada
- Estilo básico
- Estilo Fusion
- Estilo «Imagine»
- Estilo «Material»
- Estilo universal
- Estilo FluentWinUI3
- Personalización de los controles de « Qt Quick »
- Uso de selectores de archivos con los controles de « Qt Quick »
- Implementación de aplicaciones con controles de Qt Quick
- Qt Quick Archivo de configuración de los controles
- Variables de entorno compatibles con los controles de « Qt Quick »
© 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.











