class QQmlComponent#

QQmlComponent 类封装了一个 QML 组件定义。 更多...

Inheritance diagram of PySide6.QtQml.QQmlComponent

摘要#

属性#

方法#

虚方法#

槽#

信号#

注意

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

详细描述#

组件是具有良好定义的接口的复用、封装的qml类型。

可以使用一个QML文件来创建一个 QQmlComponent 实例。例如，如果有一个如下所示的 main.qml 文件

以下代码将该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 子类中创建

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 ，因为实例尚不具备上下文和引擎。

网络组件#

如果传递给 QQmlComponent 的URL是网络资源，或者如果 QML 文档引用了网络资源，QQmlComponent 在能够创建对象之前必须获取网络数据。在这种情况下，QQmlComponent 将有一个 Loading 状态。在调用 create() 之前，应用程序必须等待组件处于 Ready 状态。

以下示例展示了如何从网络资源中加载一个QML文件。创建完QQmlComponent后，它测试组件是否正在加载。如果是，则连接到statusChanged()信号，否则直接调用continueLoading()方法。请注意，对于已缓存且立即准备好的网络组件，isLoading()可能为false。

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

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

指定QQmlComponent 是立即加载组件，还是异步加载。

常量

描述

QQmlComponent.PreferSynchronous

优先立即加载/编译组件，阻塞线程。这并不总是可能的；例如，远程URL将始终异步加载。

QQmlComponent.Asynchronous

在后台线程中加载/编译组件。
class Status#

指定QQmlComponent 的加载状态。

常量

描述

QQmlComponent.Null

此QQmlComponent 没有数据。调用loadUrl()或setData()以添加QML内容。

QQmlComponent.Ready

此QQmlComponent已准备就绪，可调用create()。

QQmlComponent.Loading

此QQmlComponent正在加载网络数据。

QQmlComponent.Error

已发生错误。调用errors()以检索错误列表。

注意

当使用from __feature__ import true_property时，可以直接使用属性，否则通过访问函数。

属性 progress: float#

组件加载的进度，从 0.0（未加载任何内容）到 1.0（完成）。

访问函数
属性 status: QQmlComponent.Status#

组件当前的 状态 .

访问函数
属性 url: QUrl#

组件的 URL。这是传递给构造函数、loadUrl() 或 setData() 方法的 URL。

访问函数
__init__(arg__1[，parent=None])#
参数:

使用指定的 engine 和 parent 创建一个空的 QQmlComponent，并通过 setData() 设置数据。

__init__([parent=None])
参数:

parent – QObject

__init__(engine，uri，typeName，mode[，parent=None])
参数:

从给定的 uri 和 typeName 创建一个 QQmlComponent，并将其指定的 parent 和 engine 传递给它。如果 mode 是 Asynchronous，则组件将以异步方式加载和编译。

这是一个重载函数。

另请参阅

loadFromModule()

__init__(engine, uri, typeName[, parent=None])
参数:

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

这是一个重载函数。

另请参阅

loadFromModule()

__init__(arg__1, url, mode[, parent=None])
参数:

从给定的 url 创建一个 QQmlComponent，并将其指定的 parent 和 engine 传递给它。如果 mode 是 Asynchronous，则组件将以异步方式加载和编译。

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

相对路径将相对于 baseUrl() 解析，除非指定，否则为当前工作目录。

另请参阅

loadUrl()

__init__(arg__1, url[, parent=None])
参数:

从给定的 url 创建一个 QQmlComponent，并给它指定的 parent 和 engine。

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

相对路径将相对于 baseUrl() 解析，除非指定，否则为当前工作目录。

另请参阅

loadUrl()

__init__(arg__1, fileName, mode[, parent=None])
参数:

从给定的 fileName 创建一个 QQmlComponent，并给它指定的 parent 和 engine。如果 mode 是 Asynchronous，组件将异步加载和编译。

另请参阅

loadUrl()

__init__(arg__1, fileName[, parent=None])
参数:

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

另请参阅

loadUrl()

beginCreate(arg__1)#
参数:

arg__1 – QQmlContext

返回类型：:

QObject

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

注意

此方法提供了对组件实例创建的先进控制。通常，程序员应使用 create() 创建对象实例。

当 QQmlComponent 构造实例时，它分为三个步骤：

  1. 创建对象层次结构，并分配常量值。

  2. 第一次评估属性绑定。

  3. 在对象上适用时，调用 componentComplete()。

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

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

返回的对象实例的所有权转移到调用者。

