Loader QML Type

Ermöglicht das dynamische Laden eines Teilbaums über eine URL oder eine Komponente. Mehr...

• Liste aller Elemente, einschließlich vererbter Elemente

Eigenschaften

• active : bool
• asynchronous : bool
• item : QtObject
• progress : real
• source : url
• sourceComponent : Component
• status : enumeration

Signale

• loaded()

Methoden

• void setSource(url source, var properties)

Ausführliche Beschreibung

Der Loader dient zum dynamischen Laden von QML-Komponenten.

Der Loader kann eine QML-Datei (mithilfe der Eigenschaft „ source “) oder ein „ Component “-Objekt (mithilfe der Eigenschaft „ sourceComponent “) laden. Er ist nützlich, um die Erstellung einer Komponente so lange aufzuschieben, bis sie benötigt wird: beispielsweise wenn eine Komponente bedarfsweise erstellt werden soll oder wenn eine Komponente aus Leistungsgründen nicht unnötig erstellt werden soll.

Hier ist ein Loader, der „Page1.qml“ als Komponente lädt, wenn auf „ MouseArea “ geklickt wird:

import QtQuick

Item {
    width: 200; height: 200

    Loader { id: pageLoader }

    MouseArea {
        anchors.fill: parent
        onClicked: pageLoader.source = "Page1.qml"
    }
}

Auf das geladene Objekt kann über die Eigenschaft „ item “ zugegriffen werden.

Wenn sich „ source “ oder „ sourceComponent “ ändert, werden alle zuvor instanziierten Elemente zerstört. Das Setzen von „ source “ auf eine leere Zeichenkette oder das Setzen von „ sourceComponent “ auf „ undefined “ zerstört das aktuell geladene Objekt, gibt Ressourcen frei und lässt den Loader leer.

Verhalten des Loaders bei der Größenanpassung

Beim Laden visueller Typen wendet der Loader die folgenden Regeln zur Größenanpassung an:

• Wenn für den Loader keine explizite Größe angegeben wird, wird der Loader nach dem Laden der Komponente automatisch auf die Größe des geladenen Elements angepasst.
• Wird die Größe des Loaders explizit durch Festlegen der Breite, Höhe oder durch Verankerung festgelegt, wird das geladene Element auf die Größe des Loaders angepasst.

In beiden Szenarien sind die Größe des Elements und die des Loaders identisch. Dadurch wird sichergestellt, dass die Verankerung am Loader der Verankerung am geladenen Element entspricht.

import QtQuick

Item {
  width: 200; height: 200

  Loader {
    // Explicitly set the size of the
    // Loader to the parent item's size
    anchors.fill: parent
    sourceComponent: rect
  }

  Component {
    id: rect
    Rectangle {
      width: 50
      height: 50
      color: "red"
      }
  }
}

import QtQuick

Item {
  width: 200; height: 200

  Loader {
    // position the Loader in the center
    // of the parent
    anchors.centerIn: parent
    sourceComponent: rect
  }

  Component {
      id: rect
      Rectangle {
          width: 50
          height: 50
          color: "red"
      }
  }
}

Wenn die Quellkomponente kein „Item“-Typ ist, wendet der Loader keine speziellen Größenanpassungsregeln an.

Empfangen von Signalen von geladenen Objekten

Alle vom geladenen Objekt ausgesendeten Signale können mithilfe des Typs „ Connections “ empfangen werden. Beispielsweise lädt die folgende Datei „ application.qml “ die Datei „ MyItem.qml “ und kann das Signal „ message “ vom geladenen Element über ein „ Connections “-Objekt empfangen:

import QtQuick

Item {
    width: 100; height: 100

    Loader {
       id: myLoader
       source: "MyItem.qml"
    }

    Connections {
        target: myLoader.item
        function onMessage(msg) { console.log(msg) }
    }
}

import QtQuick

Rectangle {
   id: myItem
   signal message(string msg)

   width: 100; height: 100

   MouseArea {
       anchors.fill: parent
       onClicked: myItem.message("clicked!")
   }
}

Fokus- und Tastenereignisse

Der Loader ist ein Fokusbereich. Seine Eigenschaft „ focus “ muss auf „ true “ gesetzt sein, damit eines seiner untergeordneten Elemente den aktiven Fokus erhalten kann. (Weitere Details finden Sie unter „Keyboard Focus“ in Qt Quick.) Alle im geladenen Element empfangenen Tastenereignisse sollten wahrscheinlich ebenfalls auf „ accepted “ gesetzt werden, damit sie nicht an den Loader weitergeleitet werden.

Beispielsweise lädt die folgende Datei „ application.qml “ die Seite „ KeyReader.qml “, wenn auf „ MouseArea “ geklickt wird. Beachten Sie, dass die Eigenschaft „ focus “ sowohl für den Loader als auch für das dynamisch geladene Objekt „ Item “ auf „ true “ gesetzt ist:

import QtQuick

