class QQmlApplicationEngine

QQmlApplicationEngine 提供了一种方便的方法，可以从单个 QML 文件中加载应用程序。 更多…

摘要

方法

• def __init__()

• def rootObjects()

槽

• def load()

• 定义 loadData()

• 定义 loadFromModule()

• 定义 setExtraFileSelectors()

• 定义 setInitialProperties()

信号

• 定义 objectCreated()

• 定义 objectCreationFailed()

注意

本文档可能包含从 C++ 到 Python 自动翻译的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译中存在问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单来通知我们。

详细描述

此类结合了一个 QQmlEngine 和一个 QQmlComponent，以提供一个方便的方法来加载单个 QML 文件。它还向 QML 暴露了一些中心应用程序功能，这些功能通常由 C++/QML 混合应用程序从 C++ 控制。

可以这样使用

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine("main.qml");
    return app.exec();
}

与 QQuickView 不同，QQmlApplicationEngine 不会自动创建根窗口。如果您使用来自 Qt Quick 的视觉项，则需要将它们放置在 Window 内。

如果您不使用任何需要 QGuiApplication 的 QML 模块（例如 QtQuick），您也可以使用 QCoreApplication 与 QQmlApplicationEngine 一起使用。

默认 QQmlEngine 的配置更改列表

• 将 Qt 的 quit() 连接到 QCoreApplication::quit()

• 自动从主 QML 文件相邻的 i18n 目录加载翻译文件。

  • 翻译文件必须以“qml_”为前缀，例如 qml_ja_JP.qm。

• 当 QJSEngine::uiLanguage / Qt.uiLanguage 属性更改时，将重新加载翻译。

• 如果场景包含 QQuickWindow，将自动设置一个孵化控制器。

• 自动将 QQmlFileSelector 设置为 URL 拦截器，将文件选择器应用于所有 QML 文件和资产。

可以使用从 QQmlEngine 继承的方法进一步调整引擎行为。

__init__(uri, typeName[, parent=None])

参数：

• uri – 字符串

• typeName – 字符串

• parent – QObject

创建一个新的 QQmlApplicationEngine 并加载由 uri 和 typeName 指定的 QML 类型。这是作为一种便捷的方式提供的，与使用空构造函数并在之后调用 loadFromModule 是相同的。

__init__([parent=None])

参数：

parent – QObject

创建一个新的 QQmlApplicationEngine 并设置给定的 parent。您必须在稍后调用 load() 以加载 QML 文件。

__init__(filePath[, parent=None])

参数：

• filePath – 字符串

• parent – QObject

创建一个新的 QQmlApplicationEngine 并加载指定 filePath 的 QML 文件，它必须是一个本地文件路径。如果给出的是相对路径，则它将被解释为相对于应用程序的工作目录。

这是作为一种便捷提供的，与使用空构造函数并在之后调用 load 是相同的。

__init__(url[, parent=None])

参数：

• url – QUrl

• parent – QObject

创建一个新的 QQmlApplicationEngine 并加载指定 url 的 QML 文件。这是一种便捷方式，与使用空构造函数并在之后调用 load 是相同的。

load(filePath)

参数：

filePath – 字符串

加载位于 filePath 的根 QML 文件。 filePath 必须是本地文件的路径。如果 filePath 是相对路径，则被视为相对于应用程序的工作目录。文件定义的对象树将立即实例化。

如果在加载过程中发生错误，将使用 qWarning 打印错误信息。

load(url)

参数：

url – QUrl

加载位于 url 的根 QML 文件。对于本地文件 URL，文件定义的对象树将立即创建。对于远程 URL，将异步加载，侦听 objectCreated 信号以确定对象树何时就绪。

如果在加载过程中发生错误，将发出带有空指针参数的 objectCreated 信号，并使用 qWarning 打印错误信息。

loadData(data[, url=QUrl()])

参数：

• data – QByteArray

• url – QUrl

加载 data 中给出的 QML。由 data 定义的对象树将立即实例化。

如果指定了 url，则将其用作组件的基本 URL。这会影响数据中的相对路径和错误信息。

如果在加载过程中发生错误，将使用 qWarning 打印错误信息。

loadFromModule(uri, typeName)

参数：

• uri – 字符串

• typeName – 字符串

从由 uri 指定的模块加载 QML 类型 typeName。如果该类型来自远程 URL 位置的 QML 文件，则将异步加载类型。侦听 objectCreated 信号以确定对象树何时就绪。

如果在加载过程中发生错误，将发出带有空指针参数的 objectCreated 信号，并使用 qWarning 打印错误信息。

QQmlApplicationEngine engine;
engine.loadFromModule("QtQuick", "Rectangle");

注意

根据 uri 识别的模块将搜索在 导入路径 中，就像在 QML 文件内部执行 import uri 一样。如果无法在那里找到模块，则此函数将失败。

另请参阅

loadFromModule

objectCreated(object, url)

参数：

• object – QObject

• url – QUrl

此信号会在对象加载完成后发出。如果加载成功，object 包含对加载对象的指针；否则，指针为 NULL。

也会提供 url，它是对象来源的组件的地址。

注意

如果提供的组件路径是包含相对路径的 QString，则 url 将包含指向文件的完整解析路径。

objectCreationFailed(url)

参数：

url – QUrl

此信号在加载完成时因为发生错误而发出。

作为参数提供的是加载失败的组件的 url。

QGuiApplication app(argc, argv);
QQmlApplicationEngine engine;

// quit on error
QObject::connect(&engine, QQmlApplicationEngine::objectCreationFailed,
                 QCoreApplication::instance(), QCoreApplication::quit,
                 Qt::QueuedConnection);
engine.load(QUrl());
return app.exec();

注意

如果提供的组件路径是包含相对路径的 QString，则 url 将包含指向文件的完整解析路径。

另请参阅 objectCreated，即使创建失败，也会发出此信号（尽管创建失败）。

rootObjects()

返回类型：

QObject 列表

返回由 QQmlApplicationEngine 实例化的所有根对象列表。这仅包含通过 load() 或便利构造函数加载的对象。 bore only contains objects loaded via load() or a convenience constructor.

注意

在 Qt 5.9 之前的版本中，此函数被标记为非 const。

setExtraFileSelectors(extraFileSelectors)

参数：

extraFileSelectors – 字符串列表

设置要传递给用于解析 URL 到本地文件的内部 QQmlFileSelector 的 extraFileSelectors。在加载第一个 QML 文件时应用这些 extraFileSelectors。设置后无法生效。

另请参阅

QQmlFileSelector setExtraSelectors

setInitialProperties(initialProperties)

参数：

initialProperties – 包含 类型为 QString 的键和 类型为 QVariant 的值的字典。

设置 initialProperties，QML 组件在加载后使用这些属性进行初始化。

QQmlApplicationEngine engine;

EventDatabase eventDatabase;
EventMonitor eventMonitor;

engine.setInitialProperties({
    { "eventDatabase", QVariant::fromValue(&eventDatabase) },
    { "eventMonitor", QVariant::fromValue(&eventMonitor) }
});

另请参阅

setInitialProperties load loadData