QML ComboBox 完全自定义样式：背景、内容、下拉项与箭头

ComboBox 的样式由四个可替换部件组成：background（外框）、contentItem（收起时显示的内容）、delegate（下拉列表项）、indicator（右侧箭头）。全部重写，就能做出完全贴合设计稿的下拉框。这个 demo 以 QtQuick.Controls.Basic 风格为底，把四件套逐个替换，还顺手处理了2个常见的坑。

background --- 三态配色：常态 / 悬停 / 按下，焦点时描边加粗
contentItem --- 文本内容 + 给箭头留出右侧空间
delegate --- 下拉项高亮、悬停反馈
indicator --- Canvas 手绘箭头，颜色随状态变化

演示代码

qml 复制代码

import QtQuick
import QtQuick.Controls
import QtQuick.Controls.Basic
import QtQuick.Layouts

FadeInAnimation {
    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 15

        // ... 省略标题组件 TitleSeparator ...

        ComboBox {
            id: styledCombo
            Layout.fillWidth: true
            Layout.preferredHeight: 30

            model: ["选项1", "选项2", "选项3"]

            // 背景样式 - 定义 ComboBox 的矩形框外观
            // 注意：不要在这里引用 styledCombo.width/height（会与 implicitWidth/Height 形成绑定循环）
            // background 默认会自动铺满整个 ComboBox，无需手动设置尺寸
            background: Rectangle {
                // 三态配色：常态白底浅蓝边框，hover 淡蓝 tint，按下更深
                color: styledCombo.down ? "#D9ECFF"
                     : (styledCombo.hovered ? "#EAF4FF" : "#FFFFFF")
                border.color: styledCombo.activeFocus ? "#1296FF"
                            : (styledCombo.hovered ? "#8FC8FF" : "#D5E4F7")
                border.width: styledCombo.activeFocus ? 2 : 1
                radius: 4
            }

            // 内容区域 - 显示当前选中的文本
            contentItem: Text {
                text: styledCombo.displayText
                font: styledCombo.font
                color: "#1F2D3D"
                verticalAlignment: Text.AlignVCenter
                leftPadding: 10
                rightPadding: styledCombo.indicator.width + 15
            }

            // 下拉列表项样式 - 定义弹出窗口中每个选项的外观
            delegate: ItemDelegate {
                width: styledCombo.width
                height: 30

                // 选项内容文本：当前选中项用主色加粗高亮
                // 注意：font 是 group property，不能用 font: xxx 整体赋值后再改子属性（会报重复赋值）
                contentItem: Text {
                    text: modelData
                    font.family: styledCombo.font.family
                    font.pixelSize: styledCombo.font.pixelSize
                    font.weight: parent.highlighted ? Font.DemiBold : Font.Normal
                    color: parent.highlighted ? "#1296FF" : "#1F2D3D"
                    verticalAlignment: Text.AlignVCenter
                    leftPadding: 10
                    rightPadding: 10
                }

                // 选项背景：选中项浅蓝高亮，hover/down 淡蓝
                background: Rectangle {
                    color: parent.highlighted ? "#EAF4FF"
                         : (parent.down ? "#D9ECFF" : (parent.hovered ? "#F0F8FF" : "transparent"))
                }
            }

            // 下拉箭头指示器 - 自定义箭头样式
            indicator: Canvas {
                x: styledCombo.width - width - 8
                y: styledCombo.topPadding + (styledCombo.availableHeight - height) / 2
                width: 12
                height: 8
                contextType: "2d"

                // 绘制箭头
                onPaint: {
                    var ctx = getContext("2d")
                    ctx.reset()
                    // 箭头颜色：跟随主色，hover/down 时加深
                    ctx.strokeStyle = (styledCombo.hovered || styledCombo.down) ? "#0B7CDB" : "#1296FF"
                    // 线条宽度
                    ctx.lineWidth = 2
                    ctx.beginPath()
                    // 绘制三角形箭头路径
                    // 起点：左上角
                    ctx.moveTo(0, 0)
                    // 中点：底部中心
                    ctx.lineTo(width / 2, height)
                    // 终点：右上角
                    ctx.lineTo(width, 0)
                    // 描边绘制
                    ctx.stroke()
                }
            }
        }

        Text {
            Layout.fillWidth: true
            color: "#999"
            font.pointSize: 10
            text: "提示：自定义了背景、内容文本、下拉项和箭头四个部分"
        }

        Item { Layout.fillHeight: true }
    }
}

关键逻辑解析

1. background：三态配色

Rectangle 的 color 和 border.color 都根据 ComboBox 的状态属性取不同值：

状态属性	含义	本 demo 的表现
`hovered`	鼠标悬停	淡蓝底、浅蓝边框
`down`	按下/弹出中	更深的蓝底
`activeFocus`	键盘焦点	主色描边加粗到 2px

坑 1：绑定循环。 注释里特别强调不要在 background 里引用 styledCombo.width/height。background 默认会自动铺满整个控件，手动设尺寸会跟 implicitWidth/implicitHeight 互相依赖形成绑定循环（QML 会报警告）。indicator 里用 styledCombo.width 定位是因为它单独放在容器里，不参与背景尺寸计算，这是安全的。

2. contentItem：文本 + 避让箭头

Text 显示 displayText（所以 displayText 定制与样式可以共存），leftPadding: 10 留左内边距，rightPadding: styledCombo.indicator.width + 15 给右侧箭头留出位置，避免文字和箭头重叠。

3. delegate：高亮 + 悬停反馈

内容 Text 的 font.weight 和 color 跟随 parent.highlighted（当前高亮项），选中项主色加粗。
背景 Rectangle 按 highlighted / down / hovered 三级取色，与主框配色呼应。

坑 2：font 是 group property。 QML 里 font 是一组属性（family、pixelSize、weight...），不能先整体赋值 font: styledCombo.font 再修改子属性，会报"重复赋值"。正确写法是逐个设置 font.family、font.pixelSize、font.weight。

4. indicator：Canvas 画箭头

Canvas 用 2D 上下文手绘一个倒三角：

contextType: "2d" 声明上下文类型，onPaint 里 getContext("2d") 取上下文；
moveTo(0, 0) → lineTo(width / 2, height) → lineTo(width, 0) 画出 V 字路径，stroke() 描边；
颜色跟随 hovered/down 加深，与主框状态联动；
y 用 topPadding + (availableHeight - height) / 2 在内容区内垂直居中。

运行验证

用 Qt Creator 打开 qml_combobox/CMakeLists.txt；
按 Ctrl+R 运行；
"样式自定义"下切到"自定义样式"：鼠标悬停、按下、键盘 Tab 聚焦，分别观察外框和箭头颜色变化；
展开下拉列表，悬停和高亮项的颜色应与主框配色一致。

扩展复用方向

把这套四件套封装成一个 MyComboBox.qml，项目里统一引用，一套样式处处一致。
background 可以升级为渐变或圆角 + 阴影，indicator 换成图标图片（Image）更省事。
结合前面学的 displayText、分组、多列，自定义样式 + 复杂内容可以同时生效。

已验证环境：

Qt 版本：Qt 6.8.2 / Qt 6.11.1
操作系统：Windows 11
GitHub：QML-Minimal-Demos/qml_combobox