StyleVariation QML Type

定义特定控件的替代样式。更多

Import Statement:	`import Qt.labs.StyleKit`
Inherits:	AbstractStylableControls

所有成员（包括继承成员）的列表

属性

name : string

附属物业

controlType : int
variations : list<string>

详细说明

StyleVariation 可让您定义可应用于应用程序中特定控件（实例变化）或特定父控件类型的所有子控件（类型变化）的其他样式。例如，您可以给侧边栏中的控件一个紧凑的外观，或者让所有toolbars 中的按钮看起来与其他地方的按钮不同。

实例变化

通过在应用程序中的任何项目上设置variations 附加属性，可以激活实例变体--作为该项目子项或子孙的所有StyleKit 控件都将获得替代样式。也可同时在层次结构的多个层级设置变化；当它们发生冲突时，最接近控件的变化将优先。

实例变化在其影响的Style 或Theme 中定义：

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

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

使用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"]
        }
    }
}

应用程序中引用的变体名称如果未在活动样式（或主题）中定义，则会被静默忽略--它们作为提示，样式作者可以选择执行或不处理。

类型变化

类型变化被分配给特定ControlStyle 的variations 属性，无需name 。与实例变化（需要应用程序显式选择加入）不同，只要是指定父控件类型的子控件，类型变化都会自动应用于给定类型的所有控件。

下面的代码段展示了如何使Frame 中的所有Buttons 看起来与其他地方的按钮不同：

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: []
    }
}

由于groupBox 在样式层次结构中属于frame ，因此在frame 上设置的类型变化也会自动由groupBox 继承。要退出，请重新设置子类型的变化。

传播顺序

样式变化在Style 或Theme 中定义。主题不能影响在样式中定义的整个样式变体，只能重写其中的个别属性，就像重写其他样式属性一样。

例如，如果Style 和活动的Theme 都定义了frame.variations ，则这两个类型变化数组都对Frame 有效。单个属性的解析顺序是：主题的变化属性优先于主题的直接属性，主题的直接属性优先于样式的变化属性，样式的变化属性优先于样式的直接属性。

这同样适用于实例变化。在Theme 中定义的样式变化优先于主题的直接属性。如果在Style 中也定义了具有相同name 的样式变体，则两者都会生效，并遵循上述相同的解析顺序。

在以下代码段中，带有StyleVariation.variations: ["alert"] 的按钮在浅色主题中将显示为红色，在深色主题中将显示为青色，两者都有一个 4 像素的边框。由于深色主题将button.background.radius 覆盖为6 ，因此该属性优先于在样式的变体中设置的background.radius 。因此，按钮的半径在深色主题中为6 ，而在浅色主题中为0 ：

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"
        }
    }
}

注意： Qt.labs 模块中的类型不保证在未来版本中保持兼容。

另请参阅 Style,Theme,ControlStyle.variations, 和StyleVariation.variations 。

属性文档

name : string

该变体的名称。

该名称在用作instance variation 时可识别该变体。

另请参阅 variations 和Instance Variations 。

附加属性文件

StyleVariation.controlType : int

该属性可识别其所连接项的control type 。

StyleKit type variations 如果父项目的controlType 与在Style 中定义了variations 的控件类型相匹配，则这些变化适用于所有子控件。

内置控件会自动设置该属性。自定义控件必须显式设置该属性才能参与类型变化解析。

另请参阅 ControlStyle.variations 和StyleReader.controlType 。

StyleVariation.variations : list<string>

该属性包含Control 及其后代控件要激活的instance 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"]
        }
    }
}

另请参见 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.