QQmlEngine Class

成员函数文档

[explicit] QQmlEngine::QQmlEngine(QObject *parent = nullptr)

使用给定的parent 创建一个新的QQmlEngine。

[override virtual noexcept] QQmlEngine::~QQmlEngine()

销毁QQmlEngine 。

在此引擎上创建的任何QQmlContext 都将失效，但不会被销毁（除非它们隶属于QQmlEngine 对象）。

有关清理 JS 引擎的详细信息，请参阅 ~QJSEngine()。

void QQmlEngine::addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)

设置用于处理通过image: URL 方案请求的图像的图像提供程序（provider ），其主机为providerId 。该图像提供程序（QQmlEngine ）将接管provider 。

图像提供程序支持 pixmap 和多线程图像请求。有关实现和使用图像提供程序的详细信息，请参阅QQuickImageProvider 文档。

在加载任何 QML 源文件之前，应将所有必需的图像提供程序添加到引擎中。

另请参阅 removeImageProvider()、QQuickImageProvider 以及QQmlImageProviderBase 。

void QQmlEngine::addImportPath(const QString &path)

将path 添加为引擎在基于 URL 的目录结构中搜索已安装模块的目录。Qt 假定path 下的所有文件和文件夹均来自可信来源。

path 可以是本地文件系统目录、Qt 资源路径（:/imports ）、Qt 资源URL（qrc:/imports ）或普通 URL。

path 将在添加到导入路径列表之前被转换为规范形式。

新添加的path 将位于importPathList() 的首位。

另请参阅 setImportPathList()、QML 模块 和QML 导入路径

void QQmlEngine::addPluginPath(const QString &path)

将path 添加为引擎搜索导入模块（在qmldir 文件中引用）的原生插件的目录。Qt 假定path 下的所有文件和文件夹均来自可信来源。

默认情况下，该列表仅包含. ，即引擎会在qmldir 文件所在的目录中进行搜索。

新添加的path 将排在pluginPathList() 列表的首位。

另请参阅 setPluginPathList()。

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

添加一个urlInterceptor ，用于在QML中解析URL时使用。这同样适用于用于加载脚本文件和QML类型的URL。在引擎加载文件期间，不应修改URL拦截器，否则URL选择可能会出现不一致。如果提供了多个URL拦截器，则对于每个URL，它们将按添加的顺序依次被调用。

QQmlEngine 不会获取拦截器的所有权，也不会将其删除。

QUrl QQmlEngine::baseUrl() const

返回此引擎的基准 URL。仅当向 `QQmlComponent ` 构造函数传递相对 URL 时，基准 URL 才会用于解析组件。

如果未显式设置基 URL，则该方法返回应用程序的当前工作目录。

另请参阅 setBaseUrl()。

void QQmlEngine::clearComponentCache()

清除引擎的内部组件缓存。

此函数会销毁引擎先前加载的大多数组件的属性元数据。其实现方式是将引擎组件缓存中未被引用的组件移除。它不会移除仍被引用的组件，因为那样几乎肯定会导致后续运行时发生崩溃。

如果没有组件被引用，该函数将使引擎恢复到不包含任何已加载组件数据的状态。这在需要重新加载先前组件集中的一个较小子集，或加载先前已加载组件的新版本时可能很有用。

一旦组件缓存被清空，必须先加载组件，才能创建任何新对象。

作为一般经验法则，请确保在清除组件缓存时，没有由 QML 组件创建的对象仍处于活动状态。

另请参阅 trimComponentCache() 和clearSingletons()。

void QQmlEngine::clearSingletons()

清除引擎拥有的所有单例。

此函数将释放所有单例实例，并删除其中由引擎拥有的任何 QObject 对象。这有助于确保在调用clearComponentCache() 之前，不会残留任何由 QML 创建的对象。

如果引擎拥有基于 `QObject` 的单例实例，则持有该实例的 QML 属性将变为空；如果引擎不拥有该单例，则该属性将保留其值。通过访问现有的由 QML 创建的对象不会自动重新创建单例。只有在实例化新组件时，单例才会被重新创建。

另请参阅 clearComponentCache()。

[static] QQmlContext *QQmlEngine::contextForObject(const QObject *object)

