Component QML Type

Kapseln eine QML-Komponentendefinition. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

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

Angehängte Signale

• completed()
• destruction()

Methoden

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

Ausführliche Beschreibung

Komponenten sind wiederverwendbare, gekapselte QML-Typen mit genau definierten Schnittstellen.

Komponenten werden häufig über Komponentendateien definiert – also über „ .qml “-Dateien. Der Typ „Component“ ermöglicht es im Wesentlichen, QML-Komponenten inline innerhalb eines QML-Dokuments zu definieren, anstatt sie als separate QML-Datei zu speichern. Dies kann nützlich sein, um eine kleine Komponente innerhalb einer QML-Datei wiederzuverwenden oder um eine Komponente zu definieren, die logisch zu anderen QML-Komponenten innerhalb einer Datei gehört.

Hier ist zum Beispiel eine Komponente, die von mehreren „ Loader “-Objekten verwendet wird. Sie enthält ein einzelnes Element, ein „ 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 }
}

Beachten Sie, dass ein ` Rectangle ` für sich genommen zwar automatisch gerendert und angezeigt würde, dies bei dem oben genannten Rechteck jedoch nicht der Fall ist, da es innerhalb eines ` Component` definiert ist. Die Komponente kapselt die darin enthaltenen QML-Typen, als wären sie in einer separaten QML-Datei definiert, und wird erst bei Bedarf geladen (in diesem Fall durch die beiden ` Loader `-Objekte). Da „Component“ nicht von „Item“ abgeleitet ist, können Sie nichts daran verankern.

Das Definieren einer „ Component “ ähnelt dem Definieren eines QML-Dokuments. Ein QML-Dokument enthält ein einziges Element auf oberster Ebene, das das Verhalten und die Eigenschaften dieser Komponente definiert; außerhalb dieses Elements auf oberster Ebene können keine Eigenschaften oder Verhaltensweisen definiert werden. Ebenso enthält eine „ Component “-Definition ein einziges Element der obersten Ebene (im obigen Beispiel ein „ Rectangle “) und kann keine Daten außerhalb dieses Elements definieren, mit Ausnahme einer ID (im obigen Beispiel „redSquare“).

Der Typ „ Component “ wird häufig verwendet, um grafische Komponenten für Ansichten bereitzustellen. Beispielsweise benötigt die Eigenschaft „ ListView::delegate “ ein „ Component “, um festzulegen, wie die einzelnen Listenelemente angezeigt werden sollen.

Component Objekte können auch dynamisch mithilfe von ` Qt.createComponent()` erstellt werden.

Components sind nützlich, um einen Typ zu deklarieren, wenn Sie lediglich eine Instanz dieses Typs benötigen, ohne eine komplett neue Datei hinzufügen zu müssen. Sie können diesem Typ jedoch keinen Namen geben und ihn daher nicht zur Deklaration einer Eigenschaft oder in einer Typannotation verwenden. Wenn Sie dies benötigen, sollten Sie lieber Inline-Komponenten verwenden.

Erstellungskontext

Der Erstellungs-Kontext einer Komponente entspricht dem Kontext, in dem die Komponente deklariert wurde. Dieser Kontext wird als übergeordneter Kontext (zur Bildung einer Kontexthierarchie) verwendet, wenn die Komponente von einem Objekt wie beispielsweise einem ` ListView ` oder einem `Loader` instanziiert wird.

Im folgenden Beispiel wird „ comp1 “ innerhalb des Stammkontexts von „MyItem.qml“ erstellt, und alle aus dieser Komponente instanziierten Objekte haben Zugriff auf die IDs und Eigenschaften innerhalb dieses Kontexts, wie z. B. „ internalSettings.color “. Wenn „ comp1 “ als „ ListView “-Delegat in einem anderen Kontext verwendet wird (wie in „main.qml“ unten), hat es weiterhin Zugriff auf die Eigenschaften seines Erstellungskontexts (die andernfalls für externe Benutzer privat wären).

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 }
}

Es ist wichtig, dass die Lebensdauer des Erstellungskontexts die aller erstellten Objekte überdauert. Weitere Details finden Sie unter „Verwaltung dynamisch erstellter Objekte “.

Dokumentation zu Eigenschaften

progress : real [read-only]

Der Fortschritt beim Laden der Komponente, von 0,0 (noch nichts geladen) bis 1,0 (fertig).

status : enumeration [read-only]

Diese Eigenschaft gibt den Status des Ladevorgangs der Komponente an. Der Status kann einer der folgenden sein:

url : url [read-only]

Die URL der Komponente. Dies ist die URL, die zum Erstellen der Komponente verwendet wurde.

Beigefügte Signaldokumentation

[attached] completed()

Wird nach der Instanziierung des Objekts ausgelöst. Dies kann genutzt werden, um Skriptcode beim Start auszuführen, sobald die vollständige QML-Umgebung eingerichtet ist.

Der Signal-Handler „ onCompleted “ kann für jedes Objekt deklariert werden. Die Reihenfolge der Ausführung der Handler ist nicht definiert.

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

[attached] destruction()

Wird ausgelöst, wenn die Zerstörung des Objekts beginnt. Dies kann verwendet werden, um Änderungen rückgängig zu machen, die als Reaktion auf das Signal „ completed()“ oder anderen imperativen Code in Ihrer Anwendung vorgenommen wurden.

