桌面应用 / 系统课时

向 QML 暴露单例服务对象

向 QML 暴露单例服务对象

本篇解决 QML 页面访问共享 C++ 服务的问题,通过注册单例对象让配置、会话等全局能力拥有稳定入口,同时避免在页面之间反复传递同一个实例。

学习目标

  • 理解 QML 单例对象适合解决的共享服务访问问题。
  • 掌握将 C++ 服务注册为 QML 单例类型的方法。
  • 能够判断单例服务的使用边界,避免滥用全局状态。

为什么需要 QML 单例服务

在桌面应用中,配置管理、用户会话、权限信息或设备状态通常由一个 C++ 对象负责维护。如果每个页面都通过属性传递该对象,页面之间会形成大量耦合。

QML 单例提供了一种类型级访问方式。页面只需要导入对应模块,就可以通过固定名称访问服务,而不需要知道对象在哪里创建。

适合单例的对象通常具有以下特点:

  • 生命周期与应用一致。
  • 由多个页面共同使用。
  • 不应该被频繁创建或销毁。

例如应用配置服务可以设计为单例:

QML 单例服务注册与页面访问关系示意图

注册 C++ 单例类型

Qt 6 中可以使用 QML_SINGLETON 宏配合 QML 类型注册机制,将 C++ 类暴露给 QML。

下面是一个最小配置服务示例:

cpp
// appsettings.h
#pragma once

#include <QObject>
#include <QtQml/qqmlregistration.h>

class AppSettings : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    Q_PROPERTY(QString language READ language WRITE setLanguage NOTIFY languageChanged)

public:
    explicit AppSettings(QObject *parent = nullptr)
        : QObject(parent), m_language("zh_CN") {}

    QString language() const { return m_language; }

    void setLanguage(const QString &value)
    {
        if (m_language == value)
            return;
        m_language = value;
        emit languageChanged();
    }

signals:
    void languageChanged();

private:
    QString m_language;
};

预期结果

text
C++ 类型 AppSettings 被注册为 QML 可访问单例类型。
QML 页面可以通过模块导入后访问 AppSettings。

完成类型注册后,QML 可以直接读取和修改属性:

qml
import QtQuick

Item {
    Text {
        text: AppSettings.language
    }
}

预期结果

text
页面显示当前语言配置,例如 zh_CN。

单例服务的使用边界

单例并不意味着所有业务逻辑都应该放进去。将大量页面状态、临时交互数据和业务流程都塞入单例,会让任何页面都能修改全局状态,增加测试难度。

更合理的划分方式是:

类型 是否适合作为单例
应用配置 适合
用户会话信息 适合
当前页面表单数据 不适合
复杂业务流程控制器 通常不适合

如果一个对象只服务于某个页面,优先通过属性注入或上下文对象传递,而不是注册为全局单例。

常见问题

QML 单例最大的风险不是技术实现,而是职责失控。当多个模块开始依赖同一个巨大服务对象时,修改任何功能都可能影响整个应用。

设计单例时应保持接口稳定、职责单一,让它成为共享能力入口,而不是所有业务代码的集中位置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

向 QML 暴露单例服务对象

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通