返回object 的QQmlContext ，如果未设置上下文，则返回nullptr。

当QQmlEngine 实例化QObject 时，会自动为其分配一个内部上下文。此类内部上下文为只读，无法对其设置上下文属性。

另请参阅 setContextForObject()、qmlContext()、qmlEngine() 以及QQmlContext::setContextProperty()。

[override virtual protected] bool QQmlEngine::event(QEvent *e)

重写了：QObject::event(QEvent *e)。

[signal] void QQmlEngine::exit(int retCode)

当引擎加载的 QML 希望以指定的返回代码retCode 退出事件循环时，会发出此信号。

另请参阅 quit()。

QQmlImageProviderBase *QQmlEngine::imageProvider(const QString &providerId) const

如果找到了为providerId 设置的图像提供程序，则返回该提供程序；否则返回nullptr 。

另请参阅 QQuickImageProvider 。

QStringList QQmlEngine::importPathList() const

返回引擎在基于 URL 的目录结构中搜索已安装模块的目录列表。

例如，如果路径中包含/opt/MyApp/lib/imports ，那么导入com.mycompany.Feature 的 QML 文件将导致QQmlEngine 在/opt/MyApp/lib/imports/com/mycompany/Feature/ 中查找该模块提供的组件。需要一个qmldir 文件来定义类型版本映射，以及可能的 QML 扩展插件。

默认情况下，该列表包含“QML 导入路径”中提到的路径。

另请参阅 addImportPath() 和setImportPathList()。

QQmlIncubationController *QQmlEngine::incubationController() const

返回当前设置的孵化控制器；如果未设置控制器，则返回 0。

另请参阅 setIncubationController()。

QUrl QQmlEngine::interceptUrl(const QUrl &url, QQmlAbstractUrlInterceptor::DataType type) const

对给定的type 中的指定url 运行当前的 URL 拦截器，并返回结果。

[since 6.6] void QQmlEngine::markCurrentFunctionAsTranslationBinding()

如果在此方法在 QML 绑定中的某个函数内部被调用，则该绑定将被视为转换绑定。

class I18nAwareClass : public QObject {

  //...

   QString text() const
   {
        if (auto engine = qmlEngine(this))
            engine->markCurrentFunctionAsTranslationBinding();
        return tr("Hello, world!");
   }
};

该函数于 Qt 6.6 中引入。

另请参阅 QQmlEngine::retranslate 。

QNetworkAccessManager *QQmlEngine::networkAccessManager() const

返回一个通用的QNetworkAccessManager ，该 可被由该引擎实例化的任何QML类型使用。

如果已设置QQmlNetworkAccessManagerFactory ，但尚未创建QNetworkAccessManager ，则将使用QQmlNetworkAccessManagerFactory 来创建QNetworkAccessManager ；否则，返回的QNetworkAccessManager 将不会设置代理或缓存。

另请参阅 setNetworkAccessManagerFactory()。

QQmlNetworkAccessManagerFactory *QQmlEngine::networkAccessManagerFactory() const

返回当前的QQmlNetworkAccessManagerFactory 。

另请参阅 setNetworkAccessManagerFactory()。

QString QQmlEngine::offlineStorageDatabaseFilePath(const QString &databaseName) const

返回标识符为databaseName 的Local Storage 数据库所在（或将位于）的文件路径。

另请参阅 LocalStorage.openDatabaseSync() 。

[signal, since 6.5] void QQmlEngine::offlineStoragePathChanged()

当offlineStoragePath 发生变化时，会发出此信号。

该函数在 Qt 6.5 中引入。

bool QQmlEngine::outputWarningsToStandardError() const

如果警告消息除了通过warnings()信号发出外，还会输出到stderr，则返回true；否则返回false。

默认值为 true。

另请参阅 setOutputWarningsToStandardError()。

QStringList QQmlEngine::pluginPathList() const

返回引擎用于搜索已导入模块（在qmldir 文件中引用）的原生插件的目录列表。

默认情况下，该列表仅包含. ，即引擎会在qmldir 文件所在的目录中进行搜索。

另请参阅 addPluginPath() 和setPluginPathList()。

[signal] void QQmlEngine::quit()

