Back to Qt.io
Contact Us Blog Download Qt
Auf dieser Seite

Übersicht über die Funktionen von StyleKit

Diese Seite bietet eine kurze Einführung in die wichtigsten Funktionen von StyleKit. Eine vollständige Übersicht über alle verfügbaren Typen und Eigenschaften finden Sie auf der Seite „ QML Types “.

Erstellen eines Stils

Ein „ Style “ ist ein QML-Objekt, das das visuelle Erscheinungsbild aller Qt Quick Controls in Ihrer Anwendung – „ button “, „ slider “, „ checkBox “ und so weiter. Jedes verfügt über eine eigene Gruppe im Stil, in der Sie Eigenschaften wie Farben, Größen, Radien und Schatten für die visuellen Bestandteile des Steuerelements festlegen können.

Das „ control group “ ist etwas Besonderes, da es als Fallback für alle anderen Steuerelementgruppen dient. Wenn Sie beispielsweise einige der Eigenschaften für ein „ slider “ weglassen, werden diese stattdessen aus dem „ control “ gelesen. Eigenschaften, die weder in „ slider “ noch in „ control “ festgelegt sind, greifen weiter auf „ fallback style “ zurück, bei dem es sich um einen vollständigen Stil handelt, der dem „Basic Style“ ähnelt. Das bedeutet, dass Sie nicht unbedingt alle verfügbaren Steuerelemente gestalten müssen, sondern nur diejenigen, die Sie anpassen möchten – das Fallback-System kümmert sich um die Gestaltung der übrigen Elemente:

// PlainStyle.qml

Style {
    control {
        // control does not map to an actual Qt Quick Control, but is a shared
        // fallback for all other controls. Use it to define styling that is
        // common to all of them. Unset properties fall back to Style.fallbackStyle.
        padding: 6
        text.color: "white"
        background {
            radius: 4
            border.color: "gray"
        }
        indicator {
            width: 20
            height: 20
            border.width: 1
            radius: 3
        }
        handle {
            width: 20
            height: 20
            radius: 10
        }
    }

    slider {
        // slider defines the styling for a Qt Quick Slider.
        // Unset properties fall back to control.
        handle.color: "white"
        indicator {
            fillWidth: true
            height: 6
            color: "steelblue"
            foreground.color: "skyblue"
        }
    }

    abstractButton {
        // abstractButton does not map to an actual Qt Quick Control, but
        // is a shared fallback for button-like controls, such as button,
        // radioButton, checkBox). Use it to define styling that is common
        // to all of them. Unset properties fall back to control.
        background.shadow {
            opacity: 0.6
            verticalOffset: 2
            horizontalOffset: 2
            color: "gray"
        }
    }

    button {
        // button defines the styling for a Qt Quick Button.
        // Unset properties fall back to abstractButton.
        background {
            width: 120
            color: "lightsteelblue"
            gradient: Gradient {
                GradientStop { position: 0.0; color: Qt.alpha("black", 0.0)}
                GradientStop { position: 1.0; color: Qt.alpha("black", 0.2)}
            }
        }
    }

    // Controls left undefined — such as radioButton, checkBox, roundButton
    // or switchControl — fall back to their immediate base type, which in
    // this style will be either abstractButton or control directly.
}

Aktivieren eines Stils

Um den Stil zu aktivieren, weisen Sie ihn unter „ StyleKit.style “ der Stammkomponente „ ApplicationWindow “ zu. Alle Steuerelemente in der Anwendung übernehmen ihn dann automatisch:

// Main.qml

import QtQuick
import Qt.labs.StyleKit

ApplicationWindow {
    id: app
    width: 1024
    height: 800
    visible: true

    // Assign the style to be used
    StyleKit.style: PlainStyle {}

    // Controls are used as normal
    Column {
        anchors.fill: parent
        anchors.margins: 10
        spacing: 10

        Button {
            text: "Button"
        }

        Slider {
            width: 200
        }
    }
}

Zustände von Steuerelementen

Steuerelemente ändern ihr Erscheinungsbild je nach Benutzerinteraktion – eine Schaltfläche sieht anders aus, wenn der Mauszeiger darüberfährt, sie gedrückt wird oder deaktiviert ist. Mit „ StyleKit “ können Sie dies im Stil ausdrücken, indem Sie den Namen „ state “ vor die betroffenen Eigenschaften setzen, um ihnen alternative Werte zuzuweisen, wenn sich das Steuerelement in diesem Zustand befindet.

Zustände können verschachtelt werden, und eine spezifischere Kombination (z. B. „ hovered.checked “) hat Vorrang vor ihren einzelnen Komponenten:

