PySide6.QtQml.QQmlComponent¶

class QQmlComponent¶

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

概要¶

注意

本文档可能包含从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 status。应用程序必须等待组件变为Ready后才能调用create()。

以下示例展示了如何从网络资源加载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

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

常量	描述
QQmlComponent.PreferSynchronous	优先立即加载/编译组件，阻塞线程。这并不总是可能的；例如，远程URL将始终异步加载。
QQmlComponent.Asynchronous	在后台线程中加载/编译组件。

class Status¶

指定QQmlComponent的加载状态。

常量

描述

QQmlComponent.Null

这个 QQmlComponent 没有数据。调用 loadUrl() 或 setData() 来添加 QML 内容。

QQmlComponent.Ready

这个 QQmlComponent 已经准备好，可以调用 create()。

QQmlComponent.Loading

这个 QQmlComponent 正在加载网络数据。

QQmlComponent.Error

发生了一个错误。调用 errors() 来检索 errors 的列表。

常量	描述
QQmlComponent.Null	这个 `QQmlComponent` 没有数据。调用 `loadUrl()` 或 `setData()` 来添加 QML 内容。
QQmlComponent.Ready	这个 `QQmlComponent` 已经准备好，可以调用 `create()`。
QQmlComponent.Loading	这个 `QQmlComponent` 正在加载网络数据。
QQmlComponent.Error	发生了一个错误。调用 `errors()` 来检索 `errors` 的列表。

注意

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

property progressᅟ: float¶

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

Access functions:

progress()
信号 progressChanged()

property statusᅟ: QQmlComponent.Status¶

组件的当前status。

Access functions:

status()
信号 statusChanged()

property urlᅟ: QUrl¶

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

Access functions:

url()

__init__([parent=None])¶

Parameters:: 父对象 – QObject

__init__(engine[, parent=None])

Parameters:

engine – QQmlEngine
parent – QObject

创建一个没有数据的QQmlComponent，并为其指定engine和parent。使用setData()设置数据。

__init__(engine, fileName[, parent=None])

Parameters:

engine – QQmlEngine
fileName – str
parent – QObject

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

另请参阅

loadUrl()

__init__(engine, url[, parent=None])

Parameters:

engine – QQmlEngine
url – QUrl
parent – QObject

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

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

相对路径将根据baseUrl()解析，除非另有指定，否则当前工作目录为基准。

另请参阅

loadUrl()

__init__(engine, fileName, mode[, parent=None])

Parameters:

engine – QQmlEngine
fileName – str
mode – CompilationMode
parent – QObject

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

另请参阅

loadUrl()

__init__(engine, url, mode[, parent=None])

Parameters:

engine – QQmlEngine
url – QUrl
mode – CompilationMode
parent – QObject

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

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

相对路径将根据baseUrl()解析，除非另有指定，否则当前工作目录为基准。

另请参阅

loadUrl()

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

Parameters:

engine – QQmlEngine
uri – 字符串
typeName – str
parent – QObject

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

这是一个重载函数。

另请参阅

loadFromModule()

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

Parameters:

engine – QQmlEngine
uri – str
typeName – str
mode – CompilationMode
parent – QObject

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

这是一个重载函数。

另请参阅

loadFromModule()

beginCreate(context)¶

Parameters:: 上下文 – QQmlContext
Return type:: QObject

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

注意

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

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

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

属性绑定首次被评估。

如果适用，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])¶

Parameters:: 上下文 – QQmlContext
Return type:: QObject

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

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

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

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

另请参阅

ObjectOwnership

create(incubator[, context=None[, forContext=None]])

Parameters:

孵化器 – QQmlIncubator
context – QQmlContext
forContext – QQmlContext

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

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

forContext 指定了此对象创建所依赖的上下文。如果 forContext 是异步创建的，并且 IncubationMode 是 AsynchronousIfNested，则此对象也将异步创建。如果 forContext 是 None（默认情况下），则将使用 context 来做出此决定。

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

另请参阅

QQmlIncubator

createObject([parent=None[, properties={}]])¶

Parameters:

parent – QObject
properties – 字典，键类型为 .QString，值类型为 QVariant。

Return type:

QObject

createWithInitialProperties(initialProperties[, context=None])¶

Parameters:

initialProperties – 字典，键类型为 .QString，值类型为 QVariant。
context – QQmlContext

Return type:

QObject

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

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

另请参阅

create

creationContext()¶

Return type:: QQmlContext

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

engine()¶

Return type:: QQmlEngine

返回此组件的QQmlEngine。

errorString()¶

Return type:: 字符串

errors()¶

Return type:: QQmlError的列表

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

isBound()¶

Return type:: 布尔

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

isError()¶

Return type:: 布尔

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

isLoading()¶

Return type:: 布尔

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

isNull()¶

Return type:: 布尔

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

isReady()¶

Return type:: 布尔

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

loadFromModule(uri, typeName[, mode=QQmlComponent.CompilationMode.PreferSynchronous])¶

Parameters:

uri – 字符串
typeName – str
mode – CompilationMode

加载模块 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)¶

Parameters:: url – QUrl

从提供的url加载QQmlComponent。

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

相对路径将根据baseUrl()解析，除非另有指定，否则当前工作目录为基准。

loadUrl(url, mode)

Parameters:

url – QUrl
mode – CompilationMode

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

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

相对路径将根据baseUrl()解析，除非另有指定，否则当前工作目录为基准。

progress()¶

Return type:: 浮点数

属性 progressᅟ 的获取器。

progressChanged(progress)¶

Parameters:: progress – 浮点数

每当组件的加载进度发生变化时触发。progress 将是当前进度，范围在 0.0（未加载）到 1.0（完成）之间。

属性 progressᅟ 的通知信号。

setData(data, baseUrl)¶

Parameters:

data – QByteArray
baseUrl – QUrl

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

setInitialProperties(component, properties)¶

Parameters:

组件 – QObject
properties – 字典，键类型为 .QString，值类型为 QVariant。

设置从QQmlComponent创建的object的顶级properties。

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

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

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

例如，为了设置fond.bold，你可以创建一个QFont，将其重量设置为粗体，然后将字体作为初始属性传递。

status()¶

Return type:: 状态

属性 statusᅟ 的获取器。

statusChanged(status)¶

Parameters:: 状态 – Status

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

属性 statusᅟ 的通知信号。

url()¶

Return type:: QUrl

属性 urlᅟ 的获取器。

PySide6.QtQml.QQmlComponent¶

概要¶

属性¶

方法¶

虚拟方法¶

插槽¶

信号¶

详细描述¶

网络组件¶