松岛川树
blog2024年12月28日· 约 16 分钟

'Qt 中实现系统主题感知'

Twitter 微博

Qt 中实现系统主题感知

Qt 中实现系统主题感知 在现代桌面应用程序开发中，系统主题感知是一项重要的功能，它使得应用程序能够根据用户的系统主题设置（如深色模式或浅色模式）自动调整其外观。 Qt 作为一个跨平台的C++图形用户界面应用程序开发框架，提供了丰富的工具和类来实现这一功能。

【写在前面】#

在现代桌面应用程序开发中，系统主题感知是一项重要的功能，它使得应用程序能够根据用户的系统主题设置（如深色模式或浅色模式）自动调整其外观。

Qt 作为一个跨平台的C++图形用户界面应用程序开发框架，提供了丰富的工具和类来实现这一功能。

【正文开始】#

一、使用效果

image

二、系统主题感知助手类（SystemThemeHelper）

SystemThemeHelper类是一个封装了系统主题感知功能的Qt对象。它主要通过读取系统设置和监听系统主题变化来更新应用程序的主题颜色和颜色方案。

  1. 类定义与属性

    在systemthemehelper.h中，SystemThemeHelper类继承自QObject，并定义了两个属性：themeColor和colorScheme。这两个属性分别表示当前的主题颜色和颜色方案（深色、浅色或无）。

    class SystemThemeHelper : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QColor themeColor READ themeColor NOTIFY themeColorChanged)
    Q_PROPERTY(SystemThemeHelper::ColorScheme colorScheme READ colorScheme NOTIFY colorSchemeChanged)
    class=class="hljs-string">"hljs-comment">// ...
};

    ColorScheme是一个枚举类，定义了三种颜色方案：None、Dark和Light。

  2. 构造函数与析构函数

    SystemThemeHelper的构造函数初始化了一些私有成员变量，并启动了一个定时器，用于定期更新主题颜色和颜色方案。析构函数则负责清理资源。

    SystemThemeHelper::SystemThemeHelper(QObject *parent)
    : QObject{parent}, d_ptr(new SystemThemeHelperPrivate(this))
{
    Q_D(SystemThemeHelper);
    d->m_themeColor = getThemeColor();
    d->m_colorScheme = getColorScheme();
    d->m_timer.start(class="hljs-number">200, this);
    class=class="hljs-string">"hljs-comment">#ifdef Q_OS_WIN
    initializeFunctionPointers();
    class=class="hljs-string">"hljs-comment">#endif
}

SystemThemeHelper::~SystemThemeHelper()
{
    class=class="hljs-string">"hljs-comment">// 清理资源
}

  3. 获取主题颜色和颜色方案

    getThemeColor和getColorScheme是两个不可用于绑定的方法，它们立即返回当前的主题颜色和颜色方案，但不会触发任何更新通知。这两个方法主要用于快速获取当前设置，而不关心后续的变化。

    QColor SystemThemeHelper::getThemeColor() const
{
    Q_D(const SystemThemeHelper);
    class=class="hljs-string">"hljs-comment">#ifdef Q_OS_WIN
    return QColor::fromRgb(d->m_themeColorSettings.value(class="hljs-string">"ColorizationColor").toUInt());
    class=class="hljs-string">"hljs-comment">#endif
}