button {
    text.color: "aliceblue"
    background.color: "cornflowerblue"
    pressed.background.color: "deepskyblue"
    hovered.background.color: "lightskyblue"
    focused.background.color: "lightsteelblue"
    checked.background.color: "royalblue"
    highlighted.background.color: "lightblue"
    disabled {
        background.color: "lightgray"
        background.border.color: "darkgray"
    }

    // Nested states, such as hovered.checked in this case, takes
    // precedence over both hovered and checked:
    hovered.checked.background.color: "steelblue"
}

Zustandsübergänge

Zustandsänderungen können animiert werden, indem die Eigenschaft „ transition “ im Stil eines Steuerelements festgelegt wird. Ein „ StyleAnimation “ bietet eine bequeme Möglichkeit, Gruppen verwandter Stileigenschaften zu animieren, wie z. B. alle Hintergrund- oder Indikatorfarben, aber Sie können auch Standard-QML-Animationen wie „ ColorAnimation “ und „ NumberAnimation “ verwenden:

comboBox {
    background.color: "lightgray"
    hovered.background.color: "plum"

    indicator.color: "white"
    hovered.indicator.color: "pink"
    hovered.indicator.border.width: 4

    transition: Transition {
        StyleAnimation {
            animateBackgroundColors: true
            animateIndicatorColors: true
            animateIndicatorBorder: true
            easing.type: Easing.OutQuad
            duration: 500
        }
    }
}

Theming

StyleKit bietet über die Eigenschaften „ light “ und „ dark “ eines „ Style “ integrierte Unterstützung für helle und dunkle Designs. Ähnlich wie bei einem „ Style “ können Sie mit einem „ Theme “ den Stil festlegen, den jedes Steuerelement haben soll, wenn dieses Design aktiv ist. Eigenschaften, die in einem Design nicht festgelegt sind, werden standardmäßig aus dem Stil übernommen:

Style {
    light: Theme {
        applicationWindow.background.color: "gainsboro"
        control.text.color: "#202020"
        control.background.color: "#f0f0f0"
        control.background.border.color: "#d0d0d0"
        button.hovered.background.color: "#4a90d9"
        radioButton.indicator.foreground.color: "#d0d0d0"
    }

    dark: Theme {
        applicationWindow.background.color: "#2b2b2b"
        control.text.color: "#e0e0e0"
        control.background.color: "#404040"
        control.background.border.color: "#606060"
        button.hovered.background.color: "#6ab0f9"
        radioButton.indicator.foreground.color: "#606060"
    }
}

Benutzerdefinierte Designs

Neben „light“ und „dark“ können Sie beliebig viele zusätzliche Themen mithilfe von ` CustomTheme` definieren. Jedes ` CustomTheme ` verfügt über ein ` name ` und enthält ein ` Theme `-Objekt mit derselben Struktur wie die integrierten Themen:

Style {
    CustomTheme {
        name: "HighContrast"
        theme: Theme {
            control.background.color: "white"
            control.background.border.color: "black"
            control.background.border.width: 2
        }
    }

    CustomTheme {
        name: "Sepia"
        theme: Theme {
            control.text.color: "#5b4636"
            control.background.color: "#f4ecd8"
            control.background.border.color: "#c8b99a"
            applicationWindow.background.color: "#efe6d0"
        }
    }
}

Um das Design zur Laufzeit zu wechseln, setzen Sie in einer QML-Datei Ihrer Anwendung Style.themeName auf den Namen des gewünschten Designs. Die Eigenschaft `Style.themeNames` listet alle verfügbaren Designnamen auf, was das Befüllen eines Selektor-Steuerelements vereinfacht:

ComboBox {
    model: StyleKit.style.availableThemeNames
    onCurrentTextChanged: StyleKit.style.themeName = currentText
}

Um ein Theme beim Start der Anwendung zu aktivieren, setzen Sie ` themeName ` bei der Zuweisung des Stils:

ApplicationWindow {
    width: 1024
    height: 800
    visible: true

    StyleKit.style: MyStyleKitStyle {
        themeName: "HighContrast"
    }
}

Stilvariationen

Mit einem „ StyleVariation “ können Sie alternative Stile für Teile der Anwendung definieren. Dies ist nützlich, wenn Sie Steuerelemente unterschiedlich gestalten müssen, wenn sie beispielsweise Kinder eines „ ToolBar “ oder eines „ GroupBox “ sind, oder wenn Sie Stilhinweise implementieren möchten, die die Anwendung optional auf einige der Steuerelemente anwenden kann.

Es gibt zwei Arten von Stilvariationen: Typvariationen und Instanzvariationen.

