Loader QML Type

Permet le chargement dynamique d'une sous-arborescence à partir d'une URL ou d'un composant. En savoir plus...

• 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

• void setSource(url source, var properties)

Description détaillée

Loader sert à charger dynamiquement des composants QML.

Le Loader 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 différer 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'il ne doit pas être créé inutilement pour des raisons de performances.

Voici un Loader qui charge « Page1.qml » en tant que composant lorsque l'on clique sur l'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 via la propriété ` item `.

Si la propriété « source » ou « sourceComponent » change, tous les éléments précédemment instanciés sont détruits. Définir « source » sur une chaîne vide ou « sourceComponent » sur « undefined » détruit l’objet actuellement chargé, libérant ainsi des ressources et laissant le Loader vide.

Comportement du Loader en matière de dimensionnement

Lorsqu’il est utilisé pour charger des types visuels, le Loader applique les règles de redimensionnement suivantes :

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

Dans les deux cas, la taille de l’élément et celle du Loader sont identiques. Cela garantit que l’ancrage au Loader équivaut à 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 Loader n’applique aucune règle de dimensionnement particulière.

Réception des signaux provenant des objets chargés

Tout signal émis par l’objet chargé peut être reçu à l’aide du type « Connections ». Par exemple, l’ application.qml suivant charge MyItem.qml et est capable de recevoir le signal « message » de l’élément chargé via 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!")
   }
}

Événements de focus et de touche

Le Loader est une zone de focus. Sa propriété ` focus ` doit être définie sur ` true ` pour que l’un de ses enfants puisse obtenir le focus actif. (Voir « Focus clavier » dans Qt Quick pour plus de détails.) Tout événement de touche reçu dans l’élément chargé doit également être ` accepted ` afin qu’il ne soit pas propagé au Loader.

Par exemple, l’ application.qml e suivante charge KeyReader.qml lorsque l’ MouseArea est cliqué. Notez que la propriété focus est définie sur true pour le Loader ainsi que pour l’ 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 KeyReader.qml chargé, il accepte les événements de touche et définit event.accepted sur true afin que l’événement ne soit pas propagé au Rectangle parent.

Grâce à ` QtQuick 2.0`, `Loader` peut également charger des composants non visuels.

Utilisation d’un Loader au sein d’un délégué de vue

Dans certains cas, vous pouvez souhaiter utiliser un Loader au sein d’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 existe un point important à prendre en compte concernant l’ 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 à `Text`, car le `Loader` utilisera le contexte de création de ` myComponent ` comme contexte parent lors de son instanciation, et ` index ` ne fait référence à aucun élément de cette chaîne de contextes.

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 ce cas, 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 en tant que propriété du Loader (cela fonctionne car le Loader se définit lui-même comme 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 également Dynamic Object Creation.

Documentation sur les propriétés

active : bool

Cette propriété prend la valeur « 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 la propriété « source » ou « sourceComponent » n’entraînera pas l’instanciation de l’élément tant que le chargeur n’aura pas été activé.

Définir la valeur sur « inactive » entraînera la libération de tout item chargé par le chargeur, mais n’affectera pas les propriétés source ou sourceComponent.

L'status d'un chargeur inactif est toujours « Null ».

Voir également source et sourceComponent.

asynchronous : bool

Cette propriété détermine si le composant sera instancié de manière asynchrone. Par défaut, elle est définie sur « false ».

Lorsqu’elle est utilisée conjointement avec la propriété source, le chargement et la compilation s’effectuent également dans un thread d’arrière-plan.

Le chargement asynchrone crée les objets déclarés par le composant sur plusieurs images, ce qui réduit le risque de saccades dans l’animation. Lors d’un chargement asynchrone, l’état passe à « Loader.Loading ». Une fois le composant entièrement créé, la propriété « item » est disponible et l’état passe à « Loader.Ready ».

Modifier la valeur de cette propriété pour la définir sur « false » alors qu’un chargement asynchrone est en cours forcera une finalisation immédiate et synchrone. Cela permet de lancer un chargement asynchrone, puis d’en forcer la finalisation si le contenu du Loader doit être accessible avant la fin du chargement asynchrone.

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 d’objets ; elle n’a aucun rapport avec le chargement asynchrone d’un composant via un réseau.

item : QtObject [read-only]

Cette propriété contient l'objet de niveau supérieur actuellement chargé.

Depuis la version QtQuick 2.0, Loader peut charger n'importe quel type d'objet.

progress : real [read-only]

Cette propriété indique la progression du chargement des données QML depuis le réseau, de 0,0 (rien n'a été chargé) à 1,0 (chargement terminé). La plupart des fichiers QML étant assez légers, cette valeur passera rapidement de 0 à 1.

Voir également status.

source : url

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

Depuis la version QtQuick 2.0, Loader est capable de charger n'importe quel type d'objet ; il n'est pas limité aux types Item.

Pour décharger l’objet actuellement chargé, définissez cette propriété sur une chaîne vide, ou remplacez sourceComponent par undefined. Le fait de définir source sur 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'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é sur undefined.

À partir de la version QtQuick 2.0, Loader est capable de charger n'importe quel type d'objet ; il n'est pas limité aux types Item.

Voir également source et progress.

status : enumeration [read-only]

Cette propriété indique l'état du chargement du QML. Elle peut prendre l'une des valeurs suivantes :

• 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 cet état pour fournir une mise à jour ou réagir d’une manière ou d’une autre au changement d’état. Par exemple, vous pourriez :

• Déclencher un changement d’état :

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

• Implémenter un gestionnaire de signal « onStatusChanged » :

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

• Lier la valeur du statut :

  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 tout de même appelé.

Voir aussi progress.

Documentation sur les signaux

loaded()

Ce signal est émis lorsque l'status passe à l'état « Loader.Ready », ou lors d'un chargement initial réussi.

Documentation des méthodes

void setSource(url source, var properties)

Crée une instance de l'objet du composant « source » spécifié, qui possédera la propriété « properties » indiquée. 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 prend la valeur false au moment de l’appel de cette fonction, le composant source spécifié ne sera pas chargé, mais les propriétés source et properties initiales seront mises en cache. Lorsque le chargeur est défini sur active, une instance du composant source sera créée avec la propriété properties initiale définie.

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

Notez que l’ properties mise en cache sera effacée si l’ source ou l’ sourceComponent est modifiée après l’appel de cette fonction, mais avant la configuration 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.