En esta página

Estilo Material

El estilo Material se basa en las directrices de diseño de Google Material Design. Más información...

Declaración de importación: import QtQuick.Controls.Material
Desde: Qt 5.7

Propiedades asociadas

Métodos asociados

  • color color(enumeración predefinida, enumeración tono)

Descripción detallada

El estilo «Material» se basa en las directrices de diseño de Google Material Design. Permite ofrecer una experiencia unificada en todas las plataformas y tamaños de dispositivos.

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 del estilo «Material»

El tema oscuro del estilo Material.

Para ejecutar una aplicación con el estilo Material, consulta «Uso de estilos en los controles de Qt Quick ».

Nota: El estilo Material no es un estilo nativo de Android. El estilo Material es una implementación de estilo de los controles « Qt Quick » 100 % multiplataforma que sigue las directrices de diseño Material de Google. El estilo funciona en cualquier plataforma y tiene un aspecto prácticamente idéntico en todas ellas. Pueden producirse pequeñas diferencias debido a las variaciones en las fuentes del sistema disponibles y en los motores de renderizado de fuentes.

Nota: Dado que las directrices de Material Design cambian con el tiempo, este estilo puede modificar ciertos valores de relleno o de fuente, por ejemplo, con el fin de mantener la coherencia con dichas directrices.

Personalización

El estilo Material admite varios atributos personalizables. Algunos de estos atributos se propagate a los elementos hijos de la misma manera que fonts:

Botones de estilo «Material» que muestran los atributos de tema y elevación

Los demás atributos no se transmiten a los elementos hijos:

En el siguiente ejemplo, la ventana y los tres botones de opción aparecen con el tema oscuro, utilizando un color de acento morado:

import QtQuick
import QtQuick.Controls
import QtQuick.Controls.Material

ApplicationWindow {
    visible: true

    Material.theme: Material.Dark
    Material.accent: Material.Purple

    Column {
        anchors.centerIn: parent

        RadioButton {
            text: qsTr("Small")
        }
        RadioButton {
            text: qsTr("Medium")
            checked: true
        }
        RadioButton {
            text: qsTr("Large")
        }
    }
}

Controles de estilo «Material» con detalles personalizados en color morado

Además de especificar los atributos en QML, también es posible especificar algunos de ellos mediante variables de entorno o en un archivo de configuración. Los atributos especificados en QML tienen prioridad sobre todos los demás métodos.

Archivo de configuración

VariableDescripción
ThemeEspecifica el tema Material predeterminado. El valor puede ser uno de los temas disponibles, por ejemplo, "Dark".
VariantEspecifica la variante de Material. El diseño Material tiene dos variantes: una variante normal diseñada para dispositivos táctiles y una variante «dense» para ordenadores de sobremesa. La variante «dense» utiliza tamaños más pequeños para los controles y sus fuentes.

El valor puede ser « "Normal" » o « "Dense" ».

AccentEspecifica el color de acento predeterminado de Material. El valor puede ser cualquier color, pero se recomienda utilizar uno de los colores predeterminados de Material, por ejemplo, "Teal".
PrimaryEspecifica el color principal predeterminado de Material. El valor puede ser cualquier color, pero se recomienda utilizar uno de los colores predefinidos de Material, por ejemplo, "BlueGrey".
ForegroundEspecifica el color de primer plano predeterminado de Material. El valor puede ser cualquier color o uno de los colores predefinidos de Material, por ejemplo, "Brown".
BackgroundEspecifica el color de fondo predeterminado de Material. El valor puede ser cualquier color o uno de los colores predefinidos de Material, por ejemplo, "Grey".

Consulte el archivo de configuración «Qt Quick Controls» para obtener más detalles sobre el archivo de configuración.

Variables de entorno