Der Signal-Handler „ onDestruction “ kann für jedes Objekt deklariert werden. Die Reihenfolge, in der die Handler ausgeführt werden, ist nicht definiert.

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

Siehe auch Qt Qml.

Methodendokumentation

QtObject createObject(QtObject parent, var properties)

Erstellt und gibt eine Objektinstanz dieser Komponente zurück, die die angegebenen Werte für „ parent “ und „ properties “ aufweist. Das Argument „ properties “ ist optional. Gibt „null“ zurück, wenn die Objekterstellung fehlschlägt.

Das Objekt wird im selben Kontext erstellt wie die Komponente, in der es erstellt wurde. Diese Funktion gibt immer `null` zurück, wenn sie für Komponenten aufgerufen wird, die nicht in QML erstellt wurden.

Wenn Sie ein Objekt ohne Festlegung eines übergeordneten Objekts erstellen möchten, geben Sie als Wert für „ parent “ „ null “ an. Beachten Sie: Wenn das zurückgegebene Objekt angezeigt werden soll, müssen Sie einen gültigen Wert für „ parent “ angeben oder die Eigenschaft „ parent “ des zurückgegebenen Objekts setzen, andernfalls ist das Objekt nicht sichtbar.

Wird bei `createObject()` kein ` parent ` übergeben, muss eine Referenz auf das zurückgegebene Objekt aufbewahrt werden, damit es nicht vom Garbage Collector zerstört wird. Dies gilt unabhängig davon, ob ` Item::parent ` anschließend gesetzt wird, da das Setzen des übergeordneten `Item`-Objekts die Objektzugehörigkeit nicht ändert. Es wird lediglich das grafisch übergeordnete Objekt geändert.

Diese Methode akzeptiert ein optionales Argument ` properties `, das eine Zuordnung der anfänglichen Eigenschaftswerte für das erstellte Objekt angibt. Diese Werte werden vor Abschluss der Objekterstellung angewendet. Dies ist effizienter als das Festlegen von Eigenschaftswerten nach der Objekterstellung, insbesondere wenn große Mengen an Eigenschaftswerten definiert sind, und ermöglicht zudem die Einrichtung von Eigenschaftsbindungen (mithilfe von ` Qt.binding`) vor der Erstellung des Objekts.

Das Argument ` properties ` wird als Map mit Eigenschafts-Wert-Paaren angegeben. Der folgende Code erstellt beispielsweise ein Objekt mit den Anfangswerten 100 für ` x ` und 100 für ` y `:

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

Dynamisch erstellte Instanzen können mit der Methode ` destroy() ` gelöscht werden. Weitere Informationen finden Sie unter „Dynamische Erstellung von QML-Objekten aus JavaScript “.

Siehe auch „ incubateObject()“.

string errorString()

Gibt eine für Menschen lesbare Beschreibung eines Fehlers zurück.

Die Zeichenkette enthält den Dateinamen, den Speicherort und die Beschreibung jedes Fehlers. Liegen mehrere Fehler vor, werden diese durch ein Zeilenumbruchzeichen voneinander getrennt.

Liegen keine Fehler vor, wird eine leere Zeichenkette zurückgegeben.

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

Erstellt einen Inkubator für eine Instanz dieser Komponente. Inkubatoren ermöglichen die asynchrone Instanziierung neuer Komponenteninstanzen und verhindern so, dass die Benutzeroberfläche einfriert.

Das Argument „ parent “ gibt das übergeordnete Objekt an, zu dem die erstellte Instanz gehören soll. Wird der Parameter weggelassen oder der Wert „null“ übergeben, wird ein Objekt ohne übergeordnetes Objekt erstellt. In diesem Fall muss eine Referenz auf das erstellte Objekt aufbewahrt werden, damit es nicht vom Garbage Collector gelöscht wird.

Das Argument ` properties ` wird als Map aus Eigenschaft-Wert-Elementen angegeben, die während der Konstruktion auf das erstellte Objekt gesetzt werden. ` mode ` kann entweder `Qt.Synchronous` oder `Qt.Asynchronous` sein und steuert, ob die Instanz synchron oder asynchron erstellt wird. Standardmäßig erfolgt die Erstellung asynchron. Unter bestimmten Umständen kann der Incubator das Objekt auch dann asynchron erstellen, wenn „Qt.Synchronous“ angegeben ist. Dies geschieht, wenn die Komponente, die `incubateObject()` aufruft, selbst asynchron erstellt wird.

Alle drei Argumente sind optional.

Bei Erfolg gibt die Methode einen Incubator zurück, andernfalls null. Der Incubator verfügt über die folgenden Eigenschaften:

• status - Der Status des Incubators. Gültige Werte sind „Component.Ready“, „Component.Loading“ und „Component.Error“.
• object - Die erstellte Objektinstanz. Diese ist erst verfügbar, sobald sich der Incubator im Status „Ready“ befindet.
• onStatusChanged - Gibt eine Callback-Funktion an, die bei einer Statusänderung aufgerufen wird. Der Status wird als Parameter an den Callback übergeben.
• forceCompletion() - Aufruf, um die Inkubation synchron abzuschließen.

Das folgende Beispiel veranschaulicht die Verwendung eines Inkubators:

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!");
}

Dynamisch erstellte Instanzen können mit der Methode „ destroy() “ gelöscht werden. Weitere Informationen finden Sie unter „Dynamische Erstellung von QML-Objekten aus JavaScript “.

Siehe auch „ createObject()“.