QML QQmlComponent

QQmlComponent

• 官方文档：https://doc.qt.io/qt-5/qqmlcomponent.html
• QmlComponent类封装了一个QML component 定义

Header:	#include <QQmlComponent>
qmake:	QT += qml
Since:	Qt 5.0
Instantiated By:	Component
Inherits:	QObject

Public Types

enum	CompilationMode { PreferSynchronous, Asynchronous }
enum	Status { Null, Ready, Loading, Error }

属性

• progress : const qreal
• status : const Status
• url : const QUrl

Public Slots

void	loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)
void	loadUrl(const QUrl &url)
void	setData(const QByteArray &data, const QUrl &url)

Signals

void	progressChanged(qreal progress)
void	statusChanged(QQmlComponent::Status status)

• 组件是可重用的、封装的、具有良好定义的接口的QML类型。
• QQmlComponent实例可以从QML文件创建。例如，如果有一个main.qml文件如下:

import QtQuick 2.0

Item {
    width: 200
    height: 200
}

• 以下代码将这个QML文件作为组件加载，使用create()创建该组件的实例，然后查询Item的宽度值:

QQmlEngine *engine = new QQmlEngine;
QQmlComponent component(engine, QUrl::fromLocalFile("main.qml"));

QObject *myObject = component.create();
QQuickItem *item = qobject_cast<QQuickItem*>(myObject);
int width = item->width();  // width = 200

• 要在没有QQmlEngine实例的代码中创建组件实例，可以使用qmlContext() 或 qmlEngine().。例如，在下面的场景中，在QQuickItem子类中创建子项目:
• 例如，在下面的场景中，在QQuickItem子类中创建子项目:

void MyCppItem::init()
{
    QQmlEngine *engine = qmlEngine(this);
    // Or:
    // QQmlEngine *engine = qmlContext(this)->engine();
    QQmlComponent component(engine, QUrl::fromLocalFile("MyItem.qml"));
    QQuickItem *childItem = qobject_cast<QQuickItem*>(component.create());
    childItem->setParentItem(this);
}

• 注意，当在QObject子类的构造函数内部调用时，这些函数将返回null，因为实例还没有上下文或引擎。

网络部件（Network Components）

• 如果传递给QQmlComponent的URL是一个网络资源，或者如果QML文档引用了一个网络资源，QQmlComponent必须在能够创建对象之前获取网络数据。
• 在这种情况下，QQmlComponent将具有加载状态。应用程序必须等到组件就绪后才能调用QQmlComponent::create()。
• 下面的示例展示了如何从网络资源加载QML文件。
  • 创建QQmlComponent后，它将测试该组件是否正在加载。
  • 如果是，它将连接到 QQmlComponent::statusChanged() 信号，否则直接调用continueLoading()方法。
  • 注意，如果网络组件已经被缓存并立即准备就绪，那么QQmlComponent::isLoading()可能为false。

MyApplication::MyApplication()
{
    // ...
    component = new QQmlComponent(engine, QUrl("http://www.example.com/main.qml"));
    if (component->isLoading())
        QObject::connect(component, SIGNAL(statusChanged(QQmlComponent::Status)),
                         this, SLOT(continueLoading()));
    else
        continueLoading();
}

void MyApplication::continueLoading()
{
    if (component->isError()) {
        qWarning() << component->errors();
    } else {
        QObject *myObject = component->create();
    }
}

成员类型

enum QQmlComponent::CompilationMode

• 指定 QQmlComponent 应该立即加载组件还是异步加载组件。

Constant	Value	Description
QQmlComponent::PreferSynchronous	0	最好立即加载/编译组件，阻塞线程。这并不总是可能的;例如，远程url总是异步加载
QQmlComponent::Asynchronous	1	在后台线程中加载/编译组件

enum QQmlComponent::Status

• QQmlComponent的加载状态。

Constant	Value	Description
QQmlComponent::Null	0	这个QQmlComponent没有数据。调用 loadUrl() 或setData() 来添加QML内容。
QQmlComponent::Ready	1	QQmlComponent已经准备好了，可以调用create() 了。
QQmlComponent::Loading	2	这个QQmlComponent正在加载网络数据。
QQmlComponent::Error	3	发生错误。调用 errors() 来检索errors列表。

属性

progress : const qreal

• 加载组件的进度，从0.0(未加载)到1.0(完成)。
• Access functions:   qreal  progress() const
• Notifier signal:        void   progressChanged(qreal progress)

 

status : const Status

• 组件的当前状态。
• Access functions:      QQmlComponent:: Status    status() const
• Notifier signal:           void    statusChanged(QQmlComponent::Status status)

 

url : const QUrl

• 组件的URL。这是传递给构造函数、 loadUrl(), 或 setData() 方法的URL。
• Access functions:    QUrl url() const

成员函数

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

• 从给定的url创建一个QQmlComponent，并给它指定的父组件和引擎。如果mode为 Asynchronous,，则组件将异步加载和编译。
• 确保提供的URL是完整的和正确的，特别是，当从本地文件系统加载文件时，使用QUrl::fromLocalFile() 。
• 相对路径将根据 QQmlEngine::baseUrl()解析，除非指定，它是当前工作目录。
• 参考： loadUrl().

 

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