VariableDescripción
QT_QUICK_CONTROLS_MATERIAL_THEMEEspecifica el tema Material predeterminado. El valor puede ser cualquiera de los temas disponibles, por ejemplo, "Dark".
QT_QUICK_CONTROLS_MATERIAL_VARIANTEspecifica la variante de Material. El diseño Material tiene dos variantes: una variante normal diseñada para dispositivos táctiles y una variante «dense» para ordenadores de sobremesa. La variante «dense» utiliza tamaños más pequeños para los controles y sus fuentes.

El valor puede ser "Normal" o "Dense".

QT_QUICK_CONTROLS_MATERIAL_ACCENTEspecifica el color de acento predeterminado de Material. El valor puede ser cualquier color, pero se recomienda utilizar uno de los colores predefinidos de Material, por ejemplo, "Teal".
QT_QUICK_CONTROLS_MATERIAL_PRIMARYEspecifica el color principal predeterminado de Material. El valor puede ser cualquier color, pero se recomienda utilizar uno de los colores predefinidos de Material, por ejemplo, "BlueGrey".
QT_QUICK_CONTROLS_MATERIAL_FOREGROUNDEspecifica el color de primer plano predeterminado de Material. El valor puede ser cualquier color o uno de los colores predefinidos de Material, por ejemplo, "Brown".
QT_QUICK_CONTROLS_MATERIAL_BACKGROUNDEspecifica el color de fondo predeterminado de Material. El valor puede ser cualquier color o uno de los colores predefinidos de Material, por ejemplo, "Grey".

Consulte «Variables de entorno compatibles» en «Controles de Qt Quick » para ver la lista completa de variables de entorno compatibles.

Dependencia

El estilo «Material» debe importarse por separado para poder acceder a los atributos específicos de dicho estilo. Cabe señalar que, independientemente de las referencias al estilo «Material», el mismo código de la aplicación se ejecuta con cualquier otro estilo. Los atributos específicos de «Material» solo surten efecto cuando la aplicación se ejecuta con el estilo «Material».

Si el estilo «Material» se importa en un archivo QML que se carga siempre, dicho estilo debe implementarse junto con la aplicación para que esta pueda ejecutarse independientemente del estilo con el que se utilice. Mediante el uso de selectores de archivos, se pueden aplicar ajustes específicos del estilo sin crear una dependencia rígida con respecto a él.

Colores Material predefinidos

Aunque los colores primario y de acento pueden ser cualquier color, se recomienda utilizar uno de los colores predefinidos que se han diseñado para combinar bien con el resto de la paleta del estilo Material:

Colores predefinidos disponibles:

ConstanteDescripción
Material.Red
#F44336
Material.Pink
#E91E63 (color de acento predeterminado)
Material.Purple
#9C27B0
Material.DeepPurple
#673AB7
Material.Indigo
#3F51B5 (color principal predeterminado)
Material.Blue
#2196F3
Material.LightBlue
#03A9F4
Material.Cyan
#00BCD4
Material.Teal
#009688
Material.Green
#4CAF50
Material.LightGreen
#8BC34A
Material.Lime
#CDDC39
Material.Yellow
#FFEB3B
Material.Amber
#FFC107
Material.Orange
#FF9800
Material.DeepOrange
#FF5722
Material.Brown
#795548
Material.Grey
#9E9E9E
Material.BlueGrey
#607D8B

Cuando se utiliza el tema oscuro, se emplean por defecto diferentes tonos de los colores predefinidos:

ConstanteDescripción
Material.Red
#EF9A9A
Material.Pink
#F48FB1 (color de contraste predeterminado)
Material.Purple
#CE93D8
Material.DeepPurple
#B39DDB
Material.Indigo
#9FA8DA (color principal predeterminado)
Material.Blue
#90CAF9
Material.LightBlue
#81D4FA
Material.Cyan
#80DEEA
Material.Teal
#80CBC4
Material.Green
#A5D6A7
Material.LightGreen
#C5E1A5
Material.Lime
#E6EE9C
Material.Yellow
#FFF59D
Material.Amber
#FFE082
Material.Orange
#FFCC80
Material.DeepOrange
#FFAB91
Material.Brown
#BCAAA4
Material.Grey
#EEEEEE
Material.BlueGrey
#B0BEC5