Typvariationen

Eine Typvariante enthält alternative Stile für Steuerelemente, die Kinder (oder Nachkommen) eines anderen Steuerelementtyps sind. Das bedeutet: Wenn ein „ StyleVariation “ Stile für eine Schaltfläche enthält und diesem die Eigenschaft „ variations “ eines Frames zugewiesen wird, wendet „ StyleKit “ die Stile entsprechend auf alle „ Buttons “ an, die in der Anwendung Kinder von „ Frames “ sind:

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

Instanzvariationen

Benannte „ StyleVariations “ können mithilfe der angehängten Eigenschaft „ StyleVariation.variations “ auf einzelne Steuerelemente in der Anwendung angewendet werden. Bei der Anwendung erhalten das Steuerelement selbst sowie alle seine Nachkommen die alternative Gestaltung. Dies unterscheidet sich von einer Typvariation, die alle Steuerelemente eines bestimmten Typs betrifft, wie beispielsweise alle „ Frames “. Instanzvariationen wirken sich nur auf die Steuerelementinstanz (und deren Nachkommen) aus, an die sie angehängt sind:

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

Wenden Sie sie auf Steuerelemente in Ihrer Anwendung an:

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

Benutzerdefinierte Steuerelemente

Wenn Ihre Anwendung benutzerdefinierte Steuerelemente enthält, die nicht Teil von Qt Quick Controls, können Sie diese dennoch in „ StyleKit “ integrieren. Fügen Sie einfach für jedes dieser Steuerelemente ein „ CustomControl “ hinzu und gestalten Sie deren Stil auf dieselbe Weise wie bei den „ built-in controls “:

// MyStyle.qml

Style {
    id: style
    readonly property int myControlType: 0
    CustomControl {
        controlType: style.myControlType
        background {
            width: 120
            height: 30
            radius: 0
        }
        hovered.background.color: "lightslategray"
        pressed.background.color: "skyblue"
    }
}

Verwenden Sie in der Implementierung des Steuerelements einen „ StyleReader “ mit dem passenden „ controlType “, um die Stileigenschaften zurückzulesen. Die korrekten Eigenschaftswerte werden unter Berücksichtigung von „ Themes “, „ StyleVariations “, „ fallback types “ und der Eigenschaftsweitergabe ermittelt. Damit ein Style-Reader dies tun kann, muss er den Zustand Ihres Steuerelements kennen. Binden Sie daher den Zustand Ihres Steuerelements an die entsprechenden „ StyleReader “-Eigenschaften wie „ hovered “ und „ pressed “. Bei jeder Zustandsänderung werden alle betroffenen Stileigenschaften aktualisiert, was dazu führt, dass Ihr Steuerelement neu gezeichnet wird:

// Main.qml

component MyControl : Rectangle {
    StyleReader {
        id: styleReader
        controlType: StyleKit.style.myControlType
        hovered: hoverHandler.hovered
        pressed: tapHandler.pressed
        palette: app.palette
    }

    HoverHandler { id: hoverHandler }
    TapHandler { id: tapHandler }

    implicitWidth: styleReader.background.width
    implicitHeight: styleReader.background.height
    color: styleReader.background.color
    radius: styleReader.background.radius

    Text {
        font: styleReader.font
        anchors.centerIn: parent
        text: "ok"
    }
}

Benutzerdefinierte Delegaten

Jeder visuelle Teil eines Steuerelements – „ background “, „ handle “, „ indicator “ usw. – wird von einem „ delegate “ gerendert. Standardmäßig verwendet „ StyleKit “ „ StyledItem “ für das Rendering, Sie können es jedoch vollständig durch eine eigene QML-Komponente ersetzen.

Die Komponente muss zwei erforderliche Eigenschaften definieren, die von StyleKit automatisch ausgefüllt werden:

  • delegateStyle — die „ DelegateStyle “, die die aufgelösten Stileigenschaften (Farbe, Radius, implizite Größe usw.) enthält
  • control — die „Qt Quick “, zu der der Delegat gehört

Anschließend weisen Sie die Komponente der Eigenschaft „ delegate “ des visuellen Teils zu, den Sie beeinflussen möchten:

// import QtQuick.Templates as T

slider {
    handle.delegate: Rectangle {
        id: handle
        required property DelegateStyle delegateStyle
        required property T.Slider control
        implicitWidth: delegateStyle.width
        implicitHeight: delegateStyle.height
        radius: delegateStyle.radius
        color: delegateStyle.color
        Text {
            anchors.centerIn: parent
            text: handle.control.value.toFixed(0)
        }
    }
}

