Loader QML Type

Permet le chargement dynamique d'une sous-arborescence à partir d'une URL ou d'un composant. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

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

Signaux

• loaded()

Méthodes

• object setSource(url source, object properties)

Description détaillée

Loader est utilisé pour charger dynamiquement des composants QML.

Il peut charger un fichier QML (à l'aide de la propriété source ) ou un objet Component (à l'aide de la propriété sourceComponent ). Il est utile pour retarder la création d'un composant jusqu'à ce qu'il soit nécessaire : par exemple, lorsqu'un composant doit être créé à la demande, ou lorsqu'un composant ne doit pas être créé inutilement pour des raisons de performance.

Voici un chargeur qui charge "Page1.qml" en tant que composant lorsque l'on clique sur le site MouseArea:

import QtQuick

Item {
    width: 200; height: 200

    Loader { id: pageLoader }

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

L'objet chargé est accessible à l'aide de la propriété item.

Si source ou sourceComponent change, tous les éléments précédemment instanciés sont détruits. Le fait de donner à source la valeur d'une chaîne vide ou à sourceComponent la valeur de undefined détruit l'objet actuellement chargé, libérant ainsi des ressources et laissant le chargeur vide.

Comportement de dimensionnement du chargeur

Lorsqu'il est utilisé pour charger des types visuels, le chargeur applique les règles de dimensionnement suivantes :

• Si aucune taille explicite n'est spécifiée pour le chargeur, celui-ci est automatiquement redimensionné à la taille de l'élément chargé une fois que le composant est chargé.
• Si la taille du chargeur est spécifiée explicitement en définissant la largeur, la hauteur ou par ancrage, l'élément chargé sera redimensionné à la taille du chargeur.

Dans les deux cas, la taille de l'élément et celle du chargeur sont identiques. Cela garantit que l'ancrage au chargeur est équivalent à l'ancrage à l'élément chargé.

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

Si le composant source n'est pas de type Item, le chargeur n'applique pas de règles de dimensionnement particulières.

Réception de signaux provenant d'objets chargés

Tous les signaux émis par l'objet chargé peuvent être reçus à l'aide du type Connections. Par exemple, l'application application.qml suivante charge MyItem.qml et peut recevoir le signal message de l'objet chargé par l'intermédiaire d'un objet Connections:

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

Focus et événements clés

Le chargeur est une portée de focalisation. Sa propriété focus doit être définie sur true pour que l'un de ses enfants obtienne le focus actif. (Pour plus de détails, voir Keyboard Focus à l' adresse Qt Quick.) Tout événement de touche reçu dans l'élément chargé devrait également être défini à l'adresse accepted afin de ne pas être propagé au chargeur.

Par exemple, l'exemple suivant application.qml charge KeyReader.qml lorsque l'on clique sur MouseArea. Remarquez que la propriété focus est définie sur true pour le chargeur ainsi que sur Item dans l'objet chargé dynamiquement :

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

Une fois que KeyReader.qml est chargé, il accepte les événements de clé et définit event.accepted à true afin que l'événement ne soit pas propagé au parent Rectangle.

Depuis QtQuick 2.0, le chargeur peut également charger des composants non visuels.

Utilisation d'un chargeur dans un délégué de vue

Dans certains cas, vous pouvez souhaiter utiliser un chargeur dans un délégué de vue afin d'améliorer les performances de chargement du délégué. Cela fonctionne bien dans la plupart des cas, mais il faut tenir compte d'un problème important lié à l'adresse creation context d'un composant.

Dans l'exemple suivant, la propriété de contexte index insérée par ListView dans le contexte de delegateComponent sera inaccessible au texte, car le chargeur utilisera le contexte de création de myComponent comme contexte parent lors de son instanciation, et index ne fait référence à rien dans cette chaîne de contexte.

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

Dans cette situation, nous pouvons soit déplacer le composant en ligne,

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

dans un fichier séparé,

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

soit définir explicitement les informations requises comme une propriété du chargeur (cela fonctionne parce que le chargeur se définit lui-même comme l'objet de contexte pour le composant qu'il charge).

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

Voir aussi Dynamic Object Creation.

Documentation sur les propriétés

active : bool

Cette propriété vaut true si le chargeur est actuellement actif. La valeur par défaut de cette propriété est true.

Si le chargeur est inactif, la modification de source ou sourceComponent n'entraînera pas l'instanciation de l'élément tant que le chargeur ne sera pas activé.

