QML类型：Component（组件）

一、描述

组件是可重用、封装的 QML 类型，具有明确定义的接口。

组件通常由组件文件定义 - 即 .qml 文件，一个.qml文件就是一个组件。而 Component 类型本质上允许在 QML 文档中内联定义 QML 组件，而不是作为单独的 QML 文件。

例如，下面是一个被多个 Loader 对象使用的组件：

import QtQuick 2.0

Item 
{
    width: 100; height: 100

    Component 
    {
        id: redSquare

        Rectangle
        {
            color: "red"
            width: 10
            height: 10
        }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 20 }
}

虽然 Rectangle 本身会自动呈现和显示，但上面矩形并非如此，因为它是在 Component 内定义的。该组件将 QML 类型封装在其中，就好像它们是在单独的 QML 文件中定义的一样，并且在请求之前不会加载。由于 Component 不是从 Item 派生的，因此无法将任何内容锚定到它。

定义组件类似于定义 QML 文档。QML 文档有一个定义该组件的行为和属性的顶级项目，并且不能定义该顶级项目之外的属性或行为。同样，组件定义包含单个顶级项目（在上面的示例中是一个 Rectangle）并且不能定义除了 id 和该项目之外的任何数据。

Component 类型通常用于为视图提供图形组件。例如，ListView::delegate 属性需要一个组件来指定每个列表项的显示方式。

组件对象也可以使用 Qt.createComponent() 动态创建。

组件示例：

MyItem.qml	

Item
{
    property Component mycomponent: comp1

    QtObject 
    {
        id: internalSettings
        property color color: "green"
    }

    Component
    {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

//main.qml

ListView 
{
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //将创建绿色 Rectangles

    MyItem { id: myItem }
}

二、属性成员

1、progress : real

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

2、status : enumeration

此属性保存组件加载的状态。

• Component.Null：没有可用的组件数据
• Component.Ready：组件已加载，可用于创建实例。
• Component.Loading：当前正在加载组件
• Component.Error：加载组件时发生错误。errorString() 将提供错误的描述。

3、url : url

用于构造组件的 URL。

三、信号成员

1、completed()

在对象被实例化后发出。这可用于在启动时执行脚本代码。

Rectangle 
{
    Component.onCompleted: console.log("Completed Running!")
    Rectangle 
    {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

2、destruction()

当对象开始销毁时发出。

Rectangle
{
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle 
    {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

四、成员函数

1、object createObject(QtObject parent, object properties)

创建并返回此组件的对象实例，该对象实例将具有给定的父级和属性。属性参数是可选的。如果对象创建失败，则返回 null。

如果您希望在不设置父级的情况下创建对象，请将父级值指定为 null。请注意，如果要显示返回的对象，则必须提供有效的父值或设置返回对象的父属性，否则该对象将不可见。

如果没有为 createObject() 提供父对象，则必须保留对返回对象的引用，以便垃圾收集器不会销毁它。无论 Item::parent 之后是否设置，都是如此，因为设置 Item::parent 不会更改对象所有权。仅更改图形父级。

可选properties 参数为创建的对象指定初始属性值的映射。这些值在对象创建完成之前应用。这比在创建对象后设置属性值更有效，尤其是在定义了大量属性值的情况下，并且还允许在创建对象之前设置属性绑定（使用 Qt.binding）。

下面的代码创建了一个初始 x 和 y 值分别为 100 和 100 的对象：

var component = Qt.createComponent("Button.qml");
if (component.status == Component.Ready)
    component.createObject(parent, {x: 100, y: 100});

可以使用 destroy() 方法删除动态创建的实例。

2、string errorString()

返回错误的描述。

该字符串包括每个错误的文件、位置和描述。如果存在多个错误，它们由换行符分隔。

3、object incubateObject(Item parent, object properties, enumeration mode)

创建该组件对象的“孵化器”，该“孵化器”用来生成组件对象。允许异步创建，并且不会导致 UI 冻结。如果创建不成功则返回 null。

所有三个参数都是可选的。

• parent 参数指定创建的实例将具有的父级。省略参数或传递 null 将创建一个没有父对象的对象。在这种情况下，必须持有对所创建对象的引用，以便垃圾收集器不会销毁它。
• properties 参数被指定为一个属性值项目的映射，这些项目将在其构造期间在创建的对象上设置。
• mode 可以是 Qt.Synchronous 或 Qt.Asynchronous，控制实例是同步创建还是异步创建。默认是异步的。在某些情况下，即使指定了 Qt.Synchronous，孵化器也可能会异步创建对象。比如调用 incubateObject() 的组件本身是异步创建的，就会发生这种情况。

创建的对象具有以下特性：

status：“孵化器”的状态。有效值为：

• Component.Ready
• Component.Loading
• Component.Error

object：创建的对象实例。只有当“孵化器”处于就绪状态时才可用。

onStatusChanged：指定状态改变时调用的回调函数。状态作为参数传递给回调。

forceCompletion()：调用同步完成孵化。

以下示例演示了如何使用孵化器：

var component = Qt.createComponent("Button.qml");

var incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status != Component.Ready) 
{
    incubator.onStatusChanged = function(status) 
    {
        if (status == Component.Ready)
        {
            print ("Object", incubator.object, "is now ready!");
        }
    }
} 
else 
{
    print ("Object", incubator.object, "is ready immediately!");
}

可以使用 destroy() 方法删除动态创建的实例。