桌面应用 / 系统课时
向 QML 暴露单例服务对象
向 QML 暴露单例服务对象
本篇解决 QML 页面访问共享 C++ 服务的问题,通过注册单例对象让配置、会话等全局能力拥有稳定入口,同时避免在页面之间反复传递同一个实例。
学习目标
- 理解 QML 单例对象适合解决的共享服务访问问题。
- 掌握将 C++ 服务注册为 QML 单例类型的方法。
- 能够判断单例服务的使用边界,避免滥用全局状态。
为什么需要 QML 单例服务
在桌面应用中,配置管理、用户会话、权限信息或设备状态通常由一个 C++ 对象负责维护。如果每个页面都通过属性传递该对象,页面之间会形成大量耦合。
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 单例最大的风险不是技术实现,而是职责失控。当多个模块开始依赖同一个巨大服务对象时,修改任何功能都可能影响整个应用。
设计单例时应保持接口稳定、职责单一,让它成为共享能力入口,而不是所有业务代码的集中位置。
按自己的节奏,确认真正理解。