注意

将绑定分类为常量值和实际绑定是有意未指定的，这可能在 Qt 的不同版本以及是否以及如何使用 qmlcachegen 之间发生变化。您不应依赖于任何特定的绑定在 beginCreate() 返回之前或之后进行评估。例如，像 MyType.EnumValue 这样的常量表达式可能在编译时识别为常量表达式，或者延迟到作为绑定执行。这对于像 -(5) 或 “a” + “constant string” 这样的常量表达式也适用。

另请参阅

completeCreate() ObjectOwnership

completeCreate()#

此方法为组件实例的创建提供了高级控制。一般来说，程序员应使用 create() 创建一个组件。

此函数完成了用 beginCreate() 开始的组件创建，并且之后必须调用它。

另请参阅

beginCreate()

create([context=None])#
参数:

context – QQmlContext

返回类型：:

QObject

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

如果 context 是 None（默认值），它将在引擎的 root context 中创建实例。

返回的对象实例的所有权转移到调用者。

如果从该组件创建的对象是视觉项，则它必须有一个视觉父项，可以通过调用 QQuickItem::setParentItem() 来设置。有关更多详情，请参阅 Qt Quick 的概念部分 - 视觉父项。

另请参阅

对象所有权

create(arg__1[, context=None[, forContext=None]])
参数:

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

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

forContext 指定了此对象创建所依赖的上下文。如果 forContext 正在异步创建，并且 IncubationMode 是 AsynchronousIfNested ，则此对象也将异步创建。如果 forContext 是 None（默认值），则 context 将用于此决策。

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

另请参阅

QQmlIncubator

createObject([parent=None[, properties={}]])#
参数:

  • parent – QObject

  • properties – 键为 QString 类型，值为 QVariant 类型的字典。

返回类型：:

QObject

createWithInitialProperties(initialProperties[, context=None])#
参数:

  • initialProperties – 键为 QString 类型，值为 QVariant 类型的字典。

  • context – QQmlContext

返回类型：:

QObject

在指定的 context 中创建此组件的对象实例，并以 initialProperties 初始化其最高级属性。

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

另请参阅

create

creationContext()#
返回类型：:

QQmlContext

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

engine()#
返回类型：:

QQmlEngine

返回此组件的QQmlEngine。

errorString(）#
返回类型：:

字符串

errors(）#
返回类型：:

QQmlError列表

返回在上次编译或创建操作中发生的错误列表。如果没有错误，将返回空列表。

isBound(）#
返回类型：:

布尔值

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

isError(）#
返回类型：:

布尔值

如果status()等于Error，则返回true。

isLoading(）#
返回类型：:

布尔值

如果status()等于Loading，则返回true。

isNull(）#
返回类型：:

布尔值

如果status()等于Null，则返回true。

isReady(）#
返回类型：:

布尔值

如果status()等于Ready，则返回true。

loadFromModule(uri, typeName[，mode=QQmlComponent.CompilationMode.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);

另请参阅

loadUrl()

loadUrl(url)#
参数:

url – QUrl

从提供的 url 加载 QQmlComponent。

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

相对路径将相对于 baseUrl() 解析，除非指定，否则为当前工作目录。

loadUrl(url, mode)
参数:

从提供的 url 加载 QQmlComponent。如果 mode 设置为 Asynchronous ，则组件异步加载和编译。

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

相对路径将相对于 baseUrl() 解析，除非指定，否则为当前工作目录。

progress()#
返回类型：:

float

获取属性 progress 的值。

progressChanged(arg__1)#
参数:

arg__1 – float

每当组件的加载进度发生变化时都会触发。属性值 progress 将是当前进度，介于 0.0（未加载任何内容）和 1.0（完成）之间。

属性 progress 的通知信号。

setData(arg__1, baseUrl)#
参数:

设置 QQmlComponent 以使用给定的 QML data。如果提供了 url，则用于设置组件名称，并为通过此组件解析的项目提供基本路径。

setInitialProperties(component, properties)#
参数:

  • component – QObject

  • properties – 键为 QString 类型，值为 QVariant 类型的字典。

设置 component 的顶层属性。

此方法提供了对组件实例创建的高级控制。一般情况下，程序员应该使用 createWithInitialProperties 方法来创建组件。

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

status()#
返回类型：:

属性状态

status 的获取器。

statusChanged(arg__1)#
参数:

arg__1 – Status

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

status 属性的通知信号。

url()#
返回类型：:

QUrl

url 的获取器。