Tonos predefinidos

Hay varios tonos diferentes de cada color predefinido que se pueden pasar a la función Material.color():

ConstanteValor
Material.Shade50
Material.Shade100
Material.Shade200
Material.Shade300
Material.Shade400
Material.Shade500
Material.Shade600
Material.Shade700
Material.Shade800
Material.Shade900
Material.ShadeA100
Material.ShadeA200
Material.ShadeA400
Material.ShadeA700

Véase también Estilo básico, Estilo universal

Variantes

El estilo «Material» también admite una variante «dense», en la que los controles, como los botones y los delegados, tienen una altura menor y utilizan tamaños de fuente más pequeños. Se recomienda utilizar la variante «dense» en plataformas de escritorio, donde el ratón y el teclado permiten una interacción del usuario más precisa y flexible.

Para utilizar la variante «dense», establezca la variable de entorno « QT_QUICK_CONTROLS_MATERIAL_VARIANT » en « Dense » o especifique « Variant=Dense » en el archivo «qtquickcontrols2.conf ». El valor por defecto en ambos casos es « Normal ».

Las siguientes imágenes ilustran las diferencias entre algunos de los controles al utilizar las variantes «normal» y «densa»:

Controles de estilo de material en la variante de tamaño normal

Controles de estilo de material en la variante de tamaño denso

Ten en cuenta que las alturas mostradas arriba pueden variar en función de las diferencias en las fuentes entre plataformas.

Notas específicas sobre los controles

Área de texto

TextArea admite dos estilos de contenedor: « Filled » y « Outlined ». Los TextArea con contorno tienen un texto de marcador de posición flotante que se sitúa en la parte superior del control. Esto hace que el texto de marcador de posición se sitúe fuera de los límites del control, lo que puede provocar que se recorte cuando el « TextArea » o el «Flickable» del que depende establezca « clip » en « true ». Para evitarlo, en estos casos se establece « topInset » en un valor adecuado.

Según las directrices de Material Design, el texto de marcador de posición debe ser breve y no ocupar varias líneas.

TextField

El mismo problema de recorte explicado anteriormente para « TextArea » también puede producirse con « TextField ». Para evitarlo, « topInset » se establece en un valor adecuado cuando el « TextField » fija el recorte en « true ».

Según las directrices de Material, el texto de marcador de posición debe ser breve y no ocupar varias líneas.

Documentación adjunta sobre propiedades

Material.accent: color

Esta propiedad adjunta contiene el color de acento del tema. La propiedad se puede adjuntar a cualquier ventana o elemento. El valor se propaga a los elementos secundarios.

El valor por defecto es Material.Pink.

En el siguiente ejemplo, el color de acento del botón resaltado se cambia a Material.Orange:

Button {
    text: qsTr("Button")
    highlighted: true
    Material.accent: Material.Orange
}

Controles de estilo de materiales que muestran el color de contraste

Nota: Aunque el color de acento puede ser cualquier color, se recomienda utilizar uno de los colores Material predefinidos, que se han diseñado para combinar bien con el resto de la paleta de estilos Material.


Material.background: color

Esta propiedad asociada contiene el color de fondo del tema. La propiedad se puede asociar a cualquier ventana o elemento. El valor se propaga a los elementos secundarios.

El valor por defecto depende del tema (claro u oscuro).

En el siguiente ejemplo, el color de fondo del botón se cambia a Material.Teal:

Button {
    text: qsTr("Button")
    highlighted: true
    Material.background: Material.Teal
}

Controles de estilo «Material» que muestran el color de fondo


Material.elevation: int

Esta propiedad asociada contiene la elevación del control. Cuanto mayor sea la elevación, más profunda será la sombra. La propiedad se puede asociar a cualquier control, pero no todos los controles visualizan la elevación. El valor no se propaga a los elementos secundarios.

El valor por defecto varía según el control.