当引擎加载的 QML 希望退出时，会发出此信号。

另请参阅 exit()。

void QQmlEngine::removeImageProvider(const QString &providerId)

移除providerId 的图像提供程序。

另请参阅 addImageProvider() 和QQuickImageProvider 。

void QQmlEngine::removeUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

移除先前通过 `addUrlInterceptor` 添加的 `urlInterceptor `。在引擎加载文件期间，不应修改 URL 拦截器，否则 URL 选择可能会出现不一致。

此操作不会删除拦截器，仅将其从引擎中移除。之后，您可以在同一引擎或另一个引擎上重新使用它。

[slot] void QQmlEngine::retranslate()

刷新所有使用已标记为待翻译字符串的绑定表达式。

在使用 `QCoreApplication::installTranslator` 安装新的翻译器后，请调用此函数，以确保您的用户界面显示最新的翻译内容。

QQmlContext *QQmlEngine::rootContext() const

返回引擎的根上下文。

根上下文由QQmlEngine 自动创建。所有由引擎实例化的 QML 组件实例均可访问的数据，应放置在根上下文中。

仅应供部分组件实例使用的额外数据，应添加到作为根上下文子节点的子上下文中。

void QQmlEngine::setBaseUrl(const QUrl &url)

将此引擎的基础 URL 设置为url 。

另请参阅 baseUrl()。

[static] void QQmlEngine::setContextForObject(QObject *object, QQmlContext *context)

将“object ”的QQmlContext 设置为context 。如果“object ”已有上下文，则会输出警告，但不会更改该上下文。

当QQmlEngine 实例化QObject 时，上下文会自动设置。

另请参阅 contextForObject()。

[since 6.12] bool QQmlEngine::setExternalSingletonInstance(QAnyStringView moduleName, QAnyStringView typeName, QObject *instance)

设置 QML 引擎中用于指定类型的单例实例。

此函数允许您手动设置一个从 `QObject` 派生的实例，作为该引擎在 QML 中的单例。这使您能够控制该实例的创建。此功能在多种场景下都很有用，包括当您的单例需要与后端组件通信的情况。

该函数接受moduleName 和typeName 作为参数，用于指定要设置的单例类型，并接受instance 作为要设置的实例。该类型必须已作为QML单例类型注册，理想情况下应使用QML_ELEMENT 和QML_SINGLETON进行注册。如果该模块尚未加载，则此时会自动加载。

该函数在成功时返回 true，失败时返回 false。如果发生错误，将发出详细说明错误原因的警告。

例如，该单例可能需要一个后端服务才能工作，此时可以按如下方式声明：

class CppSingleton: public QObject {
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
    QML_UNCREATABLE("Provided via QQmlEngine::setExternalSingletonInstance")
    // Q_PROPERTY(...)
public:
    explicit CppSingleton(BackendService *service); // constructor taking a reference to something MySingleton needs
    // members, Q_INVOKABLE functions, etc.
};

在应用程序初始化时，你可以执行以下操作：

    // create and setup the backend service
    BackendService service;

    // create your singleton instance
    CppSingleton singleton(&service);
    QQmlApplicationEngine engine;
    engine.setExternalSingletonInstance("com.company.myApp", "MySingleton", &singleton);
    engine.loadFromModule("com.company.myApp", "Main");

请注意，这里没有提供默认构造函数或静态 create 函数，而是使用了QML_UNCREATABLE() 宏，以表明该项不能由 QML 引擎创建。

每个类型和引擎仅能设置一次单例实例，且必须在任何使用之前完成设置。一旦单例实例被创建或设置，就无法再通过此函数进行设置，因此应在 QML 中首次使用该实例之前完成设置。

引擎不会接管您传递的实例，除非您通过使用QJSEngine::setObjectOwnership() 显式指示引擎这样做。

此函数于 Qt 6.12 中引入。

void QQmlEngine::setImportPathList(const QStringList &paths)

将paths 设置为引擎在基于URL的目录结构中搜索已安装模块的目录列表。Qt 假定paths 下的所有文件和文件夹均来自可信来源。

默认情况下，此列表包含“QML 导入路径”中提到的路径。

另请参阅 importPathList() 和addImportPath()。

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

