Back to Qt.io
Contact Us Blog Download Qt

Loader QML Type

Ermöglicht das dynamische Laden eines Teilbaums von einer URL oder Komponente. Mehr...

Import Statement: import QtQuick
Inherits:

Item

Eigenschaften

Signale

Methoden

  • object setSource(url source, object properties)

Detaillierte Beschreibung

Loader wird zum dynamischen Laden von QML-Komponenten verwendet.

Loader kann eine QML-Datei (mit der Eigenschaft source ) oder ein Component Objekt (mit der Eigenschaft sourceComponent ) laden. Er ist nützlich, um die Erstellung einer Komponente zu verzögern, bis sie benötigt wird: z.B. wenn eine Komponente bei Bedarf erstellt werden soll, oder wenn eine Komponente aus Leistungsgründen nicht unnötig erstellt werden soll.

Hier ist ein Loader, der "Seite1.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 einen leeren String oder von sourceComponent auf undefined zerstört das aktuell geladene Objekt, gibt Ressourcen frei und lässt den Loader leer.

Größenverhalten des Loader

Wenn der Loader zum Laden visueller Typen verwendet wird, wendet er die folgenden Größenregeln an:

  • Wenn keine explizite Größe für den Loader angegeben ist, wird die Größe des Loader automatisch an die Größe des geladenen Objekts angepasst, sobald die Komponente geladen ist.
  • Wenn die Größe des Loader explizit durch Setzen der Breite, Höhe oder durch Verankerung angegeben wird, wird das geladene Element an die Größe des Loader angepasst.

In beiden Fällen sind die Größe des Elements und die des Loader identisch. Dadurch wird sichergestellt, dass die Verankerung im Loader der Verankerung im geladenen Element entspricht.

sizeloader.qmlsizeitem.qml
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"
      }
  }
}
Das rote Rechteck wird auf die Größe des Wurzelobjekts angepasst.Das rote Rechteck hat die Größe 50x50, zentriert im Stammelement.

Wenn die Quellkomponente kein Elementtyp ist, wendet der Loader keine speziellen Größenregeln an.

Empfangen von Signalen von geladenen Objekten

Alle Signale, die vom geladenen Objekt ausgesendet werden, können mit dem Typ Connections empfangen werden. Das folgende application.qml lädt beispielsweise MyItem.qml und kann das Signal message des geladenen Objekts über ein Objekt Connections empfangen:

application.qmlMeinElement.qml
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!")
   }
}

Da MyItem.qml innerhalb des Geltungsbereichs des Loader geladen wird, könnte es alternativ auch direkt eine beliebige Funktion aufrufen, die im Loader oder seinem übergeordneten Item definiert ist.

Fokus und Tastenereignisse

Loader ist ein Fokusbereich. Seine Eigenschaft focus muss auf true gesetzt werden, damit eines seiner Kinder den aktiven Fokus erhält. (Siehe Tastaturfokus in Qt Quick für weitere Details.) Alle Tastenereignisse, die im geladenen Element empfangen werden, sollten wahrscheinlich auch accepted sein, damit sie nicht an den Loader weitergegeben werden.

Zum Beispiel lädt die folgende application.qml KeyReader.qml , wenn MouseArea angeklickt wird. Beachten Sie, dass die Eigenschaft focus sowohl für den Loader als auch für Item im dynamisch geladenen Objekt auf true gesetzt ist:

application.qmlKeyReader.qml
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, akzeptiert es Tastenereignisse und setzt event.accepted auf true, damit das Ereignis nicht an das übergeordnete Rectangle weitergegeben wird.

Seit QtQuick 2.0 kann der Loader auch nicht-visuelle Komponenten laden.

Verwendung eines Loader innerhalb eines View Delegate

In einigen Fällen möchten Sie vielleicht einen Loader innerhalb eines Ansichtsdelegaten verwenden, um die Ladeleistung des Delegaten zu verbessern. Dies funktioniert in den meisten Fällen gut, aber es gibt ein wichtiges Problem, das im Zusammenhang mit der creation context einer Komponente zu beachten ist.

Im folgenden Beispiel wird die Kontexteigenschaft index, die von ListView in den Kontext von delegateComponent eingefügt wurde, für Text unzugänglich sein, da der Loader bei seiner Instanziierung den Erstellungskontext 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,

        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 Loader setzen (dies funktioniert, weil der Loader sich selbst als Kontextobjekt für die zu ladende Komponente setzt).

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.

Eigenschaft Dokumentation

active : bool

Diese Eigenschaft ist true, wenn der Loader gerade aktiv ist. Der Standardwert für diese Eigenschaft ist true.

Wenn der Loader inaktiv ist, führt eine Änderung von source oder sourceComponent nicht dazu, dass das Element instanziiert wird, bis der Loader wieder aktiv wird.