Rectangle {
    width: 200; height: 200

    Loader {
        id: loader
        focus: true
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            loader.source = "KeyReader.qml"
        }
    }

    Keys.onPressed: (event)=> {
        console.log("Captured:",
                    event.text);
    }
}

import QtQuick

Item {
    Item {
        focus: true
        Keys.onPressed: (event)=> {
            console.log("KeyReader captured:",
                        event.text);
            event.accepted = true;
        }
    }
}

Sobald „ KeyReader.qml “ geladen ist, nimmt es Tastaturereignisse entgegen und setzt „ event.accepted “ auf „ true “, damit das Ereignis nicht an das übergeordnete „ Rectangle “ weitergeleitet wird.

Da „ QtQuick 2.0 “ verwendet wird, kann der Loader auch nicht-visuelle Komponenten laden.

Verwendung eines Loaders innerhalb eines View-Delegaten

In manchen Fällen möchten Sie möglicherweise einen Loader innerhalb eines View-Delegaten verwenden, um die Ladeleistung des Delegaten zu verbessern. Dies funktioniert in den meisten Fällen gut, es gibt jedoch einen wichtigen Punkt, den Sie im Zusammenhang mit dem „ creation context “ einer Komponente beachten sollten.

Im folgenden Beispiel ist die vom „ ListView “ in den Kontext von „ delegateComponent “ eingefügte Kontexteigenschaft „ index “ für „Text“ nicht zugänglich, da der Loader beim Instanziieren den Erstellungs-Kontext von „ myComponent “ als übergeordneten Kontext verwendet und „ index “ auf nichts innerhalb dieser Kontextkette verweist.

Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: index }    //fails
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            id: delegateComponent
            Loader {
                sourceComponent: myComponent
            }
        }
    }
}

In dieser Situation können wir die Komponente entweder inline verschieben

        delegate: Component {
            Loader {
                sourceComponent: Component {
                    Text { text: index }    //okay
                }
            }
        }

in eine separate Datei verschieben,

        delegate: Component {
            Loader {
                source: "MyComponent.qml" //okay
            }
        }

oder die erforderlichen Informationen explizit als Eigenschaft des Loaders festlegen (dies funktioniert, da der Loader sich selbst als Kontextobjekt für die Komponente festlegt, die er lädt).

Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: modelIndex }    //okay
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            Loader {
                property int modelIndex: index
                sourceComponent: myComponent
            }
        }
    }
}

Siehe auch Dynamic Object Creation.

Dokumentation zu Eigenschaften

active : bool

Diese Eigenschaft lautet „ true “, wenn der Loader derzeit aktiv ist. Der Standardwert für diese Eigenschaft ist „ true “.

Ist der Loader inaktiv, führt eine Änderung von „ source “ oder „ sourceComponent “ nicht dazu, dass das Element instanziiert wird, bis der Loader aktiviert wird.

Wird der Wert auf „inactive“ gesetzt, werden alle vom Loader geladenen „ item “ freigegeben, was jedoch keine Auswirkungen auf „ source “ oder „ sourceComponent “ hat.

Die ` status ` eines inaktiven Loaders ist immer ` Null`.

Siehe auch „ source “ und „ sourceComponent “.

asynchronous : bool

Diese Eigenschaft legt fest, ob die Komponente asynchron instanziiert wird. Standardmäßig ist sie auf „ false “ gesetzt.

In Verbindung mit der Eigenschaft „ source “ werden das Laden und die Kompilierung ebenfalls in einem Hintergrund-Thread ausgeführt.

Das asynchrone Laden erstellt die von der Komponente deklarierten Objekte über mehrere Frames hinweg und verringert die Wahrscheinlichkeit von Störungen in der Animation. Beim asynchronen Laden ändert sich der Status zu „Loader.Loading“. Sobald die gesamte Komponente erstellt wurde, ist „ item “ verfügbar und der Status ändert sich zu „Loader.Ready“.

Wird der Wert dieser Eigenschaft auf „ false “ gesetzt, während ein asynchrones Laden läuft, wird eine sofortige, synchrone Fertigstellung erzwungen. Dies ermöglicht es, ein asynchrones Laden zu starten und anschließend die Fertigstellung zu erzwingen, falls auf den Inhalt des Loaders zugegriffen werden muss, bevor das asynchrone Laden abgeschlossen ist.

Um zu vermeiden, dass die Elemente schrittweise geladen werden, setzen Sie „ visible “ entsprechend, z. B.

Loader {
    source: "mycomponent.qml"
    asynchronous: true
    visible: status == Loader.Ready
}

Beachten Sie, dass diese Eigenschaft nur die Instanziierung von Objekten betrifft; sie steht in keinem Zusammenhang mit dem asynchronen Laden einer Komponente über ein Netzwerk.

item : QtObject [read-only]

Diese Eigenschaft enthält das derzeit geladene Objekt der obersten Ebene.

Seit „ QtQuick 2.0 “ kann der Loader jeden Objekttyp laden.