设置引擎的孵化器controller 。引擎只能有一个活动的控制器，且不会对其拥有所有权。

另请参阅 incubationController()。

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

设置用于创建QNetworkAccessManager 的factory 。

QNetworkAccessManager 该设置用于处理 QML 的所有网络访问。通过实现工厂类，可以创建具有专用缓存、代理和 Cookie 支持的自定义QNetworkAccessManager 。

必须在执行引擎之前设置该工厂。

另请参阅 networkAccessManagerFactory()。

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

设置是否将警告消息输出到 stderr，即enabled 。

如果enabled 为true，QML生成的任何警告消息都将输出到stderr，并通过warnings()信号发出。如果enabled 为false，则仅会发出warnings()信号。这允许应用程序自行处理警告输出。

默认值为 true。

另请参阅 outputWarningsToStandardError()。

void QQmlEngine::setPluginPathList(const QStringList &paths)

将引擎用于搜索已导入模块（在qmldir 文件中引用）的原生插件的目录列表设置为paths 。Qt假定paths 下的所有文件和文件夹均来自可信来源。

默认情况下，该列表仅包含. ，即引擎会在qmldir 文件所在的目录中进行搜索。

另请参阅 pluginPathList() 和addPluginPath()。

template <typename T> T QQmlEngine::singletonInstance(int qmlTypeId)

返回在qmlTypeId 下注册的单例类型的实例。

模板参数T可以是QJSValue ，也可以是QObject 派生类型的指针，具体取决于单例的注册方式。如果尚未创建T的实例，则此时会创建一个。如果qmlTypeId 不代表有效的单例类型，则返回默认构造的QJSValue 或nullptr 。

QObject* 示例：

class MySingleton : public QObject {
    Q_OBJECT

    // Register as default constructed singleton.
    QML_ELEMENT
    QML_SINGLETON

    static int typeId;
    // ...
};

    MySingleton::typeId = qmlTypeId(...);

    // Retrieve as QObject*
    QQmlEngine engine;
    MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

QJSValue 示例：

    // Register with QJSValue callback
    int typeId = qmlRegisterSingletonType(...);

    // Retrieve as QJSValue
    QQmlEngine engine;
    QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

建议将 QML 类型 ID 存储在单例类中，例如作为静态成员。通过qmlTypeId() 进行查找的开销较大。

另请参阅 QML_SINGLETON、qmlRegisterSingletonType() 和qmlTypeId()。

[since 6.5] template <typename T> T QQmlEngine::singletonInstance(QAnyStringView uri, QAnyStringView typeName)

返回由模块 `uri` 定义的、名为 `typeName ` 的单例类型的实例。

该方法可作为调用 `qmlTypeId ` 并随后调用基于 id 的 `singletonInstance` 重载方法的替代方案。当仅需对单例进行一次性初始化时，此方法非常方便；如果需要重复访问该单例，缓存其 `typeId` 将通过 `type-id based overload` 实现更快的后续访问。

模板参数T可以是 `QJSValue `，也可以是 `QObject` 派生类型的指针，具体取决于单例的注册方式。如果尚未创建T的实例，则此时会创建一个。如果 `typeName ` 不代表有效的单例类型，则返回默认构造的 `QJSValue ` 或 `nullptr `。

    QQmlEngine engine;
    MySingleton *singleton = engine.singletonInstance<MySingleton *>("mymodule", "MySingleton");

该函数在 Qt 6.5 中引入。

另请参见 QML_SINGLETON、qmlRegisterSingletonType() 和qmlTypeId()。

void QQmlEngine::trimComponentCache()

清理引擎的内部组件缓存。

此函数会销毁所有已加载但当前未被使用的组件的属性元数据。

如果组件本身存在任何实例、使用该组件的其他组件的任何实例，或者由这些组件实例化的任何对象，则该组件被视为正在使用中。

另请参阅 clearComponentCache()。

QList<QQmlAbstractUrlInterceptor *> QQmlEngine::urlInterceptors() const

返回当前处于活动状态的 URL 拦截器列表。

[signal] void QQmlEngine::warnings(const QList<QQmlError> &warnings)

当 QML 生成warnings 消息时，会触发此信号。