Overlay und Underlay

Wenn Sie die Standarddarstellung nur ergänzen und nicht vollständig ersetzen möchten, verwenden Sie „ StyledItem “ als Stammelement Ihres Delegaten. Alle untergeordneten Elemente, die Sie zu „ StyledItem “ hinzufügen, werden über der Standarddarstellung gezeichnet (Overlay):

Style {
    component Star : Shape {
        id: star
        property color color
        ShapePath {
            fillColor: star.color
            scale: Qt.size(star.width, star.height)
            PathMove { x: 0.50; y: 0.00 }
            PathLine { x: 0.59; y: 0.35 }
            PathLine { x: 0.97; y: 0.35 }
            PathLine { x: 0.66; y: 0.57 }
            PathLine { x: 0.78; y: 0.91 }
            PathLine { x: 0.50; y: 0.70 }
            PathLine { x: 0.22; y: 0.91 }
            PathLine { x: 0.34; y: 0.57 }
            PathLine { x: 0.03; y: 0.35 }
            PathLine { x: 0.41; y: 0.35 }
            PathLine { x: 0.50; y: 0.00 }
        }
    }

    button {
        background.delegate: StyledItem {
            width: parent.width
            height: parent.height
            // Draw a star on top the default rendering
            Star {
                anchors.fill: parent
                color: "gold"
            }
        }
    }
}

Um stattdessen etwas unterhalb der Standarddarstellung darzustellen, machen Sie Ihren Delegaten zu einem „ Item “, platzieren Sie den zusätzlichen Inhalt an erster Stelle und betten Sie ein „ StyledItem “ als untergeordnetes Element ein, um die Standarddarstellung darüber darzustellen:

Style {
    component Star : Shape {
        id: star
        property color color
        ShapePath {
            fillColor: star.color
            scale: Qt.size(star.width, star.height)
            PathMove { x: 0.50; y: 0.00 }
            PathLine { x: 0.59; y: 0.35 }
            PathLine { x: 0.97; y: 0.35 }
            PathLine { x: 0.66; y: 0.57 }
            PathLine { x: 0.78; y: 0.91 }
            PathLine { x: 0.50; y: 0.70 }
            PathLine { x: 0.22; y: 0.91 }
            PathLine { x: 0.34; y: 0.57 }
            PathLine { x: 0.03; y: 0.35 }
            PathLine { x: 0.41; y: 0.35 }
            PathLine { x: 0.50; y: 0.00 }
        }
    }

    slider.handle.delegate: Item {
        // Since the root item is not a StyledItem, the following
        // required properties must be defined explicitly:
        required property DelegateStyle delegateStyle
        required property QtObject control

        implicitWidth: delegateStyle.width
        implicitHeight: delegateStyle.height
        width: parent.width
        height: parent.height
        scale: delegateStyle.scale
        rotation: delegateStyle.rotation
        visible: delegateStyle.visible

        // Draw a star underneath the default handle delegate
        Star {
            width: parent.width * 2
            height: parent.height * 2
            anchors.centerIn: parent
            color: "gold"
        }

        StyledItem {
            // Forward delegateStyle into StyledItem. StyledItem doesn't
            // use 'control' for anything, so it can be omitted.
            delegateStyle: parent.delegateStyle
        }
    }
}

Benutzerdefinierte Daten

Benutzerdefinierte Delegaten benötigen manchmal zusätzliche Stileigenschaften, die über die integrierten hinausgehen – beispielsweise, um untergeordnete Elemente zu gestalten, von denen „ StyleKit “ nichts weiß. Die Eigenschaft „ data “ macht dies möglich. Sie kann ein beliebiges „ QtObject “ enthalten und somit alle Informationen transportieren, die Ihr Delegat benötigt.

Wie alle anderen Stileigenschaften ist auch „ data “ an der Auflösung von Stileigenschaften beteiligt – der Delegat erhält immer das Objekt, das dem aktuellen Steuerelementzustand, dem aktiven Design und den Stilvariationen entspricht. Im Gegensatz zu den integrierten Eigenschaften wird „ data “ als Ganzes weitergegeben – einzelne Eigenschaften innerhalb des Objekts werden nicht separat weitergegeben:

component OverlayData : QtObject {
    property color overlayColor
}

toolButton {
    background.delegate: StyledItem {
        id: custom
        Text {
            color: custom.delegateStyle.data.overlayColor
            font.pixelSize: 30
            text: "シ"
        }
    }
    background.data: OverlayData {
        overlayColor: "sandybrown"
    }
    hovered.background.data: OverlayData {
        overlayColor: "magenta"
    }
}

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