progress : real [read-only]

Diese Eigenschaft gibt den Fortschritt beim Laden von QML-Daten aus dem Netzwerk an, von 0,0 (noch nichts geladen) bis 1,0 (abgeschlossen). Da die meisten QML-Dateien recht klein sind, ändert sich dieser Wert schnell von 0 auf 1.

Siehe auch status.

source : url

Diese Eigenschaft enthält die URL der QML-Komponente, die instanziiert werden soll.

Seit QtQuick 2.0 kann der Loader Objekte beliebiger Art laden; er ist nicht auf Item-Typen beschränkt.

Um das aktuell geladene Objekt zu entladen, setzen Sie diese Eigenschaft auf eine leere Zeichenkette oder setzen Sie „ sourceComponent “ auf „ undefined “. Das Setzen von „ source “ auf eine neue URL führt ebenfalls dazu, dass das durch die vorherige URL erstellte Element entladen wird.

Siehe auch sourceComponent, status und progress.

sourceComponent : Component

Diese Eigenschaft enthält das zu instanziierende „ Component “.

Item {
    Component {
        id: redSquare
        Rectangle { color: "red"; width: 10; height: 10 }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 10 }
}

Um das aktuell geladene Objekt zu entladen, setzen Sie diese Eigenschaft auf „ undefined “.

Da „ QtQuick 2.0 “ gilt, kann der Loader Objekte beliebiger Typen laden; er ist nicht auf Item-Typen beschränkt.

Siehe auch „ source “ und „ progress “.

status : enumeration [read-only]

Diese Eigenschaft gibt den Status des QML-Ladevorgangs an. Mögliche Werte sind:

• Loader.Null – Der Loader ist inaktiv oder es wurde keine QML-Quelle festgelegt
• Loader.Ready – Die QML-Quelle wurde geladen
• Loader.Loading – Die QML-Quelle wird gerade geladen
• Loader.Error – Beim Laden der QML-Quelle ist ein Fehler aufgetreten

Verwenden Sie diesen Status, um eine Aktualisierung bereitzustellen oder auf die Statusänderung in irgendeiner Weise zu reagieren. Sie könnten beispielsweise:

• Eine Zustandsänderung auslösen:

  State { name: 'loaded'; when: loader.status == Loader.Ready }

• Einen Signal-Handler für „ onStatusChanged “ implementieren:

  Loader {
      id: loader
      onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded')
  }

• Eine Bindung an den Statuswert herstellen:

  Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' }

Beachten Sie, dass der Status zunächst „Ready“ (oder „Error“) lautet, wenn es sich bei der Quelle um eine lokale Datei handelt. In diesem Fall wird zwar kein „onStatusChanged“-Signal ausgelöst, aber „onLoaded“ wird dennoch aufgerufen.

Siehe auch „ progress “.

Signal-Dokumentation

loaded()

Dieses Signal wird ausgelöst, wenn der Wert von „ status “ auf „ Loader.Ready “ wechselt oder wenn das erste Laden erfolgreich war.

Methodendokumentation

void setSource(url source, var properties)

Erstellt eine Objektinstanz der angegebenen „ source “-Komponente, die die angegebene „ properties “ aufweist. Das Argument „ properties “ ist optional. Auf die Instanz kann über die Eigenschaft „ item “ zugegriffen werden, sobald das Laden und die Instanziierung abgeschlossen sind.

Wenn die Eigenschaft „ active “ zum Zeitpunkt des Aufrufs dieser Funktion den Wert „ false “ hat, wird die angegebene „ source “-Komponente nicht geladen, aber die „ source “-Eigenschaft und der anfängliche „ properties “-Wert werden zwischengespeichert. Wenn der Loader auf „ active “ gesetzt wird, wird eine Instanz der „ source “-Komponente erstellt, wobei der anfängliche „ properties “-Wert festgelegt wird.

Das Festlegen der anfänglichen Eigenschaftswerte einer Instanz einer Komponente auf diese Weise löst keine zugehörigen „ Behavior“ aus.

Beachten Sie, dass der zwischengespeicherte „ properties “ gelöscht wird, wenn „ source “ oder „ sourceComponent “ nach dem Aufruf dieser Funktion, aber vor dem Setzen von „loader active “ geändert wird.

Beispiel:

// ExampleComponent.qml
import QtQuick 2.0
Rectangle {
    id: rect
    color: "red"
    width: 10
    height: 10

    Behavior on color {
        NumberAnimation {
            target: rect
            property: "width"
            to: (rect.width + 20)
            duration: 0
        }
    }
}

// example.qml
import QtQuick 2.0
Item {
    Loader {
        id: squareLoader
        onLoaded: console.log(squareLoader.item.width);
        // prints [10], not [30]
    }

    Component.onCompleted: {
        squareLoader.setSource("ExampleComponent.qml",
                             { "color": "blue" });
        // will trigger the onLoaded code when complete.
    }
}

Siehe auch source und active.