En esta página

StyleVariation QML Type

Define estilos alternativos para controles específicos. Más información...

Import Statement: import Qt.labs.StyleKit
Inherits:

StylableControls

Status: Technology preview

Este tipo se encuentra en fase de vista previa tecnológica y está sujeto a cambios.

Propiedades

Propiedades adjuntas

Descripción detallada

Una «StyleVariation» te permite definir estilos alternativos que se pueden aplicar a controles específicos de la aplicación (variaciones de instancia) o a todos los descendientes de un tipo de control padre concreto (variaciones de tipo). Por ejemplo, puedes dar a los controles de una barra lateral un aspecto compacto, o hacer que los botones de todas las páginas de toolbars tengan un aspecto diferente al de los botones del resto de la aplicación.

Variaciones de instancia

Las variaciones de instancia se activan estableciendo la propiedad adjunta ` variations ` en cualquier elemento de la aplicación; todos los controles de StyleKit que sean hijos o descendientes de ese elemento recibirán el estilo alternativo. Las variaciones también pueden establecerse simultáneamente en varios niveles de la jerarquía; cuando entran en conflicto, prevalece la variación más cercana al control.

Las variaciones de instancia se definen en el ` Style ` o en el ` Theme ` al que afectan:

Style {
    StyleVariation {
        name: "mini"
        control {
            padding: 2
            background.height: 15
            indicator.width: 15
            indicator.height: 15
            handle.width: 15
            handle.height: 15
        }
    }

    StyleVariation {
        name: "alert"
        abstractButton.background.color: "red"
    }
}

Y se aplican desde la aplicación mediante la propiedad adjunta variations:

GroupBox {
    title: "Mini controls"
    StyleVariation.variations: ["mini"]

    Row {
        spacing: 10
        Button { text: "Save" }
        CheckBox { text: "Option" }
        // This button also has the "alert" variation, in addition to "mini"
        Button {
            text: "Delete"
            StyleVariation.variations: ["alert"]
        }
    }
}

Los nombres de variaciones a los que se hace referencia desde la aplicación y que no están definidos en el estilo (o tema) activo se ignoran de forma silenciosa; actúan como sugerencias que el autor del estilo puede optar por implementar o dejar sin tratar.

Variaciones de tipo

Las variaciones de tipo se asignan a la propiedad ` variations ` de un ` ControlStyle` específico, sin necesidad de un ` name`. A diferencia de las variaciones de instancia —que requieren que la aplicación las active explícitamente—, las variaciones de tipo se aplican automáticamente a todos los controles de un tipo determinado siempre que sean descendientes del tipo de control padre especificado.

El siguiente fragmento de código muestra cómo hacer que todos los Buttons dentro de un Frame tengan un aspecto distinto al de los botones que se encuentran en otras partes:

Style {
    frame {
        variations: StyleVariation {
            button {
                text.color: "ghostwhite"
                background.border.width: 0
                background.color: "slategrey"
            }
        }
    }

    groupBox {
        // groupBox falls back to frame. Therefore, if the varations set on a
        // frame is not wanted on a groupBox, just override it and set it back to [].
        variations: []
    }
}

Dado que groupBox se recurre a frame en la jerarquía de estilos, las variaciones de tipo establecidas en frame también son heredadas automáticamente por groupBox. Para desactivarlas, restablece las variaciones del subtipo.

Orden de propagación

Una StyleVariation es local a Style o Theme, donde se define. Un tema no puede anular por completo una StyleVariation definida en el estilo; solo se pueden sobrescribir las propiedades individuales que contiene, al igual que cualquier otra propiedad de estilo.

Por ejemplo, si tanto el « Style » como el « Theme » activo definen « frame.variations », ambas matrices de variaciones de tipo se aplican a un « Frame ». El orden de resolución para las propiedades individuales es el siguiente: las propiedades de variación del «Theme» tienen prioridad sobre las propiedades directas del «Theme», que a su vez tienen prioridad sobre las propiedades de variación del «Style», las cuales tienen prioridad sobre las propiedades directas del «Style».

Lo mismo se aplica a las variaciones de instancia. Una StyleVariation definida en un Theme tiene prioridad sobre las propiedades directas del tema. Si también se define una StyleVariation con el mismo name en el Style, ambas surten efecto, siguiendo el mismo orden de resolución descrito anteriormente.

En el siguiente fragmento de código, un botón con StyleVariation.variations: ["alert"] será rojo en el tema claro y cian en el tema oscuro, con un borde de 4 píxeles en ambos. Dado que el tema oscuro anula button.background.radius para establecer 6, esa propiedad tiene prioridad sobre el background.radius establecido en la variación del estilo. Como resultado, el radio del botón acaba siendo « 6 » en el tema oscuro, pero « 0 » en el tema claro:

Style {
    button.background.radius: 2
    StyleVariation {
        name: "alert"
        button.background.border.width: 4
        button.background.radius: 0
    }

    light: Theme {
        StyleVariation {
            name: "alert"
            button.background.color: "red"
        }
    }

    dark: Theme {
        button.background.radius: 6
        StyleVariation {
            name: "alert"
            button.background.color: "cyan"
        }
    }
}

Nota: No se garantiza que los tipos de los módulos de Qt.labs sigan siendo compatibles en futuras versiones.

Véase también Style, Theme, ControlStyle.variations y StyleVariation.variations, {StyleKit Property Resolution}.

Documentación de propiedades

name : string

El nombre de esta variante.

El nombre identifica esta variante cuando se utiliza como instance variation.

Véase también « variations » y « Instance Variations ».

Documentación adjunta sobre la propiedad

StyleVariation.controlType : int [attached]

Esta propiedad identifica el control type del elemento al que está asociada.

StyleKit la utiliza para resolver las variaciones de tipo ( type variations ) de los controles descendientes: si la variación de tipo ( controlType ) de un elemento padre coincide con un tipo de control que tiene variaciones de tipo ( variations ) definidas en el tipo de control ( Style), dichas variaciones se aplican a todos los controles descendientes.

Los controles integrados establecen esta propiedad automáticamente. Los controles personalizados deben establecerla explícitamente para participar en la resolución de variaciones de tipo.

Véase también ControlStyle.variations y StyleReader.controlType.

StyleVariation.variations : list<string> [attached]

Esta propiedad contiene la lista de elementos « instance variations » que se deben activar para un « Control » y sus controles descendientes.

Si varias variaciones de la lista establecen la misma propiedad, prevalece la primera de la lista.

Si se establecen variaciones tanto en un elemento padre como en un control descendiente, se aplican ambas configuraciones, y las variaciones propias del control tienen prioridad sobre las heredadas del padre.

GroupBox {
    title: "Mini controls"
    StyleVariation.variations: ["mini"]

    Row {
        spacing: 10
        Button { text: "Save" }
        CheckBox { text: "Option" }
        // This button also has the "alert" variation, in addition to "mini"
        Button {
            text: "Delete"
            StyleVariation.variations: ["alert"]
        }
    }
}

Véase también name.

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