StyleKit の機能概要

このページでは、StyleKitの主な機能について簡単に紹介します。利用可能なすべての型とプロパティに関する完全なリファレンスについては、「QML Types 」ページを参照してください。

スタイルの作成

Style は、アプリケーション内のすべてのQt Quick コントロール（button 、slider 、checkBox など）の視覚的な外観を記述するQMLオブジェクトです。各コントロールにはスタイル内に独自のグループがあり、そこでコントロールを構成する視覚的な部分の色、サイズ、半径、影などのプロパティを設定できます。

control group は、他のすべてのコントロールグループのフォールバックとして機能するため、特別な存在です。たとえば、slider のプロパティの一部を省略した場合、それらのプロパティは代わりにcontrol から読み込まれます。slider やcontrol で設定されていないプロパティは、さらにfallback style にフォールバックされます。これはBasic 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 の子要素であるコントロールに対して異なるスタイルを適用する必要がある場合や、アプリケーションが一部のコントロールにオプションで適用できるスタイルのヒントを実装したい場合に役立ちます。

スタイルのバリエーションには、「タイプバリエーション」と「インスタンスバリエーション」の2種類があります。

タイプバリエーション

タイプバリエーションには、別のコントロールタイプの子供（または子孫）であるコントロールに対する代替スタイルが含まれます。つまり、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 が自動的に設定する以下の2つの必須プロパティを定義する必要があります：

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.