组件 QML 类型

封装 QML 组件定义。更多...

导入语句	import QtQml
实例化	QQmlComponent

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

属性

progress : real
status : 枚举
url : url

附加信号

completed()
destruction()

方法

QtObject createObject(QtObject parent, object properties)
string errorString()
object incubateObject(QtObject parent, object 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》来指定如何显示每个列表项。

可以使用《Qt.createComponent》() 方法动态创建《Component》对象。

创建上下文

Component 的创建上下文对应于 Component 声明时的上下文。在组件被如 ListView 或 Loader 等对象实例化时，此上下文被用作父上下文（创建一个上下文层次结构）。

在下面的示例中，`comp1` 是在 MyItem.qml 的根上下文中创建的，从这个组件实例化出的任何对象都可以访问这个上下文内的 ids 和属性，如 `internalSettings.color`。当 `comp1` 作为另一个上下文（如下面的 main.qml）中的 ListView 代理使用时，它将继续访问其创建上下文的属性（否则对外部用户将是私有的）。

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    //will create green Rectangles

    MyItem { id: myItem }
}

创建上下文的生存期必须长于任何创建的对象。有关更多详细信息，请参见《维护动态创建的对象》。

属性说明

进度 : 实数 [只读]

Component 加载的进度，从 0.0（没有加载）到 1.0（完成）。

状态 : 枚举 [只读]

此属性包含 Component 加载的状态。状态可以是以下之一

常量	描述
`Component.Null`	Component 没有可用的数据
`Component.Ready`	Component 已被加载，可以用来创建实例
`Component.Loading`	Component 正在加载
`Component.Error`	在加载 Component 时发生错误。调用 errorString() 将提供有关任何错误的可读描述。

url : URL [只读]

Component 的 URL。这是用于构造 Component 的 URL。

附加信号文档

completed()

在对象实例化后发出。这可以用于在完全建立 QML 环境后执行脚本代码。

`onCompleted` 信号处理器可以声明在任意对象上。处理器调用的顺序是未定义的。

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

注意：对应的处理器是 `onCompleted`。

destruction()

当对象开始销毁时发出。这可以用于取消对 completed() 信号或其他应用程序中的命令式代码的反应所做的操作。

`onDestruction` 信号处理器可以声明在任意对象上。处理器调用的顺序是未定义的。

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

注意：对应的处理器是 `onDestruction`。

另请参阅Qt Qml。

方法文档

QtObject createObject(QtObject parent, object properties)

创建并返回一个对象实例，它将以给定的 parent 和 properties 属性创建。`properties` 参数是可选的。如果对象创建失败，则返回 null。

对象将在与组件创建相同的环境中创建。此函数始终在未在 QML 中创建的组件上返回 null。

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

如果未向 createObject() 提供父对象，则必须保留返回对象的引用，以防止垃圾回收器销毁它。这是无论随后是否设置了 Item::parent 都成立，因为设置 Item 父对象并不改变对象的拥有权。只是更改了图形父对象。

从 QtQuick 1.1 开始，此方法接受一个可选的 properties 参数，该参数指定创建的对象的初始属性值的映射。这些值在最终确定对象创建之前应用。这比在对象创建后设置属性值更有效，尤其是在定义大量属性值的情况下，还可以在对象创建前设置属性绑定（使用 Qt.binding）。

参数 properties 作为一个属性-值项的映射来指定。例如，以下代码创建了初始 x 和 y 值分别为 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()

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

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

如果没有错误，则返回空字符串。

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

为该组件的实例创建一个孵化器。孵化器允许异步实例化新的组件实例，而不会在 UI 中造成冻结。

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

参数 properties 作为一个属性-值项的映射来指定，这些值在创建对象期间设置在创建的对象上。《i translate="no">模式可以是 Qt.Synchronous 或 Qt.Asynchronous，它控制实例是否以同步或异步的方式创建。默认为异步。在某些情况下，即使指定了 Qt.Synchronous，孵化器也可能异步创建对象。这发生在调用 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()。