StyleKit 기능 개요

이 페이지에서는 StyleKit의 주요 기능에 대해 간략히 소개합니다. 사용 가능한 모든 유형과 속성에 대한 전체 참조 내용은 QML Types 페이지를 참조하십시오.

스타일 생성

Style 는 애플리케이션 내 모든 요소의 시각적 모양을 정의하는 QML 객체입니다 Qt Quick Controls button, slider, checkBox 등)의 시각적 외관을 설명하는 QML 객체입니다. 각 컨트롤은 스타일 내에서 고유한 그룹을 가지며, 이 그룹에서 컨트롤을 구성하는 시각적 요소에 대한 색상, 크기, 반경, 그림자 등의 속성을 설정할 수 있습니다.

control group 는 다른 모든 컨트롤 그룹에 대한 대체 역할(fallback)을 수행하기 때문에 특별합니다. 예를 들어, slider 의 일부 속성을 생략하면, 해당 속성은 대신 control 에서 읽어오게 됩니다. slider 이나 control 에 설정되지 않은 속성은 Basic Style과 유사한 완전한 스타일인 fallback style 로 추가 대체됩니다. 즉, 사용 가능한 모든 컨트롤에 스타일을 적용할 필요는 없으며, 사용자 정의하려는 컨트롤에만 적용하면 됩니다. 나머지 컨트롤의 스타일링은 대체 시스템이 처리합니다:

// 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.
}

스타일 활성화

스타일을 활성화하려면 루트 ApplicationWindow 의 StyleKit.style 에 해당 스타일을 할당하세요. 그러면 애플리케이션의 모든 컨트롤이 자동으로 해당 스타일을 적용받게 됩니다:

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

컨트롤 상태

컨트롤은 사용자 상호작용에 따라 모양이 바뀝니다. 예를 들어, 버튼은 마우스를 올렸을 때, 눌렀을 때, 비활성화되었을 때 각각 다르게 보입니다. ` StyleKit `를 사용하면 영향을 받는 속성 앞에 ` state ` 이름을 붙여 해당 상태에 있을 때 대체 값을 부여함으로써 스타일에서 이러한 변화를 표현할 수 있습니다.

상태는 중첩될 수 있으며, 더 구체적인 조합(예: hovered.checked)은 개별 구성 요소보다 우선 순위를 갖습니다:

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

상태 전환

컨트롤 스타일에서 ` transition ` 속성을 설정하여 상태 변경에 애니메이션을 적용할 수 있습니다. ` StyleAnimation `는 모든 배경색이나 표시기 색상과 같이 관련 스타일 속성 그룹에 애니메이션을 적용하는 편리한 방법을 제공하지만, ` ColorAnimation ` 및 ` NumberAnimation `와 같은 표준 QML 애니메이션도 사용할 수 있습니다:

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

테마

StyleKit 는 ` Style`의 ` light ` 및 ` dark ` 속성을 통해 밝은 테마와 어두운 테마를 기본적으로 지원합니다. ` Style`과 마찬가지로, ` Theme `을 사용하면 해당 테마가 활성화되었을 때 각 컨트롤이 가져야 할 스타일을 정의할 수 있습니다. 테마에 설정되지 않은 속성은 스타일에서 읽어오는 방식으로 대체됩니다:

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

사용자 정의 테마

라이트(light)와 다크(dark) 외에도, ` CustomTheme`를 사용하여 원하는 만큼 추가 테마를 정의할 수 있습니다. 각 ` CustomTheme `는 ` name `를 가지며, 내장 테마와 동일한 구조를 가진 ` Theme ` 객체를 포함합니다:

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

실행 시 테마를 전환하려면 애플리케이션의 QML 파일에서 ` Style.themeName `을 원하는 테마의 이름으로 설정하십시오. `Style.themeNames` 속성에는 사용 가능한 모든 테마 이름이 나열되어 있으므로, 선택기 컨트롤을 쉽게 채울 수 있습니다:

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

애플리케이션 시작 시 테마를 활성화하려면 스타일을 할당할 때 ` themeName `을 설정하십시오:

ApplicationWindow {
    width: 1024
    height: 800
    visible: true

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

스타일 변형

StyleVariation 을 사용하면 애플리케이션의 일부에 대해 대체 스타일을 정의할 수 있습니다. 이는 예를 들어 ToolBar 이나 GroupBox 의 자식 요소인 컨트롤에 서로 다른 스타일을 적용해야 할 때, 또는 애플리케이션이 일부 컨트롤에 선택적으로 적용할 수 있는 스타일 힌트를 구현하려는 경우에 유용합니다.

스타일 변형에는 ‘유형 변형(type variations)’과 ‘인스턴스 변형(instance variations)’의 두 가지 유형이 있습니다.

유형 변형

유형 변형은 다른 컨트롤 유형의 자식(또는 하위 요소)인 컨트롤에 대한 대체 스타일을 포함합니다. 즉, ` StyleVariation `에 버튼용 스타일이 포함되어 있고, 이 스타일이 프레임의 ` variations ` 속성에 추가되면, ` StyleKit `는 애플리케이션 내에서 ` Frames `의 자식인 모든 ` 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: []
    }
}

인스턴스 변형

StyleVariations 라는 이름의 변형은 StyleVariation.variations 부착 속성을 사용하여 애플리케이션 내 개별 컨트롤에 적용할 수 있습니다. 적용되면 컨트롤 자체와 그 모든 하위 요소에 대체 스타일이 적용됩니다. 이는 특정 유형(예: 모든 ` Frames`)의 모든 컨트롤에 영향을 미치는 유형 변형과는 다릅니다. 인스턴스 변형은 해당 속성이 부착된 컨트롤 인스턴스(및 하위 요소)에만 영향을 미칩니다:

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

애플리케이션의 컨트롤에 이를 적용하려면:

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

사용자 정의 컨트롤

애플리케이션에 Qt Quick Controls에 속하지 않는 사용자 정의 컨트롤이 포함되어 있더라도, 이를 StyleKit 와 통합할 수 있습니다. 각 컨트롤에 대해 CustomControl 를 추가하고, 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"
    }
}

컨트롤의 구현에서, 스타일 속성을 다시 읽기 위해 일치하는 controlType 을 가진 StyleReader 을 사용하십시오. 올바른 속성 값은 Themes, StyleVariations, fallback types 및 속성 전파를 고려하여 결정됩니다. 스타일 리더가 이를 수행하려면 컨트롤의 상태를 알아야 합니다. 따라서 컨트롤의 상태를 hovered 및 pressed 와 같은 관련 StyleReader 속성에 바인딩하십시오. 상태가 변경될 때마다 영향을 받는 모든 스타일 속성이 업데이트되어 컨트롤이 다시 그리게 됩니다:

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

사용자 정의 델리게이트

컨트롤의 각 시각적 요소( background, handle, indicator 등)는 delegate 에 의해 렌더링됩니다. 기본적으로 StyleKit 는 렌더링에 StyledItem 를 사용하지만, 이를 사용자 정의 QML 컴포넌트로 완전히 대체할 수 있습니다.

이 컴포넌트는 StyleKit 가 자동으로 채우는 두 가지 필수 속성을 정의해야 합니다:

delegateStyle — 해결된 스타일 속성(색상, 반경, 암시적 크기 등)을 전달하는 DelegateStyle
control — 델리게이트가 속한 Qt Quick

그런 다음, 변경을 적용하려는 시각적 요소의 delegate 속성에 해당 컴포넌트를 할당합니다:

// 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)
        }
    }
}

오버레이와 언더레이

기본 렌더링을 완전히 대체하기보다는 보강하기만 하고 싶다면, StyledItem 를 델리게이트의 루트로 사용하세요. StyledItem 에 추가하는 모든 자식 요소는 기본 렌더링 위에 그려집니다(오버레이):

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

반대로 기본 렌더링 아래에 무언가를 그리려면, 델리게이트를 Item 로 설정하고, 추가 콘텐츠를 맨 앞에 배치한 다음, StyledItem 를 자식으로 삽입하여 그 위에 기본 모양을 렌더링하도록 하십시오:

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

사용자 정의 데이터

사용자 정의 델리게이트는 때때로 기본 제공되는 스타일 속성을 넘어서는 추가적인 스타일 속성이 필요합니다. 예를 들어, ` StyleKit `가 인식하지 못하는 자식 항목의 스타일을 지정해야 하는 경우입니다. ` data ` 속성을 사용하면 이를 구현할 수 있습니다. 이 속성은 모든 ` QtObject`를 담을 수 있으므로, 델리게이트에 필요한 어떤 정보든 전달할 수 있습니다.

다른 모든 스타일 속성과 마찬가지로, ` data `도 스타일 속성 해결 과정에 참여합니다. 즉, 델리게이트는 항상 현재 컨트롤 상태, 활성 테마 및 스타일 변형과 일치하는 객체를 수신합니다. 내장 속성과 달리, ` data `는 전체적으로 전파되며, 객체 내부의 개별 속성은 별도로 전파되지 않습니다:

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.