En esta página

Personalización de los controles de Qt Quick

Estilos disponibles

Qt Quick Los controles incluyen una selección de estilos.

Estilo básico

Galería de controles al estilo Basic

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»

Galería de controles en el tema claro de estilo Fusion

El tema claro del estilo «Fusion».

Galería de controles con el tema oscuro de 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»

Galería de controles al 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

Galería de controles en el tema claro al estilo de macOS

El tema claro del estilo macOS.

Galería de controles con el tema oscuro al estilo de 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

Galería de controles en tema claro al estilo iOS

El tema claro del estilo iOS.

Galería de controles con tema oscuro al 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

Galería de controles en el tema claro de estilo Material

El tema claro del estilo Material.

Galería de controles con el tema oscuro de 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

Galería de controles en el tema claro de estilo Universal

El tema claro del estilo Universal.

Galería de controles con tema oscuro de 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

Galería de controles al estilo de 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

Galería de controles con el tema claro del estilo FluentWinUI3

El tema claro del estilo FluentWinUI3.

Galería de controles con el tema oscuro al 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:

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 auto

La 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.Controls

El complemento « QtQuick.Controls » importará el estilo establecido en tiempo de ejecución mediante uno de los siguientes métodos:

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:

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.Controls y luego QtQuick.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 Material

Variable 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 ./app

Consulte «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=Material

Consulte «Archivo de configuración de los controlesQt Quick » para obtener más detalles sobre el archivo de configuración.

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