如何创建可在QML中实例化的单例？兼顾C++/Python侧特性

一、修复Python单例崩溃问题 #

当前元类拦截__call__的单例实现会干扰QML引擎的实例化流程，导致QApplication未完全就绪时创建对象，引发SIGSEGV错误。改用类内部静态实例+显式获取方法的方式，避免冲突：

from PySide6.QtCore import QObject, Signal, Property, QmlElement
from PySide6.QtQml import QmlSingleton

# 单例基类，不使用元类拦截实例化
class BaseQuery(QObject):
    _instance = None

    @classmethod
    def instance(cls):
        if not cls._instance:
            cls._instance = cls()
        return cls._instance

# 注册为QML单例，同时保留Python侧单例逻辑
@QmlElement
@QmlSingleton
class MainQuery(BaseQuery):
    def __init__(self, parent=None):
        super().__init__(parent)
        self._graphql = ""
        self._data = ""

    # GraphQL查询属性（带变化通知）
    graphqlChanged = Signal(str)
    def _get_graphql(self):
        return self._graphql
    def _set_graphql(self, value):
        if self._graphql != value:
            self._graphql = value
            self.graphqlChanged.emit()
    graphql = Property(str, _get_graphql, _set_graphql, notify=graphqlChanged)

    # 查询结果数据属性（带变化通知）
    dataChanged = Signal(str)
    def _get_data(self):
        return self._data
    def _set_data(self, value):
        if self._data != value:
            self._data = value
            self.dataChanged.emit()
    data = Property(str, _get_data, _set_data, notify=dataChanged)

二、QML侧属性绑定与跨文件复用 #

方案1：上下文属性注入（推荐） #

在Python主程序中初始化单例，将其作为全局上下文属性传入QML，既保证单例唯一性，又能直接绑定属性：

Python主程序：

from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine

if __name__ == "__main__":
    app = QGuiApplication([])
    engine = QQmlApplicationEngine()

    # 初始化单例并注入QML上下文
    main_query = MainQuery.instance()
    engine.rootContext().setContextProperty("MainQuery", main_query)

    engine.load("main.qml")
    app.exec()

main.qml：直接绑定单例属性，无需重复实例化

Item{
    Text{
        text: MainQuery.data
    }

    // 初始化GraphQL查询
    Component.onCompleted: {
        MainQuery.graphql = `query MainQuery{...}`
    }
}

otherfile.qml：跨文件直接复用单例

Item{
    Text{
        text: MainQuery.data
    }
}

方案2：QML内初始化单例属性（进阶） #

若需在QML中设置初始属性，可通过辅助组件保证初始化仅执行一次：

// SingletonInitializer.qml
Item{
    property string initialGraphql

    Component.onCompleted: {
        // 仅在首次使用时初始化属性
        if (MainQuery.graphql === "") {
            MainQuery.graphql = initialGraphql
        }
    }
}

main.qml：

Item{
    SingletonInitializer{
        initialGraphql: `query MainQuery{...}`
    }

    Text{
        text: MainQuery.data
    }
}

otherfile.qml：直接使用单例属性

Item{
    Text{
        text: MainQuery.data
    }
}

三、关键注意事项 #

• 禁止在QML中多次实例化单例类，通过上下文属性或QmlSingleton注册确保全局唯一。
• Python侧单例实现不要拦截QML元素的__call__方法，改用instance()显式获取实例，避免与QML引擎流程冲突。
• 所有需要绑定的属性必须通过Qt的Property机制实现，并附带notify信号，否则QML无法感知属性变化。

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