QML类型说明-Component

Component

ImportStatement:   import QtQml 2.2

Instantiates:     QQmlComponent

 

Properties

progress :real

status :enumeration

url : url

 

Attached Signals

completed()

destruction()

 

Methods

objectcreateObject(Item parent, object properties)

stringerrorString()

objectincubateObject(Item parent, object properties, enumeration mode)

 

Detailed Description

这个组件是可重用的，有着良好接口的QML封装类型。Components常常被组件文件定义。组件文件是.qml文件。Component类型本质上允许在一个QML文档定义内联组件，而不是用单独的QML文件。组件有益于在一个QML文件中重用小组件或者在。qml中定义可被其他QML文件使用的组件。

例如，这里有个被多次装载的组件，它包含单一项Rectangle：

import QtQuick2.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能被自己渲染和显示，但这不是上面的Rectangle显示的理由。因为它被定义在一个Component内部，就像使用单独的QML文件定义，如果不加载，它就不显示。因为组件不是Item的派生，所以我们没有办法锚定到它。

定义组件和定义QML文档相似。一个QML文档有一个顶层的Item，它定义了组件的行为和属性。不能在顶层Item的外面定义任何属性或行为。与之相同，一个组件定义包含一个单一的顶层Item。（上面的例子中是Rectangle），除了id标识，不能在Item的外面定义任何数据。（上面的例子中是redSquare）

Component常常用来为显示提供一个图形组件。例如ListView::delegate属性需要一个组件来指明列表中的项应该如何显示。Component也能被Qt.createComponent()动态的创建。

 

创建内容：

组件的创建内容对应于组件被宣布的内容。当组件被一个诸如ListView或Loader的对象实例化，这个内容被用作父内容层次结构的创建。

在下面的例子中，comp1在MyItem.qml的根内容上创建，在这个组件的任何对象实例中，都可访问ids和属性，比如internalSettings.color。当comp1被用在另一个内容（如main.qml下）中ListView的delegate属性上时，它依旧能访问MyItem.qml的创建内容，但这些内容对main.qml的其他内容来说，是私有的。

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 }

}

 

Property Documentation

progress :real

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

 

status :enumeration

组件的加载状态，它是下面的值之一：

Component.Null- 没有数据可利用

Component.Ready- 组件加载完毕，能创建实例。

Component.Loading- 组件正在被加载。

Component.Error- 加载组件发生错误，errorString()提供了可阅读的错误描述。

 

url : url

用于构造组件的URL。

 

AttachedSignal Documentation

completed()

在组件启动完成之后发射这个信号。这被用来在完整的QML环境建立后，执行启动脚本代码。响应的操作句柄是onCompleted。它能在任何对象中宣部，onCompleted的运行次序是未定义的。

Rectangle {

    Component.onCompleted:console.log("Completed Running!")

    Rectangle {

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

    }

}

 

destruction()

当组件被摧毁时，发射这个信号。它能用来撤销在completed()信号上响应的工作或者我们应用其他必要处理的工作。操作句柄是onDestruction。它能被任何对象宣布。注意：onDestruction被用于组件整体被摧毁，而不是一个具体的对象。其运行的次序是未定义的。

Rectangle {

    Component.onDestruction:console.log("Destruction Beginning!")

    Rectangle {

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

    }

}

 

Method Documentation

objectcreateObject(Item parent, object properties)

用parent和properties创建并返回一个组件的实例。properties参数是可选的，如果创建失败，则返回空。创建对象的内容和组件被创建时一致。如果调用的组件不是在QML中创建的，则这个函数总是返回空。

如果我们希望创建不设置父母的对象，指定parent的值为空。注意如果返回的对象需要被显示，我们必须提供有效的父母值或设置返回对象的父母属性，否则对象将不可见。如果父母没有在createObject()的时候被提供，返回对象的引用则被保留而不会被垃圾收集器摧毁。这是真的不管，无论Item::parent是否被设置。这是因为设置Item parent没有改变对象的拥有者，仅仅是显示控制的父被改变。

在QtQuick 1.1，这个方法接受可选择的属性参数，它是创建实例的初始化属性值的映射。这些值在对象创建结束前被设置比创建之后设置更有效率，特别对大型属性值的定义，效率提升的更明显。同时它也允许属性在对象创建之前绑定（使用Qt.binding）。

properties是对象的属性值的映射，例如下面的代码，使用x为100，y为100创建一个对象。

varcomponent = Qt.createComponent("Button.qml");

if(component.status == Component.Ready)

    component.createObject(parent,{"x": 100, "y": 100});

动态创建的实例，能被destroy()方法摧毁。更多信息参阅《Dynamic QML Object Creation from JavaScript》

 

stringerrorString()

返回错误的描述。这个信息包含文件，路经和错误的描述。如果多个错误吹按，他们被放在新行。如果没有错误发生，它是空字符。

 

objectincubateObject(Item parent, object properties, enumeration mode)

为组件的实例创建孵化器。孵化器允许我们异步创建组件的实例，这么做不会阻塞UI。

parent指明了创建的实例的父，该参数允许为空，标识没有父。在这种情况下，实例的引用被保留，而不会被垃圾收集器摧毁。properties参数是实例被构造是，用来初始化属性的值的映射。模式为Qt.Synchronous或Qt.Asynchronous，用来控制我们同步还是异步创建实例。默认是异步的。在某些情况下，即使Qt.Synchronous被设置，实例依然异步创建。这发生在调用incubateObject()的组件实例本身就被异步创建的时候。

3个参数都是可选的。

如果成功，该方法返回一个孵化器对象，否则为空。孵化器有下面的属性：

status：孵化期的状态，有效值是Component.Ready、Component.Loading和Component.Error。

object Thecreated object instance：仅仅当孵化期在Ready状态有效，为孵化器创建的实例。

onStatusChanged：状态变化时指定的回调，status作为参数传递。

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

下面的例子展示了如何使用孵化器：

 

varcomponent = Qt.createComponent("Button.qml");

 

varincubator = 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()方法摧毁。更多信息参阅《Dynamic QML Object Creation from JavaScript》