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)

设置provider ，用于通过图片：url 方案请求的图片，主机为providerId 。QQmlEngine 拥有provider 的所有权。

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

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

另请参阅 removeImageProvider(),QQuickImageProvider, 和QQmlImageProviderBase 。

void QQmlEngine::addImportPath(const QString &path)

在基于 URL 的目录结构中，添加path 作为引擎搜索已安装模块的目录。

path 可以是本地文件系统目录、Qt Resource路径 (:/imports)、Qt Resourceurl (qrc:/imports) 或 URL。

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

新添加的path 将首先出现在importPathList() 中。

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

void QQmlEngine::addPluginPath(const QString &path)

添加path 作为引擎搜索已导入模块（在qmldir 文件中引用）的本地插件的目录。

默认情况下，该列表只包含. ，即引擎在qmldir 文件本身的目录中搜索。

新添加的path 将首先出现在pluginPathList() 中。

另请参见 setPluginPathList()。

void QQmlEngine::addUrlInterceptor(QQmlAbstractUrlInterceptor *urlInterceptor)

在 QML 中解析 URL 时添加urlInterceptor 。这也适用于用于加载脚本文件和 QML 类型的 URL。在引擎加载文件时，不应修改 URL 拦截器，否则 URL 选择可能会不一致。如果给定了多个 URL 拦截器，将按照为每个 URL 添加拦截器的顺序调用。

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

QUrl QQmlEngine::baseUrl() const

返回此引擎的基本 URL。基本 URL 仅用于在向QQmlComponent 构造函数传递相对 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/ 中查找该模块提供的组件。定义类型版本映射和可能的 QML 扩展插件需要qmldir 文件。

默认情况下，该列表包含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

返回引擎的根上下文（root context）。

根上下文由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() 。

void QQmlEngine::setImportPathList(const QStringList &paths)

将paths 设置为引擎在基于 URL 的目录结构中搜索已安装模块的目录列表。

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

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

void QQmlEngine::setIncubationController(QQmlIncubationController *controller)

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

另请参阅 incubationController() 。

void QQmlEngine::setNetworkAccessManagerFactory(QQmlNetworkAccessManagerFactory *factory)

设置用于创建QNetworkAccessManager(s) 的factory 。

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

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

另请参阅 networkAccessManagerFactory().

void QQmlEngine::setOutputWarningsToStandardError(bool enabled)

将警告信息是否输出到 stderr 设置为enabled 。

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

默认值为 true。

另请参见 outputWarningsToStandardError()。

void QQmlEngine::setPluginPathList(const QStringList &paths)

将引擎搜索导入模块（在qmldir 文件中引用）的本地插件的目录列表设置为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 消息时会发出该信号。