Das Setzen des Wertes auf inaktiv führt dazu, dass alle vom Loader geladenen item freigegeben werden, hat aber keine Auswirkungen auf source oder sourceComponent.

Der status eines inaktiven Loaders ist immer Null.

Siehe auch source und sourceComponent.


asynchronous : bool

Diese Eigenschaft gibt an, ob die Komponente asynchron instanziiert wird. Standardmäßig lautet sie false.

Wenn sie in Verbindung mit der Eigenschaft source verwendet wird, werden das Laden und die Kompilierung ebenfalls in einem Hintergrund-Thread durchgeführt.

Durch asynchrones Laden werden die von der Komponente deklarierten Objekte über mehrere Frames hinweg erstellt, wodurch die Wahrscheinlichkeit von Störungen in der Animation verringert wird. Beim asynchronen Laden ändert sich der Status in Loader.Loading. Sobald die gesamte Komponente erstellt wurde, ist die Website item verfügbar und der Status ändert sich in Loader.Ready.

Wird der Wert dieser Eigenschaft während eines asynchronen Ladevorgangs auf false geändert, wird ein sofortiger, synchroner Abschluss erzwungen. Dies ermöglicht es, ein asynchrones Laden zu beginnen und dann den Abschluss zu erzwingen, wenn auf den Inhalt des Loader zugegriffen werden muss, bevor das asynchrone Laden abgeschlossen ist.

Um zu vermeiden, dass die Elemente nach und nach geladen werden, setzen Sie visible entsprechend, z. B.

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

Beachten Sie, dass sich diese Eigenschaft nur auf die Instanziierung von Objekten auswirkt; sie hat nichts mit dem asynchronen Laden einer Komponente über ein Netzwerk zu tun.


item : QtObject [read-only]

Diese Eigenschaft enthält das Objekt der obersten Ebene, das gerade geladen wird.

Seit QtQuick 2.0 kann der Loader jeden Objekttyp laden.


progress : real [read-only]

Diese Eigenschaft enthält den Fortschritt des Ladens von QML-Daten aus dem Netzwerk, von 0.0 (nichts geladen) bis 1.0 (fertig). Die meisten QML-Dateien sind recht klein, so dass sich dieser Wert schnell von 0 auf 1 ändert.

Siehe auch status.


source : url

Diese Eigenschaft enthält die URL der zu instanziierenden QML-Komponente.

Seit QtQuick 2.0 ist Loader in der Lage, jeden Objekttyp zu laden; er ist nicht auf Item-Typen beschränkt.

Um das aktuell geladene Objekt zu entladen, setzen Sie diese Eigenschaft auf einen leeren String oder setzen Sie sourceComponent auf undefined. Wenn Sie source auf eine neue URL setzen, wird auch das von der vorherigen URL erstellte Objekt entladen.

Siehe auch sourceComponent, status, und progress.


sourceComponent : Component

Diese Eigenschaft enthält die 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.

Seit QtQuick 2.0 ist der Loader in der Lage, jeden Objekttyp zu laden; er ist nicht auf Item-Typen beschränkt.

Siehe auch source und progress.


status : enumeration [read-only]

Diese Eigenschaft enthält den Status des QML-Ladens. Sie kann einer der folgenden Werte sein:

  • 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 vorzunehmen oder auf irgendeine Weise auf die Statusänderung zu reagieren. Zum Beispiel könnten Sie:

  • Eine Zustandsänderung auslösen:
    State { name: 'loaded'; when: loader.status == Loader.Ready }
  • Implementieren Sie einen onStatusChanged Signalhandler:
    Loader {
    id: loader
    onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded')
}
  • Bindung an den Statuswert:
    Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' }

Beachten Sie, dass, wenn die Quelle eine lokale Datei ist, der Status anfänglich Ready (oder Error) sein wird. Während es in diesem Fall kein onStatusChanged-Signal gibt, wird das onLoaded-Signal trotzdem aufgerufen.

Siehe auch progress.


Signal-Dokumentation

loaded()

Dieses Signal wird ausgegeben, wenn status Loader.Ready wird, oder bei erfolgreichem ersten Laden.

Hinweis: Der entsprechende Handler ist onLoaded.


Methode Dokumentation

object setSource(url source, object properties)

Erzeugt eine Objektinstanz der angegebenen source Komponente, die die angegebene properties hat. 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 false ist, wird die angegebene Komponente source nicht geladen, sondern die source und die anfängliche properties werden zwischengespeichert. Wenn der Loader auf active gesetzt wird, wird eine Instanz der Komponente source mit dem Initialwert properties erstellt.

Das Einstellen der anfänglichen Eigenschaftswerte einer Instanz einer Komponente auf diese Weise löst keine zugehörigen Behaviors aus.

Beachten Sie, dass der Zwischenspeicher properties gelöscht wird, wenn source oder sourceComponent nach dem Aufruf dieser Funktion, aber vor dem Setzen des Loaders 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.


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.