En el siguiente ejemplo, la elevación del panel se establece en 6 para conseguir el aspecto de una tarjeta elevada:

Pane {
    width: 120
    height: 120

    Material.elevation: 6

    Label {
        text: qsTr("I'm a card!")
        anchors.centerIn: parent
    }
}

Controles de estilo de material que muestran los niveles de cota


Material.foreground: color

Esta propiedad asociada contiene el color de primer plano del tema. La propiedad se puede asociar a cualquier ventana o elemento. El valor se propaga a los elementos secundarios.

El valor por defecto depende del tema (claro u oscuro).

En el siguiente ejemplo, el color de primer plano del botón se establece en Material.Pink:

Button {
    text: qsTr("Button")
    Material.foreground: Material.Pink
}

Botón con primer plano rosa al estilo Material


Material.primary: color

Esta propiedad adjunta contiene el color principal del tema. La propiedad se puede adjuntar a cualquier ventana o elemento. El valor se propaga a los elementos secundarios.

El color principal se utiliza, por defecto, como color de fondo de ToolBar.

El valor por defecto es Material.Indigo.

Nota: Aunque el color principal puede ser cualquier color, se recomienda utilizar uno de los colores Material predefinidos, que se han diseñado para combinar bien con el resto de la paleta de estilos Material.


Material.theme: enumeración

Esta propiedad adjunta indica si el tema es claro u oscuro. La propiedad se puede adjuntar a cualquier ventana o elemento. El valor se propaga a los elementos secundarios.

Temas disponibles:

ConstanteDescripción
Material.LightTema claro (predeterminado)
Material.DarkTema oscuro
Material.SystemTema del sistema

Al configurar el tema como « System », se elige el tema claro u oscuro en función de los colores del tema del sistema. Sin embargo, al leer el valor de la propiedad «theme», el valor nunca es « System », sino el tema real.

En el siguiente ejemplo, el tema tanto del panel como del botón se establece en « Material.Dark »:

Pane {
    Material.theme: Material.Dark

    Button {
        text: qsTr("Button")
    }
}

Panel y botón en el tema oscuro de Material


Material.roundedScale: enumeración

Esta propiedad adjunta contiene el radio de las esquinas redondeadas que se utilizan en el control de destino. La propiedad se puede adjuntar a cualquier ventana o elemento, pero solo algunos controles la admiten. El valor no se propaga a los elementos hijos.

El valor por defecto depende de cada control.

Escalas disponibles:

ConstanteDescripción
Material.NotRoundedEsquinas cuadradas
Material.ExtraSmallScaleEsquinas redondeadas extra pequeñas
Material.SmallScaleEsquinas redondeadas pequeñas
Material.MediumScaleEsquinas redondeadas medianas
Material.LargeScaleEsquinas redondeadas grandes
Material.ExtraLargeScaleEsquinas redondeadas extragrandes
Material.FullScaleEsquinas totalmente redondeadas

Esta propiedad se añadió en Qt 6.5.

Véase también: Estilo Material: Forma.


Material.containerStyle: enumeración

Esta propiedad adjunta contiene el estilo del contenedor utilizado por el control de destino. La propiedad se puede adjuntar a cualquier ventana o elemento, pero solo TextField y TextArea la admiten de forma predeterminada. El valor no se propaga a los elementos hijos.

El valor por defecto depende del control.

Estilos disponibles:

ConstanteDescripción
Material.FilledUtiliza la variante de contenedor relleno si está disponible
Material.OutlinedUtiliza la variante de contenedor con contorno si está disponible

Esta propiedad se añadió en Qt 6.5.

Véase también: Estilo Material: Contenedores de campos de texto.


Documentación del método adjunta

color color(enumeración predefinida, enumeración tono)

Este método adjunto devuelve el valor de color efectivo del color de Material predefinido especificado, combinado con el tono dado. Si se omite, el argumento «tone» toma por defecto el valor « Material.Shade500 ».

Rectangle {
    color: Material.color(Material.Red)
}

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