La définition de la valeur inactive entraînera la libération de tout item chargé par le chargeur, mais n'affectera pas le source ou le sourceComponent.

Le status d'un chargeur inactif est toujours Null.

Voir également source et sourceComponent.

asynchronous : bool

Cette propriété indique si le composant sera instancié de manière asynchrone. La valeur par défaut est false.

Lorsqu'elle est utilisée conjointement avec la propriété source, le chargement et la compilation seront également effectués dans un fil d'exécution en arrière-plan.

Le chargement asynchrone crée les objets déclarés par le composant sur plusieurs images, ce qui réduit la probabilité de problèmes d'animation. Lors d'un chargement asynchrone, le statut devient Loader.Loading. Une fois que l'ensemble du composant a été créé, le site item est disponible et l'état devient Loader.Ready.

Le fait de changer la valeur de cette propriété pour false alors qu'un chargement asynchrone est en cours forcera l'achèvement immédiat et synchrone. Cela permet de commencer un chargement asynchrone et de forcer l'achèvement si le contenu du chargeur doit être accessible avant que le chargement asynchrone ne soit terminé.

Pour éviter de voir les éléments se charger progressivement, définissez visible de manière appropriée, par exemple

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

Notez que cette propriété n'affecte que l'instanciation des objets ; elle n'est pas liée au chargement asynchrone d'un composant via un réseau.

item : QtObject [read-only]

Cette propriété contient l'objet de premier niveau qui est actuellement chargé.

Depuis QtQuick 2.0, le chargeur peut charger n'importe quel type d'objet.

progress : real [read-only]

Cette propriété indique la progression du chargement des données QML à partir du réseau, de 0.0 (rien de chargé) à 1.0 (terminé). La plupart des fichiers QML étant assez petits, cette valeur passera rapidement de 0 à 1.

Voir aussi status.

source : url

Cette propriété contient l'URL du composant QML à instancier.

Depuis QtQuick 2.0, le chargeur peut charger n'importe quel type d'objet ; il n'est pas limité aux types d'éléments.

Pour décharger l'objet actuellement chargé, attribuez à cette propriété la valeur d'une chaîne vide ou attribuez à sourceComponent la valeur de undefined. L'attribution à source d'une nouvelle URL entraînera également le déchargement de l'élément créé par l'URL précédente.

Voir également sourceComponent, status, et progress.

sourceComponent : Component

Cette propriété contient l'adresse Component à instancier.

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

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

Pour décharger l'objet actuellement chargé, définissez cette propriété à undefined.

Depuis QtQuick 2.0, Loader peut charger n'importe quel type d'objet ; il n'est pas limité aux types d'éléments.

Voir également source et progress.

status : enumeration [read-only]

Cette propriété indique l'état du chargement de QML. Il peut s'agir de l'un des éléments suivants

• Loader.Null - le chargeur est inactif ou aucune source QML n'a été définie
• Loader.Ready - la source QML a été chargée
• Loader.Loading - la source QML est en cours de chargement
• Loader.Error - une erreur s'est produite lors du chargement de la source QML

Utilisez ce statut pour fournir une mise à jour ou répondre au changement de statut d'une manière ou d'une autre. Par exemple, vous pouvez

• Déclencher un changement d'état :

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

• mettre en œuvre un gestionnaire de signal onStatusChanged:

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

• se lier à la valeur de l'état :

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

Notez que si la source est un fichier local, le statut sera initialement Ready (ou Error). Bien qu'il n'y ait pas de signal onStatusChanged dans ce cas, le signal onLoaded sera toujours invoqué.

Voir également progress.

Documentation sur les signaux

loaded()

Ce signal est émis lorsque le site status devient Loader.Ready, ou lors d'un chargement initial réussi.

Documentation de la méthode

object setSource(url source, object properties)

Crée une instance d'objet du composant source donné qui aura le composant properties donné. L'argument properties est facultatif. L'instance sera accessible via la propriété item une fois le chargement et l'instanciation terminés.

Si la propriété active est false au moment où cette fonction est appelée, le composant source donné ne sera pas chargé, mais le source et le properties initial seront mis en cache. Lorsque le chargeur est rendu active, une instance du composant source est créée avec la valeur initiale properties.

La définition des valeurs initiales des propriétés d'une instance d'un composant de cette manière ne déclenchera pas les Behaviorassociés.

Notez que le cache properties sera effacé si source ou sourceComponent est modifié après l'appel de cette fonction mais avant la définition du chargeur active.

Exemple :

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

Voir également source et active.