本页内容

ControlStyleProperties QML Type

定义控件的可样式化属性。更多...

Import Statement: import Qt.labs.StyleKit
Inherited By:

ControlStateStyle, ControlStyle, CustomControl, and StyleReader

Status: Technology preview

此类型处于技术预览阶段,内容可能会有变动。

属性

详细说明

ControlStyleProperties 定义了控件的可样式化属性:视觉构建块background 、indicator 、handle 和text ,以及布局属性,如padding 、spacing 和transition 。

可通过继承类型(如ControlStyle 和StyleReader )访问这些样式属性。

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

另请参阅 ControlStyle 、StyleReader 、ControlStateStyle 和DelegateStyle 。

属性文档

background : DelegateStyle

用于设置控件背景样式的分组属性。

背景委托通常是控件后面的主要视觉矩形。使用它来设置colors 、borders 、radii 、shadows 、gradients 以及images 。

注意:默认的 ` fallback style ` 会将 `background.visible ` 设置为 `false `,这适用于通常不应绘制背景的控件,例如 `CheckBox`、`RadioButton` 和 `Slider`。若要显示这些控件的背景,请显式将 `background.visible ` 设置为 `true `。

bottomPadding : real

控件的bottom padding 。如果未设置,则回退到padding 。

另请参阅 padding 、topPadding 、leftPadding 以及rightPadding 。

handle : HandleStyle

用于设置控件手柄样式的分组属性。

该控件手柄被Switch 、Slider 和RangeSlider 等控件所使用。对于RangeSlider ,可以通过handle.first 和handle.second 分别设置两个控件手柄的样式。

另请参阅 HandleStyle 和DelegateStyle 。

indicator : IndicatorStyle

用于设置控件指示符样式的分组属性。对于checkBox ,指示符是边框,其foreground 属性对应的是复选标记。对于slider ,指示符是凹槽,其 属性对应的是填充色。

另请参阅 DelegateStyle 。

leftPadding : real

控件的left padding 。如果未设置,则回退为padding 。

另请参阅 padding 、rightPadding 、topPadding 以及bottomPadding 。

padding : real

control's content area and the bounds of the control 之间的均匀间距。设置此选项将为leftPadding 、rightPadding 、topPadding 和bottomPadding 提供默认值。每侧均可单独覆盖。

另请参阅 leftPadding 、rightPadding 、topPadding 和bottomPadding 。

rightPadding : real

控件的right padding 。如果未设置,则回退到padding 。

另请参阅 padding 、leftPadding 、topPadding 以及bottomPadding 。

spacing : real

控件内部视觉元素之间的间距,例如指示器与标签之间的间距。

text : TextStyle

用于设置控件文本标签样式的分组属性。

topPadding : real

控件的top padding 。如果未设置,则回退到padding 。

另请参阅 padding 、bottomPadding 、leftPadding 以及rightPadding 。

transition : Transition

Transition 用于在控件进入新状态时对样式属性进行动画效果,例如hovered 或pressed 。如果设置为null (默认值),则属性更改将立即生效,不进行动画效果。

button {
    background.color: "mistyrose"
    hovered.background.color: "plum"
    transition: Transition {
        ColorAnimation {
            properties: "background.color, background.shadow.color, handle.color"
            easing.type: Easing.OutQuad
            duration: 500
        }
        NumberAnimation {
            properties: "background.leftRadius, background.rightRadius"
            easing.type: Easing.OutQuad
            duration: 500
        }
    }

    // I only want a fade-out effect (not fade-in). So while the button
    // is hovered, remove the transition, so that it only applies in the
    // normal state. In other words, it's the state being entered that
    // determines the transition, not the state that is left.
    hovered.transition: null
}

为避免在每个委托中重复指定相同的目标属性,StyleKit 提供了StyleAnimation 以方便使用,它既可以替代标准动画,也可以与标准动画结合使用:

comboBox {
    background.color: "mistyrose"
    hovered.background.color: "plum"
    transition: Transition {
        StyleAnimation {
            animateColors: true
            animateBackgroundRadii: true
            animateIndicatorRadii: true
            animateBackgroundShadow: true
            easing.type: Easing.OutQuad
            duration: 500
        }
    }
}

注意:对于 参与过渡的颜色属性,请优先使用Qt.alpha 而不是"transparent" (例如menuBarItem.background.color: Qt.alpha(palette.accent, 0) )。"transparent" 的行为是Qt.rgba(0, 0, 0, 0) ,这可能会导致在过渡过程中插值生成的颜色向黑色偏移。

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