• 从给定的url创建一个QQmlComponent，并给它指定的父组件和引擎。
• 确保提供的URL是完整的和正确的，特别是，当从本地文件系统加载文件时，使用QUrl::fromLocalFile()。
• 相对路径将根据QQmlEngine::baseUrl()解析，除非指定，它是当前工作目录。

 

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

• 根据给定的fileName创建一个QQmlComponent，并给它指定的父组件和引擎。如果mode为Asynchronous，则组件将异步加载和编译。

 

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

• 根据给定的fileName创建一个QQmlComponent，并给它指定的父组件和引擎。

 

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

• 创建一个没有数据的QQmlComponent，并给它指定引擎和父组件。使用setData()设置数据。

 

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

• 从提供的url加载QQmlComponent。如果mode为Asynchronous，则组件将异步加载和编译。
• 确保提供的URL是完整的和正确的，特别是，当从本地文件系统加载文件时，使用QUrl::fromLocalFile()。
• 相对路径将根据QQmlEngine::baseUrl()解析，除非指定，它是当前工作目录。

 

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

• 从提供的url加载QQmlComponent。
• 确保提供的URL是完整的和正确的，特别是，当从本地文件系统加载文件时，使用QUrl::fromLocalFile()。
• 相对路径将根据QQmlEngine::baseUrl()解析，除非指定，它是当前工作目录。

 

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

• 每当组件的加载进度发生变化时触发。进度将是0.0(未加载)和1.0(已完成)之间的当前进度。
• 注意:属性进度的通知信号  progress.

 

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

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

 

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

• 每当组件的状态改变时触发。状态将是新的状态。
• 注意:属性状态的通知信号status.

 

[override virtual] QQmlComponent::~QQmlComponent()

• QQmlComponent销毁

 

[virtual] QObject *QQmlComponent::beginCreate(QQmlContext *publicContext)

• 该方法提供了对组件实例创建的高级控制。一般来说，程序员应该使用QQmlComponent::create() 来创建对象实例。
• 从这个组件创建一个对象实例。如果创建失败，返回nullptr。publicContext指定创建对象实例的上下文。
• 当QQmlComponent构造一个实例时，它发生在三个步骤中:
  • 创建对象层次结构，并分配常量值。
  • 第一次评估属性绑定。
  • 如果适用，对对象调用QQmlParserStatus::componentComplete() 。
• QQmlComponent::beginCreate()不同于QQmlComponent::create()，它只执行第1步。必须调用QQmlComponent::completeCreate() 来完成步骤2和3。
• 当使用附加的属性向实例化的组件传递信息时，这个断点有时很有用，因为它允许在属性绑定生效之前配置它们的初始值。
• 返回对象实例的所有权转移给调用者。
• 当使用附加的属性向实例化的组件传递信息时，这个断点有时很有用，因为它允许在属性绑定生效之前配置它们的初始值。
• 返回对象实例的所有权转移给调用者。
• 参考： completeCreate() and QQmlEngine::ObjectOwnership.

 

[virtual]void QQmlComponent::completeCreate()

• 该方法提供了对组件实例创建的高级控制。通常，程序员应该使用QQmlComponent::create() 来创建组件。
• QQmlComponent::beginCreate() 开始的组件创建，之后必须被调用。
• 参考： beginCreate().

 

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

• 从这个组件创建一个对象实例。如果创建失败，返回nullptr。Context指定在其中创建对象实例的上下文。
• 如果context是nullptr(默认值)，它将在引擎的根上下文中创建实例。
• 返回对象实例的所有权转移给调用者。
• 如果从这个组件创建的对象是一个可视项目，那么它必须有一个可视父对象，可以通过调用QQuickItem::setParentItem().来设置。更多细节请参见概念- Qt Quick中的可视父类。
• 参考：QQmlEngine::ObjectOwnership.

 

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

• 使用提供的孵化器从该组件创建一个对象实例。Context指定在其中创建对象实例的上下文。
• 如果context为0(默认值)，它将在引擎的根上下文中创建实例。
• forContext指定对象创建所依赖的上下文。如果forContext是异步创建的，并且QQmlIncubator::孵化器模式是QQmlIncubator:: asynchronousif嵌套的，该对象也将被异步创建。如果forContext为0(默认值)，该上下文将用于此决策。
• 创建的对象和它

 

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

• 创建该组件的对象实例，并使用initialProperties初始化其顶层属性。Context指定要创建对象实例的上下文。
• 如果任何一个initialProperties不能被设置， isError() 将返回true，而 errors()函数可以用来获得关于错误的详细信息。
• 该函数是在Qt 5.14中引入的。

 

QQmlContext *QQmlComponent::creationContext() const

• 返回创建组件的 QQmlContext。这只对直接从QML创建的组件有效。

 

QQmlEngine *QQmlComponent::engine() const

• 返回该组件的QQmlEngine。
• 该函数是在Qt 5.12中引入的。

 

QList<QQmlError> QQmlComponent::errors() const

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

 

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。

 

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

• 设置组件的顶级属性。
• 该方法提供了对组件实例创建的高级控制。通常，程序员应该使用QQmlComponent::createWithInitialProperties来创建组件。
• 在 beginCreate之后和completeCreate之前使用此方法。如果提供的属性不存在，则会发出警告。
• 该函数是在Qt 5.14中引入的。