Component QML Type

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

• 所有成员的列表，包括继承的成员

属性

• progress : real
• status : enumeration
• url : url

附加信号

• completed()
• destruction()

方法

• QtObject createObject(QtObject parent, var properties)
• string errorString()
• var incubateObject(QtObject parent, var properties, enumeration mode)

详细说明

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

组件通常通过组件文件（即.qml 文件）进行定义。Component类型本质上允许在QML 文档内直接定义 QML 组件，而非将其作为单独的 QML 文件。这对于在 QML 文件中复用小型组件，或者定义一个在逻辑上属于该文件内其他 QML 组件的组件而言，可能会非常有用。

例如，下面是一个被多个Loader 对象使用的组件。它包含一个Rectangle ：

import QtQuick

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文件中定义的一样，并且只有在被请求时（在本例中，由两个Loader 对象请求）才会被加载。 由于 Component 并非从 Item 派生而来，因此无法将其作为锚点。

定义Component 与定义QML文档类似。一个QML文档包含一个顶级项，该项定义了该组件的行为和属性，且无法在该顶级项之外定义属性或行为。 同样，Component 的定义包含一个顶级项（在上例中是Rectangle ），且不能在此项之外定义任何数据，唯一例外是id（在上例中是redSquare）。

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

Component 还可以使用 `Qt.createComponent()` 动态创建对象。

Component此类声明方式适用于仅需该类型的实例、而无需添加全新文件的情况。但是，此类无法命名，因此无法用于声明属性或在类型注解中使用。若需此类功能，建议使用内联组件。

创建上下文

组件的创建上下文对应于声明该组件的上下文。当组件由ListView 或Loader等对象实例化时，该上下文将作为父上下文（从而形成上下文层次结构）。

在下面的示例中，comp1 是在 MyItem.qml 的根上下文中创建的，从该组件实例化的任何对象都将能够访问该上下文中的 ID 和属性，例如internalSettings.color 。 当在另一个上下文中（如下面的 main.qml 所示）将 `comp1 ` 用作 `ListView ` 委托时，它将继续访问其创建上下文中的属性（否则这些属性对外部用户而言将是私有的）。

Item {
    property Component mycomponent: comp1

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

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

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

创建上下文的生命周期必须比任何已创建的对象更长，这一点非常重要。更多详细信息请参阅《维护动态创建的对象》。

属性文档

progress : real [read-only]

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

status : enumeration [read-only]

该属性用于表示组件的加载状态。状态可以是以下之一：

url : url [read-only]

组件的 URL。这是用于构建该组件的 URL。

附带的信号文档

[attached] completed()

在对象实例化后触发。这可用于在启动时、当完整的 QML 环境建立完成后执行脚本代码。

onCompleted 信号处理程序可在任何对象上声明。处理程序的执行顺序未定义。

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

[attached] destruction()

在对象开始销毁时触发。这可用于撤销因响应completed()信号而执行的操作，或撤销应用程序中的其他命令式代码。

onDestruction 信号处理程序可以在任何对象上声明。处理程序的执行顺序未定义。

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

另请参阅 Qt Qml。

方法文档

QtObject createObject(QtObject parent, var properties)

创建并返回该组件的一个对象实例，该实例将具有给定的parent 和properties 。properties 参数是可选的。如果对象创建失败，则返回null。

该对象将在与创建该组件时相同的上下文中创建。若在非QML环境中创建的组件上调用此函数，该函数将始终返回null。

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

如果未向 createObject() 提供parent ，则必须保留对返回对象的引用，以免其被垃圾回收器销毁。无论随后是否设置了Item::parent ，此规则均适用，因为设置 Item 父对象不会改变对象的所有权，仅会更改图形父对象。

该方法接受一个可选的 `properties ` 参数，用于指定创建对象的初始属性值映射。这些值将在对象创建完成前应用。这比在对象创建后设置属性值更高效，特别是在定义大量属性值时，同时也允许在对象创建前（使用 `Qt.binding`）设置属性绑定。

properties 参数应指定为一个包含属性-值对的映射。例如，以下代码创建了一个对象，其x 和y 的初始值分别为 100 和 100：

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

可以通过 `destroy() ` 方法删除动态创建的实例。有关更多信息，请参阅《从 JavaScript 动态创建 QML 对象》。

另请参阅 incubateObject()。

string errorString()

返回任何错误的人类可读描述。

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

如果不存在错误，则返回一个空字符串。

var incubateObject(QtObject parent, var properties, enumeration mode)

为本组件的实例创建一个孵化器。孵化器允许异步实例化新的组件实例，且不会导致用户界面卡顿。

parent 参数指定了所创建实例的父对象。省略该参数或传入null将创建一个没有父对象的实例。在这种情况下，必须保留对该对象的引用，以防止其被垃圾回收器销毁。

properties 参数指定为属性-值对的映射表，这些属性将在创建对象时设置到该对象上。mode 可以是Qt.Synchronous或Qt.Asynchronous，用于控制实例是同步还是异步创建。 默认行为是异步的。在某些情况下，即使指定了 Qt.Synchronous，incubator 仍可能异步创建该对象。当调用 incubateObject() 的组件本身正在异步创建时，就会发生这种情况。

这三个参数均为可选。

若调用成功，该方法返回一个孵化器；否则返回 null。该孵化器具有以下属性：

• status - 孵化器的状态。有效值为 Component.Ready、Component.Loading 和 Component.Error。
• object - 已创建的对象实例。只有当孵化器处于 Ready 状态时，该实例才可用。
• onStatusChanged - 指定在状态发生变化时调用的回调函数。状态将作为参数传递给该回调函数。
• forceCompletion() - 用于同步完成孵化的调用。

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

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

const 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() ` 方法删除动态创建的实例。更多信息请参阅《从 JavaScript 动态创建 QML 对象》。

另请参阅 createObject()。