SystemThemeHelper::ColorScheme SystemThemeHelper::getColorScheme() const
{
    Q_D(const SystemThemeHelper);
    class=class="hljs-string">"hljs-comment">#if QT_VERSION >= QT_VERSION_CHECK(class="hljs-number">6, class="hljs-number">5, class="hljs-number">0)
    const auto scheme = QGuiApplication::styleHints()->colorScheme();
    return scheme == Qt::ColorScheme::Dark ? ColorScheme::Dark : ColorScheme::Light;
    class=class="hljs-string">"hljs-comment">#else
    class=class="hljs-string">"hljs-comment">#ifdef Q_OS_WIN
    return !d->m_colorSchemeSettings.value(class="hljs-string">"AppsUseLightTheme").toBool() ? ColorScheme::Dark : ColorScheme::Light;
    #else class=class="hljs-string">"hljs-comment">//linux
    const QPalette defaultPalette;
    const auto text = defaultPalette.color(QPalette::WindowText);
    const auto window = defaultPalette.color(QPalette::Window);
    return text.lightness() > window.lightness() ? ColorScheme::Dark : ColorScheme::Light;
    #endif class=class="hljs-string">"hljs-comment">// Q_OS_WIN
    #endif class=class="hljs-string">"hljs-comment">// QT_VERSION
}

  4. 更新主题颜色和颜色方案

    themeColor和colorScheme是两个可用于绑定的方法，它们返回当前的主题颜色和颜色方案，并在值发生变化时发出通知。这两个方法内部调用了私有成员函数的更新逻辑。

    QColor SystemThemeHelper::themeColor()
{
    Q_D(SystemThemeHelper);
    d->_updateThemeColor();
    return d->m_themeColor;
}

SystemThemeHelper::ColorScheme SystemThemeHelper::colorScheme()
{
    Q_D(SystemThemeHelper);
    d->_updateColorScheme();
    return d->m_colorScheme;
}

  5. 设置窗口标题栏模式

    setWindowTitleBarMode方法允许设置窗口标题栏的模式（深色或浅色）。这个方法在Windows平台上通过调用 DWM API 实现，而在其他平台上则不支持。

    bool SystemThemeHelper::setWindowTitleBarMode(QWindow *window, bool isDark)
{
    class=class="hljs-string">"hljs-comment">#ifdef Q_OS_WIN
    return bool(pDwmSetWindowAttribute ? !pDwmSetWindowAttribute(HWND(window->winId()), class="hljs-number">20, &isDark, sizeof(BOOL)) : false);
    class=class="hljs-string">"hljs-comment">#else
    return false;
    #endif class=class="hljs-string">"hljs-comment">//Q_OS_WIN
}

  6. 定时器事件处理

    timerEvent方法是一个虚函数，用于处理定时器事件。它定期调用更新函数来检查主题颜色和颜色方案是否发生变化，并在变化时发出通知。

    void SystemThemeHelper::timerEvent(QTimerEvent *)
{
    Q_D(SystemThemeHelper);
    d->_updateThemeColor();
    d->_updateColorScheme();
}

三、实现细节

SystemThemeHelperPrivate是SystemThemeHelper的私有实现类，它封装了所有的实现细节和状态变量。这个类主要负责读取系统设置、更新主题颜色和颜色方案，并发出通知。

  1. 构造函数与成员变量

    SystemThemeHelperPrivate的构造函数接收一个指向SystemThemeHelper的指针，并初始化成员变量。成员变量包括主题颜色、颜色方案、定时器和一些平台特定的设置对象。

    SystemThemeHelperPrivate::SystemThemeHelperPrivate(SystemThemeHelper *q)
    : q_ptr(q)
{
    class=class="hljs-string">"hljs-comment">// 初始化成员变量
}

  2. 更新函数

    _updateThemeColor和_updateColorScheme是两个更新函数，它们检查当前的主题颜色和颜色方案是否发生变化，并在变化时更新成员变量并发出通知。

    void SystemThemeHelperPrivate::_updateThemeColor()
{
    Q_Q(SystemThemeHelper);
    auto nowThemeColor = q->getThemeColor();
    if (nowThemeColor != m_themeColor) {
        m_themeColor = nowThemeColor;
        emit q->themeColorChanged();
    }
}

void SystemThemeHelperPrivate::_updateColorScheme()
{
    Q_Q(SystemThemeHelper);
    auto nowColorScheme = q->getColorScheme();
    if (nowColorScheme != m_colorScheme) {
        m_colorScheme = nowColorScheme;
        emit q->colorSchemeChanged();
    }
}

  3. 平台特定的实现

    在Windows平台上，SystemThemeHelperPrivate使用QSettings来读取系统主题设置，并使用DWM API来设置窗口标题栏的模式。这些实现细节被封装在条件编译块中，以确保跨平台的兼容性。

    class=class="hljs-string">"hljs-comment">#ifdef Q_OS_WIN
