如何在Qt6中使用CMake创建纯QML单例类型？

架构老林

2026-7-20

纯QML实现Qt6单例类型（无需C++）

问题背景

你尝试通过pragma Singleton定义QML单例，但直接导入目录后无法访问属性；Qt6构建时自动生成qmldir导致手动配置无效，且不想通过C++的qmlRegisterSingletonType注册单例。

解决方案

方法1：利用Qt6自动模块生成（原生单例规范）

如果接受通过模块URI导入，可通过以下步骤让Qt6自动识别单例：

在themes目录下创建qmldir.in文件（后缀.in是关键，Qt构建系统会自动处理生成最终的qmldir）：

singleton Theme 1.0 Theme.qml

在CMakeLists.txt中注册该QML模块（使用qmake则对应调整配置）：

qt_add_qml_module(ThemeModule
    URI ThemeModule
    VERSION 1.0
    QML_FILES
        themes/Theme.qml
    RESOURCES
        themes/qmldir.in
)

在主QML文件中导入模块并使用：

import QtQuick
import QtQuick.Window
import ThemeModule 1.0

Window {
    color: Theme.color
    visible: true
    width: 640
    height: 480
}

方法2：全局上下文属性（无模块依赖，直接访问）

若希望像本地QML文件一样直接访问，无需模块导入，可将单例实例挂载到全局上下文：

// Main.qml
import QtQuick
import QtQuick.Window

Window {
    id: mainWindow
    visible: true
    width: 640
    height: 480

    // 定义单例实例
    QtObject {
        id: internalTheme
        readonly property string color: "indigo"
        // 可扩展更多全局配置属性
        readonly property int fontSize: 14
    }

    // 组件加载完成后将实例设为全局属性
    Component.onCompleted: {
        mainWindow.engine.rootContext.setContextProperty("Theme", internalTheme)
    }

    // 示例使用
    Text {
        text: "全局单例测试"
        color: Theme.color
        font.pixelSize: Theme.fontSize
        anchors.centerIn: parent
    }
}

这种方式下，项目中所有QML文件都能直接访问Theme对象，无需额外导入，完全通过QML实现。