QML QtQuick自定义CheckBox显示原生复选框问题及修复方案

Qt 6.2.1环境下混用QtQuick 2.15模块时，若未显式指定Quick Controls样式，运行时会默认加载当前系统的原生控件样式。原生样式的绘制逻辑优先级高于用户自定义的indicator、contentItem属性，会在自定义绘制层上方额外渲染默认的原生复选框，导致自定义样式被覆盖。

按优先级选择以下任意一种方案即可解决：

• 统一模块版本：Qt 6版本支持无版本号导入QML模块，会自动匹配当前环境的适配版本，从根源避免跨版本兼容问题。将QML文件头部的导入语句替换为：

import QtQuick
import QtQuick.Controls

不要保留Qt 5时代的import QtQuick 2.15写法。

• 强制使用非原生基础样式：如果需要兼容旧版本QML代码，可强制指定控件使用Basic样式，屏蔽原生样式绘制。两种实现方式二选一即可：
  1. C++端设置：在main函数中加载QML文件前添加代码，需提前引入<QQuickStyle>头文件，工程配置中链接QuickControls2模块：

  QQuickStyle::setStyle("Basic");
  

  2. 配置文件设置：在项目资源根目录添加qtquickcontrols2.conf文件，写入以下配置，无需修改C++代码：

  [Controls]
  Style=Basic
  

• 显式屏蔽原生背景绘制：如果需要保留其他控件的原生样式效果，仅自定义CheckBox，只需在自定义CheckBox代码中显式覆盖background属性，打断原生样式的绘制链路：

CheckBox {
    id: control
    text: qsTr("CheckBox")
    checked: true

    // 置空默认背景，屏蔽原生样式的复选框绘制
    background: null

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 3
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 2
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}

方案生效后，原生复选框的叠层会完全消失，选中、选中悬停、未选中悬停、默认无操作四种状态都会按照自定义代码的颜色、尺寸规则正常渲染。

内容的提问来源于stack exchange，提问作者David