QT 6.5.1编译QML代码出现背景自定义不支持运行时错误求助

问题场景 #

QML代码在QT 6.0.4编译运行正常，但升级到QT 6.5.1后出现运行时错误。

错误信息 #

QML Rectangle: The current style does not support customization of this control (property: "background" item: QQuickRectangle(0x22c49ddefc0, parent=0x0, geometry=0,0 100x40)). Please customize a non-native style (such as Basic, Fusion, Material, etc)

报错代码片段 #

Button {
    id: listen_btn
    text: "Press Me"
    font.pixelSize: 18
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        border.width: 1
    }
}

解决方法 #

QT 6.5.x起，原生系统样式（如Windows、macOS原生样式）不再允许自定义控件的background属性，需切换到非原生样式（如Basic、Fusion、Material等），以下是两种常用实现方式：

1. 全局设置样式（推荐） #

在C++的main函数中指定全局使用非原生样式，所有控件都会遵循该样式：

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQuickStyle>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    // 设置全局样式为Fusion，也可替换为"Basic"或"Material"
    QQuickStyle::setStyle("Fusion");

    QQmlApplicationEngine engine;
    const QUrl url(u"qrc:/main.qml"_qs);
    QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
                     &app, [url](QObject *obj, const QUrl &objUrl) {
        if (!obj && url == objUrl)
            QCoreApplication::exit(-1);
    }, Qt::QueuedConnection);
    engine.load(url);

    return app.exec();
}

2. 单个Button指定样式 #

仅给需要自定义背景的Button单独设置非原生样式，不影响其他控件：

import QtQuick.Controls 2.15
import QtQuick.Controls.Fusion 2.15 // 导入Fusion样式模块

Button {
    id: listen_btn
    text: "Press Me"
    font.pixelSize: 18
    // 使用Fusion样式，并自定义背景
    style: Fusion.ButtonStyle {
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            border.width: 1
            // 可选：添加按钮按下状态的颜色变化
            color: control.pressed ? "#e0e0e0" : "#ffffff"
        }
    }
}

原因说明 #

QT 6.5.x对控件样式系统做了调整，原生系统样式依赖系统自身的绘制逻辑，无法兼容自定义背景元素的替换操作，因此必须使用非原生样式才能实现background的自定义。

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