StyleVariation QML Type
为特定控件定义替代样式。更多...
| Import Statement: | import Qt.labs.StyleKit |
| Inherits: | |
| Status: | Technology preview |
此类型处于技术预览阶段，可能会有变动。
属性
- name : string
关联属性
- controlType : int
- variations : list<string>
详细说明
StyleVariation 允许您定义替代样式，这些样式可应用于应用程序中的特定控件（实例变体），或应用于特定父控件类型的所有子控件（类型变体）。例如，您可以让侧边栏中的控件呈现紧凑的外观，或者使所有“toolbars ”中的按钮与其他位置的按钮外观不同。
实例变体
实例变体通过为应用程序中的任何项目设置variations 附加属性来激活——该项目的所有子控件或后代控件（即所有StyleKit控件）都将应用该替代样式。变体也可同时在层次结构的多个级别上设置；当它们发生冲突时，距离控件最近的变体具有优先级。
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"
}
}并通过应用程序中的 `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 继承。若要取消此行为，请重置子类型的变体设置。
传播顺序
一个 StyleVariation 仅在定义它的Style 或Theme 范围内有效。主题无法覆盖样式中定义的整个 StyleVariation——只能覆盖其中的单个属性，这与任何其他样式属性一样。
例如，如果Style 和活动Theme 都定义了frame.variations ，那么对于Frame 而言，这两个类型变体数组都会生效。单个属性的解析顺序为：主题的变体属性优先于主题的直接属性，主题的直接属性优先于风格的变体属性，而风格的变体属性又优先于风格的直接属性。
此规则同样适用于实例变体。在Theme 中定义的StyleVariation优先于主题的直接属性。如果Style 中也定义了一个具有相同name 的StyleVariation，则两者均会生效，并遵循上述相同的解析顺序。
在下面的代码片段中，一个具有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, {StyleKit Property Resolution} 。
属性文档
name : string
此变体的名称。
当作为instance variation 使用时，该名称可识别此变体。
另请参阅 variations 和Instance Variations 。
附带属性文档
StyleVariation.controlType : int [attached]
该属性用于标识其所关联项的control type 。
StyleKit 会利用该属性为子控件解析type variations ——如果父项的controlType 与Style 中定义了variations 的控件类型相匹配，则这些变体将应用于所有子控件。
内置控件会自动设置此属性。自定义控件必须显式设置此属性，才能参与类型变体解析。
另请参阅 ControlStyle.variations 和StyleReader.controlType 。
StyleVariation.variations : list<string> [attached]
该属性存储了要为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.