QSettings m_themeColorSettings{QSettings::UserScope, class="hljs-string">"Microsoft", class="hljs-string">"Windows\\DWM"};
QSettings m_colorSchemeSettings{QSettings::UserScope, class="hljs-string">"Microsoft", class="hljs-string">"Windows\\CurrentVersion\\Themes\\Personalize"};
static DwmSetWindowAttributeFunc pDwmSetWindowAttribute = nullptr;
class=class="hljs-string">"hljs-comment">// ...
static inline bool initializeFunctionPointers()
{
    class=class="hljs-string">"hljs-comment">// 初始化DWM API函数指针
}
#endif class=class="hljs-string">"hljs-comment">//Q_OS_WIN

四、如何使用

C++：

	SystemThemeHelper *helper = new SystemThemeHelper;
    QObject::connect(helper, &SystemThemeHelper::themeColorChanged, [helper]{
        qDebug() << helper->getThemeColor();
    });
    QObject::connect(helper, &SystemThemeHelper::colorSchemeChanged, [helper]{
        qDebug() << helper->getColorScheme();
    });

Qml：

import QtQuick class="hljs-number">2.15
import QtQuick.Window class="hljs-number">2.15

import DelegateUI.Utils class="hljs-number">1.0

Window {
    id: window
    width: class="hljs-number">640
    height: class="hljs-number">480
    visible: true
    title: qsTr(class="hljs-string">"SystemThemeHelper Test - ") + (themeHelper.colorScheme == SystemThemeHelper.Dark ? class="hljs-string">"Dark" : class="hljs-string">"Light")
    color: themeHelper.colorScheme == SystemThemeHelper.Dark ? class="hljs-string">"black" : class="hljs-string">"white"

    Behavior on color { ColorAnimation { } }

    SystemThemeHelper {
        id: themeHelper
        onThemeColorChanged: {
            console.log(class="hljs-string">"onThemeColorChanged:", themeColor);
        }
        onColorSchemeChanged: {
            setWindowTitleBarMode(window, themeHelper.colorScheme == SystemThemeHelper.Dark)
            console.log(class="hljs-string">"onColorSchemeChanged:", colorScheme);
        }
        Component.onCompleted: {
            console.log(class="hljs-string">"onColorSchemeChanged:", colorScheme);
            setWindowTitleBarMode(window, themeHelper.colorScheme == SystemThemeHelper.Dark)
        }
    }

    Text {
        anchors.centerIn: parent
        text: qsTr(class="hljs-string">"主题颜色")
        font.family: class="hljs-string">"微软雅黑"
        font.pointSize: class="hljs-number">32
        color: themeHelper.themeColor
    }
}

【结语】#

通过SystemThemeHelper类，我们可以在 Qt 应用程序中实现系统主题感知功能。

这个类封装了读取系统设置、更新主题颜色和颜色方案以及发出通知的逻辑，使得我们可以轻松地根据系统主题变化来调整应用程序的外观。

此外，通过条件编译和平台特定的实现，还确保了跨平台的兼容性。

最后：项目链接(多多star呀..⭐_⭐)：

Github: https://github.com/mengps/QmlControls

Gitee: https://gitee.com/MenPenS/QmlControls

上一篇

'Python读取栅格图像并对像元数据处理后导出到表格文件中'

下一篇

'NineData 社区版 V5.1.0 正式发布！AI Agent 能力全面释放，新增 48 种数据复制和对比链路'

相关文章

blog

'NineData 社区版 V5.1.0 正式发布！AI Agent 能力全面释放，新增 48 种数据复制和对比链路'

blog

'记一次微服务架构下的HTTP请求头“大小写”丢失排查之旅'

评论

© 2026 松岛川树