class QQmlIncubator#

QQmlIncubator 类允许异步创建 QML 对象。 更多信息...

摘要#

方法#

虚方法#

注意

此文档可能包含自动从C++转换为Python的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE创建工单的方式告诉我们。

详细描述#

创建QML对象（如视图中的委托或应用中的新页面）可能需要明显的时间，尤其是在资源受限的移动设备上。当应用直接使用create()时，QML对象实例的创建是同步的，这可能在对象复杂度较高的情况下导致应用中出现明显的暂停或卡顿。

使用QQmlIncubator可以更细致地控制QML对象的创建，包括允许它在使用应用空闲时间时异步创建。以下示例展示了QQmlIncubator的简单使用。

// Initialize the incubator
QQmlIncubator incubator;
component->create(incubator);

让孵化器运行一段时间（通常是通过将控制权交还给事件循环），然后对其进行轮询。有几种方法可以在之后回到孵化器。您可能想连接到QQuickWindow发出的某个信号，或者您可能想为此特别运行一个QTimer。您也可能需要根据某些特定目的使用对象，并在需要该对象时对孵化器进行轮询。

// Poll the incubator
if (incubator.isReady()) {
    QObject *object = incubator.object();
    // Use created object
}

异步孵化器由一个设置了在QQmlEngine上的QQmlIncubationController来控制，这会让引擎知道应用处于空闲状态并且应该处理孵化对象。如果在QQmlEngine上没有设置孵化控制器，无论指定的IncubationMode如何，QQmlIncubator都会同步创建对象。默认情况下，没有设置孵化控制器。然而，QQuickView、QQuickWindow和QQuickWidget都会在其各自的QQmlEngine上设置孵化控制器。这些孵化控制器在视图渲染时分散在多个帧中进行孵化。

QQmlIncubator支持三种孵化模式

  • 同步：创建是同步发生的。也就是说，一旦create()调用返回，孵化器就已经处于错误或准备好状态。与直接使用QQmlComponent的同步创建方法相比，同步孵化器没有真正的优势，但它可以简化应用程序的实现，使用相同的API来处理同步和异步创建。

  • 异步（默认）：在QQmlEngine上设置QQmlIncubatorController时，创建将异步发生。

    孵化器将保持在加载状态，直到创建完成或发生错误。可以使用statusChanged()回调来通知状态变化。

    应用程序应该使用异步孵化模式来创建不需要立即的对象。例如，当列表滚动时，ListView类型使用异步孵化来创建屏幕外稍远处的对象。如果在异步创建期间需要立即使用对象，则可以调用forceCompletion()方法来同步完成创建过程。

  • AsynchronousIfNested：如果创建是嵌套异步创建的一部分，则将异步创建，否则将同步创建。

    在大多数情况下，当QML组件想要同步实例化的外观时，它应该使用此模式。

    这种模式的最佳解释是通过一个示例。当ListView类型首次创建时，它需要用初始一组委托来填充自己以显示内容。如果ListView高度为400像素，而每个委托高度为100像素，就需要创建四个初始委托实例。如果ListView使用异步孵化模式，ListView总是先创建为空，然后稍后四个初始项目才会出现。

    相反，如果ListView要使用同步孵化模式，则其行为将正确，但可能会在应用程序中引入卡顿。因为QML必须停止并同步实例化ListView的委托，如果ListView是正在异步实例化的QML组件的一部分，这将会抵消异步实例化的大部分好处。

    AsynchronousIfNested模式解决了这个问题。通过使用AsynchronousIfNested，如果ListView本身已经是一个异步实例化的一部分，那么ListView委托将异步实例化，否则将同步实例化。在嵌套异步实例化的情况下，外部异步实例化将不会完成，直到所有嵌套实例化也完成。这确保了外部异步实例化完成时，内部项（如ListView）已经完成了初始委托的加载。

    几乎总是不正确地使用同步孵化模式——想要同步实例化外观，但又不想引起应用程序中的冻结或卡顿的元素或组件应该使用AsynchronousIfNested孵化模式。

class IncubationMode#

指定孵化器运行的模式。无论孵化模式如何，如果QQmlEngine没有设置QQmlIncubationController，则QQmlIncubator将同步操作。

常量

描述

QQmlIncubator.Asynchronous

对象将被异步创建。

QQmlIncubator.AsynchronousIfNested

如果对象正在一个已经包含在异步创建中的上下文中创建，则此孵化器将加入到现有孵化中并异步执行。现有孵化将不会成为Ready状态，直到它和这个孵化都完成。否则，孵化将同步执行。

QQmlIncubator.Synchronous

对象将被同步创建。
class Status#

指定QQmlIncubator的状态。

常量

描述

QQmlIncubator.Null

孵化没有进行中。调用create()开始孵化。

QQmlIncubator.Ready

对象已完全创建，可以通过调用object()进行访问。

QQmlIncubator.Loading

对象正在创建过程中。

QQmlIncubator.Error

发生了错误。可以通过调用errors()来访问错误。
__init__([arg__1=QQmlIncubator.IncubationMode.Asynchronous])#
参数：:

arg__1 – IncubationMode

创建一个新的孵化器，指定mode。

clear()#

清除孵化器。任何正在进行中的孵化都会被中止。如果孵化器处于Ready状态，创建的对象不会被删除。

errors()#
返回类型：:

QQmlError对象的列表

返回孵化对象时遇到的错误列表。

forceCompletion()#

强制任何正在进行的孵化同步完成。一旦这个调用返回，孵化器将不会处于Loading状态。

incubationMode()#
返回类型：:

IncubationMode

返回传递给QQmlIncubator构造函数的孵化模式。

isError()#
返回类型：:

bool

如果孵化器的status()是Error，则返回true。

isLoading()#
返回类型：:

bool

如果孵化器的status()是Loading，则返回true。

isNull()#
返回类型：:

bool

如果孵化器的status()是Null，则返回true。

isReady()#
返回类型：:

bool

如果孵化器的status()是Ready，则返回true。

object()#
返回类型：:

QObject

如果状态为Ready，则返回孵化对象，否则返回0。

setInitialProperties(initialProperties)#
参数：:

initialProperties – 具有类型为 .QString 的键和类型为 QVariant 的值的字典。

存储从属性名称到初始值的映射，包含在 initialProperties 中，用于初始化孵化组件。

另请参阅

setInitialProperties

setInitialState(arg__1)#
参数：:

arg__1 – QObject

在对象首次创建之后、复杂属性绑定评估之前、适用时调用 componentComplete() 。这相当于 beginCreate() 和 completeCreate() 之间的点，并可用来给对象的属性赋初值。

默认实现不做任何事情。

注意

在调用 setInitialState() 之前，简单绑定（如数值字面量）将被评估。将绑定分类为简单和复杂的是有意未指定的，并且可能会在 Qt 的不同版本之间或根据你是否使用 qmlcachegen 而改变。你不应该依赖于任何特定的绑定在调用 setInitialState() 之前或之后被评估。例如，一个常量表达式如 MyType.EnumValue 可能会在编译时被识别为这样的表达式，或者推迟到作为绑定执行。同样适用于常量表达式如 -(5) 或 “a” + “ constant string”。

status()#
返回类型：:

状态

返回孵化器的当前状态。

statusChanged(arg__1)#
参数：:

arg__1 – Status

当孵化器状态改变时被调用。 status 是新的状态。

默认实现不做任何事情。