QQmlComponent 类

成员函数文档

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

创建一个无数据的 QQmlComponent，并赋予它指定的 engine 和 parent。使用 setData() 设置数据。

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

从给定的 fileName 创建 QQmlComponent，并赋予它指定的 parent 和 engine。

另请参阅loadUrl。

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

根据给定的fileName创建QQmlComponent，并赋给它指定的parent和engine。如果mode是异步，该组件将会异步加载和编译。

另请参阅loadUrl。

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

根据给定的url创建QQmlComponent，并赋给它指定的parent和engine。

确保提供的URL是完整且正确的，特别是在从本地文件系统加载文件时，请使用QUrl::fromLocalFile()。

相对路径将与QQmlEngine::baseUrl进行解析，除非指定，否则是当前工作目录。

另请参阅loadUrl。

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

根据给定的url创建QQmlComponent，并赋给它指定的parent和engine。如果mode是异步，该组件将会异步加载和编译。

确保提供的URL是完整且正确的，特别是在从本地文件系统加载文件时，请使用QUrl::fromLocalFile()。

相对路径将与QQmlEngine::baseUrl进行解析，除非指定，否则是当前工作目录。

另请参阅loadUrl。

[显式，自6.5版本开始] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)

从给定的uri和typeName创建QQmlComponent，并给它指定的parent和engine。如果可能，组件将同步加载。

这是一个重载函数。

此函数在Qt 6.5版本中引入。

另请参阅loadFromModule。

[显式，自6.5版本开始] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

从给定的uri和typeName创建QQmlComponent，并给它指定的parent和engine。如果mode是异步，该组件将会异步加载和编译。

这是一个重载函数。

此函数在Qt 6.5版本中引入。

另请参阅loadFromModule。

[重载虚析构函数，异常不抛出] QQmlComponent::~QQmlComponent()

销毁QQmlComponent对象。

[虚拟] QObject *QQmlComponent::beginCreate(QQmlContext *context)

在此组件的指定context中创建一个对象实例。如果创建失败，则返回nullptr。

当QQmlComponent构建一个实例时，它包含三个步骤：

1. 创建对象层次结构，并分配常量值。
2. 首次评估属性绑定。
3. 如果适用，将在对象上调用QQmlParserStatus::componentComplete ()。

QQmlComponent::beginCreate () 与QQmlComponent::create () 不同，因为它只执行步骤 1。必须调用 QQmlComponent::completeCreate () 来完成步骤 2 和 3。

当使用附加属性将信息传递给实例化的组件时，这个断点有时很有用，因为它允许在属性绑定生效之前配置它们的初始值。

返回的对象实例的所有权传递给调用者。

另请参阅：completeCreate () 和 QQmlEngine::ObjectOwnership。

[virtual] void QQmlComponent::completeCreate()

此方法提供了对组件实例创建的高级控制。通常，程序员应使用 QQmlComponent::create () 来创建组件。

此函数完成使用 QQmlComponent::beginCreate () 开始的组件创建，必须在之后调用。

另请参阅：beginCreate ()。

[virtual] QObject *QQmlComponent::create(QQmlContext *context = nullptr)

在此组件的指定context中创建一个对象实例。如果创建失败，则返回nullptr。

如果 context 为 nullptr（默认值），它将在引擎的根上下文中创建实例。

返回的对象实例的所有权传递给调用者。

如果从这个组件创建的对象是一个可视项，它必须有一个可视父项，这可以通过调用QQuickItem::setParentItem () 来设置。有关详细信息，请参阅概念 - Qt Quick 中的可视父项。

另请参阅：QQmlEngine::ObjectOwnership。

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

使用提供的 incubator 从该组件创建一个对象实例。context 指定创建对象实例的上下文。

如果 context 为 nullptr（默认值），它将在引擎的根上下文中创建实例。

forContext 指定一个此对象创建依赖的上下文。如果 forContext 正在异步创建，并且QQmlIncubator::IncubationMode 是QQmlIncubator::AsynchronousIfNested，则此对象也将以异步方式创建。如果 forContext 为 nullptr（默认值），则将使用 context 做出此决定。

创建的对象及其创建状态可通过 incubator 获取。

另请参阅 QQmlIncubator.

QObject *QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

在指定的 context 中创建本组件的对象实例，并用 initialProperties 初始化其顶级属性。

如果任何 initialProperties 无法设置，将发出警告。如果有未设置的必需属性，对象创建将失败并返回 nullptr，在这种情况下，isError() 将返回 true。

另请参阅 QQmlComponent::create.

QQmlContext *QQmlComponent::creationContext() const

返回组件创建时的 QQmlContext。这仅适用于从 QML 直接创建的组件。

QQmlEngine *QQmlComponent::engine() const

返回此组件的 QQmlEngine。

QList<QQmlError> QQmlComponent::errors() const

返回上次编译或创建操作期间发生的错误列表。如果没有设置 isError()，则返回空列表。

[since 6.5] bool QQmlComponent::isBound() const

如果组件是在指定了 pragma ComponentBehavior: Bound 的 QML 文件中创建的，则返回 true，否则返回 false。

此函数在Qt 6.5版本中引入。

bool QQmlComponent::isError() const

如果 status() == QQmlComponent::Error。

bool QQmlComponent::isLoading() const

如果 status() == QQmlComponent::Loading。

bool QQmlComponent::isNull() const

如果 status() == QQmlComponent::Null。

bool QQmlComponent::isReady() const

如果 status() == QQmlComponent::Ready。

[slot, since 6.5] void QQmlComponent::loadFromModule(QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode = PreferSynchronous)

在模块 uri 中加载 typeName 的 QQmlComponent。如果通过 QML 文件实现该类型，则使用 mode 来加载它。支持 C++ 的类型始终同步加载。

QQmlEngine engine;
QQmlComponent component(&engine);
component.loadFromModule("QtQuick", "Item");
// once the component is ready
std::unique_ptr<QObject> item(component.create());
Q_ASSERT(item->metaObject() == &QQuickItem::staticMetaObject);

此函数在Qt 6.5版本中引入。

另请参阅loadUrl。

[slot] void QQmlComponent::loadUrl(const QUrl &url)

从提供的url加载QQmlComponent。

确保提供的URL是完整且正确的，特别是在从本地文件系统加载文件时，请使用QUrl::fromLocalFile()。

相对路径将与QQmlEngine::baseUrl进行解析，除非指定，否则是当前工作目录。

[slot] void QQmlComponent::loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)

从提供的url加载QQmlComponent。如果mode是异步，组件将异步加载和编译。

确保提供的URL是完整且正确的，特别是在从本地文件系统加载文件时，请使用QUrl::fromLocalFile()。

相对路径将与QQmlEngine::baseUrl进行解析，除非指定，否则是当前工作目录。

[signal] void QQmlComponent::progressChanged(qreal progress)

每当组件的加载进度变化时都会发出。当前的进度值将在 0.0（没有加载）和 1.0（完成）之间。

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &url)

设置QQmlComponent以使用给定的QML数据。如果提供了url，它将用于设置组件名称并为该组件解析的项目提供一个基本路径。

void QQmlComponent::setInitialProperties(QObject *component, const QVariantMap &properties)

设置组件的顶级属性。

此方法提供对组件实例创建的高级控制。通常，程序员应使用 QQmlComponent::createWithInitialProperties 来创建组件。

在调用beginCreate之后和调用completeCreate之前使用此方法。如果提供的属性不存在，将发出警告。

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

每当组件的状态变化时都会发出。当前的状态将是最新的状态。