Component QML Type 譯文

封裝一個QML元件定義。 import聲明：import QtQml 2.15 執行個體化：QQmlComponet  

屬性

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

連接配接的信号

• completed()
• destruction()

方法

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

詳細說明

元件是可複用的，用定義清晰的接口封裝QML類型。 元件通常由元件檔案定義，就是.qml檔案。元件類型本質上允許QML元件在QML document 中内聯定義，而不是單獨定義QML檔案。這對于在QML檔案中複用小元件，或者定義邏輯上屬于其他QML元件的Component是非常有效的。   例如：下面是一個被多個加載器元件使用的Component，包含一個獨立的Item，一個Rectangle 檔案：

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會自動渲染和顯示，但是上面的Rectangle因為是在元件内定義的，是以不會自動重新整理。元件将QML類型封裝在其中，就像它們在單獨的QML檔案中定義一樣，直到被請求時才加載(在本例中，由兩個加載器對象加載)。因為Component不是從Item派生的，是以您不能将任何東西錨定到它。   定義元件類似于定義QML文檔。QML文檔有一個定義該元件的行為和屬性的頂級項，并且不能定義該頂級項之外的屬性或行為。同樣，元件定義包含單個頂級項(在上面的示例中是一個矩形)，并且不能定義該項之外的任何資料，除了id(在上面的示例中是redSquare)。   元件類型通常用于為視圖提供圖形化元件。例如，ListView::delegate屬性需要一個元件來指定每個清單項如何顯示。   元件對象也可以使用Qt.createComponent()動态建立。  

建立情景

元件的建立上下文對應于聲明元件的上下文。當元件被ListView或Loader這樣的對象執行個體化時，這個上下文被用作父上下文(建立上下文層次結構)。   在下面的示例中，comp1是在MyItem的根上下文中建立的 .qml，并且從該元件執行個體化的任何對象都可以通路該上下文中的id和屬性，例如internalSettings.color。當comp1在另一個上下文中用作ListView委托時(如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 }
}
           

建立上下文的生存期比任何建立的對象的生存期都要長，這一點很重要。有關更多細節，請參見 Maintaining Dynamically Created Objects.  

文檔屬性

progress: real

• 加載元件的進度，從0到1

  status: enumeration 元件加載狀态，有如下狀态：

• Component.Null - 元件沒有可用資料
• Component.Ready - 元件已加載，可以建立執行個體
• Component.Loading - 元件加載中
• Component.Error - 元件加載中出現錯誤，調用 errorString() 取得可識别的錯誤資訊

  url: url

• 元件URL，用于構造元件的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  

方法文檔

object createObject(QtObject parent, object properties)

建立并傳回該元件的對象執行個體，并且具有傳入的父節點參數和屬性參數。屬性參數可選。建立失敗傳回null。   建立的對象群組件建立的上下文是同一個，如果調用的元件不是在QML中建立的，始終傳回null。   如果不想傳入parent參數，可以傳null。注意，如果傳回的對象用于展示，那必須提供一個有效的父節點參數，或者設定傳回對象的parent屬性，否則對象不可見。   如果沒有提供parent參數，則必須持有傳回對象的引用，防止垃圾回收。無論之後是否設定Item::parent，這都是正确的，因為設定Item parent并不會改變對象的所有權。隻有圖形父節點被更改。   從QtQuick 1.1開始，該方法接受一個可選的properties參數，該參數指定建立對象的初始屬性值的映射。這些值在對象建立完成之前應用。這比在對象建立之後設定屬性值更有效，特别是在定義了大量屬性值的情況下，而且還允許在對象建立之前設定屬性綁定(使用Qt.binding)。   properties參數被指定為鍵值對的映射。例如，下面的代碼建立了一個對象，其初始x值和y值分别為100和100:

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

使用destroy()方法删除動态建立的執行個體。檢視 Dynamic QML Object Creation from JavaScript。  

string errorString()

傳回可識别錯誤描述。   該字元串包括每個錯誤的檔案、位置和描述。如果存在多個錯誤，則用換行符分隔。   如果沒有錯誤，則傳回一個空字元串。  

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

為該元件的執行個體建立孵化器。孵化器允許新元件執行個體異步執行個體化，并且不會在UI中造成當機。   parent參數指定建立執行個體的父節點。忽略參數或傳遞null将建立一個沒有父對象的對象。在這種情況下，必須持有對已建立對象的引用，以便它不會被垃圾回收器銷毀。   properties參數被指定為鍵值對的映射，該映射将在建立的對象的構造過程中設定。模式可以是Qt.Synchronous或Qt.Asynchronous，它控制執行個體是同步建立還是異步建立。預設是異步的。在某些情況下，即使指定了Qt.Synchronous，孵化器也可能異步地建立對象。如果調用incubateObject()的元件本身是異步建立的，就會發生這種情況。   這三個參數都是可選的。   如果成功，該方法将傳回孵卵器，否則為空。孵化器具有以下特性:

• status 孵化器的狀态，就是元件 的 Ready,Loading, Error狀态
• object 建立的對象執行個體。隻有在孵化器是Ready狀态才可用。
• 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 not ready!");
        }
    }
} else {
    print("Object", incubator.object, "is ready immediately!");
}
           

使用destroy()方法删除動态建立的執行個體。檢視 Dynamic QML Object Creation from JavaScript。