QQmlComponent Class

成员函数文档

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 QUrl &url, QObject *parent = nullptr)

根据给定的url 创建一个QQmlComponent，并为其指定parent 和engine 。

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

相对路径将相对于QQmlEngine::baseUrl() 进行解析，除非另有指定，否则该路径即为当前工作目录。

另请参阅 loadUrl()。

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

根据给定的fileName 创建一个QQmlComponent，并为其指定parent 和engine 。如果mode 为Asynchronous ，则该组件将异步加载和编译。

另请参阅 loadUrl()。

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

根据给定的url 创建一个QQmlComponent，并为其指定parent 和engine 。如果mode 为Asynchronous ，则该组件将以异步方式加载和编译。

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

相对路径将根据QQmlEngine::baseUrl() 进行解析，除非另有指定，否则该函数默认指向当前工作目录。

另请参阅 loadUrl()。

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)

根据给定的uri 和typeName 创建一个QQmlComponent，并为其指定parent 和engine 。如果可能，该组件将以同步方式加载。

该函数在 Qt 6.5 中引入。

另请参阅 loadFromModule()。

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

根据给定的uri 和typeName 创建一个QQmlComponent，并为其指定parent 和engine 。如果mode 为Asynchronous ，则该组件将异步加载和编译。

该函数在 Qt 6.5 中引入。

另请参阅 loadFromModule()。

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

摧毁QQmlComponent 。

[virtual] 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 （默认值），则将在引擎的root context 中创建该实例。

返回的对象实例的所有权将转移给调用方。

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

另请参阅 QQmlEngine::ObjectOwnership 。

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

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

如果context 为nullptr （默认值），则将在引擎的root context 中创建该实例。

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 。

如果context 为nullptr （默认值），则会在引擎的root context 中创建该实例。

返回的对象实例的所有权将转移给调用方。

另请参阅 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`，则返回 true。

bool QQmlComponent::isLoading() const

如果 `status()` == `QQmlComponent::Loading`，则返回 true。

bool QQmlComponent::isNull() const

如果 `status()` == `QQmlComponent::Null`，则返回 true。

bool QQmlComponent::isReady() const

如果 `status()` == `QQmlComponent::Ready`，则返回 true。

[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() 进行解析，除非另有指定，否则该路径即为当前工作目录。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url) { receiver->loadUrl(url); });

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

从提供的url 加载QQmlComponent 。如果mode 的值为Asynchronous ，则该组件将异步加载并编译。

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

相对路径将根据QQmlEngine::baseUrl() 进行解析，除非另有指定，否则该路径即为当前工作目录。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url, QQmlComponent::CompilationMode mode) { receiver->loadUrl(url, mode); });

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

每当组件的加载进度发生变化时触发。progress 表示当前进度，取值范围为 0.0（尚未加载）到 1.0（已完成）。

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

将QQmlComponent 设置为使用给定的QML文件data 。如果提供了url ，则将其用于设置组件名称，并为该组件解析的项目提供基路径。该组件将以同步方式加载和编译。

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

设置由QQmlComponent 生成的object 的顶级properties 。

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

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

此方法不允许直接设置初始嵌套属性。相反，要为具有嵌套属性的值类型属性设置初始值，可以通过创建该值类型、为其嵌套属性赋值，然后将该值类型作为要构建的对象的初始属性传递来实现。

例如，要设置 `fond.bold`，可以创建一个 `QFont`，将其 `weight` 属性设置为 `bold`，然后将该字体作为初始属性传递。

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

每当组件的状态发生变化时触发。status 将表示新的状态。