Loader QML Type

Permite la carga dinámica de un subárbol desde una URL o Componente. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

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

Señales

• loaded()

Métodos

• object setSource(url source, object properties)

Descripción detallada

Loader se utiliza para cargar dinámicamente componentes QML.

Loader puede cargar un archivo QML (utilizando la propiedad source ) o un objeto Component (utilizando la propiedad sourceComponent ). Es útil para retrasar la creación de un componente hasta que sea necesario: por ejemplo, cuando un componente debe crearse bajo demanda, o cuando un componente no debe crearse innecesariamente por razones de rendimiento.

A continuación se muestra un cargador que carga "Page1.qml" como componente cuando se hace clic en MouseArea:

import QtQuick

Item {
    width: 200; height: 200

    Loader { id: pageLoader }

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

Se puede acceder al objeto cargado mediante la propiedad item.

Si source o sourceComponent cambian, cualquier elemento instanciado previamente es destruido. Establecer source a una cadena vacía o establecer sourceComponent a undefined destruye el objeto cargado actualmente, liberando recursos y dejando el Loader vacío.

Comportamiento del tamaño del cargador

Cuando se utiliza para cargar tipos visuales, Loader aplica las siguientes reglas de tamaño:

• Si no se especifica un tamaño explícito para el Loader, éste se redimensiona automáticamente al tamaño del elemento cargado una vez cargado el componente.
• Si el tamaño del cargador se especifica explícitamente estableciendo la anchura, la altura o anclándolo, el elemento cargado se redimensionará al tamaño del cargador.

En ambos casos, el tamaño del elemento y del cargador son idénticos. Esto garantiza que el anclaje al cargador es equivalente al anclaje al elemento cargado.

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 el componente de origen no es de tipo Item, Loader no aplica ninguna regla de tamaño especial.

Recepción de señales de objetos cargados

Cualquier señal emitida desde el objeto cargado puede ser recibida utilizando el tipo Connections. Por ejemplo, el siguiente application.qml carga MyItem.qml, y es capaz de recibir la señal message del elemento cargado a través de un objeto 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!")
   }
}

Foco y eventos clave

Loader es un focus scope. Su propiedad focus debe tener el valor true para que cualquiera de sus hijos obtenga el foco activo. (Ver Enfoque de Teclado en Qt Quick para más detalles.) Cualquier evento de tecla recibido en el elemento cargado debe probablemente también ser accepted para que no se propaguen al Loader.

Por ejemplo, el siguiente application.qml carga KeyReader.qml cuando se hace clic en MouseArea. Observe que la propiedad focus se establece en true tanto para el Loader como para Item en el objeto cargado dinámicamente:

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

Una vez cargado KeyReader.qml, acepta eventos de clave y establece event.accepted en true para que el evento no se propague al padre Rectangle.

Desde QtQuick 2.0, Loader también puede cargar componentes no visuales.

Utilización de un Loader dentro de un View Delegate

En algunos casos es posible que desee utilizar un Loader dentro de un delegado de vista para mejorar el rendimiento de carga del delegado. Esto funciona bien en la mayoría de los casos, pero hay una cuestión importante a tener en cuenta relacionada con el creation context de un Componente.

En el siguiente ejemplo, la propiedad de contexto index insertada por ListView en el contexto de delegateComponent será inaccesible para Text, ya que el cargador utilizará el contexto de creación de myComponent como contexto padre al instanciarlo, y index no hace referencia a nada dentro de esa cadena de contextos.

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

En esta situación podemos mover el componente inline,

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

en un archivo separado,

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

o establecer explícitamente la información requerida como una propiedad del cargador (esto funciona porque el cargador se establece a sí mismo como el objeto de contexto para el componente que está cargando).

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

Véase también Dynamic Object Creation.

Documentación de propiedades

active : bool

Esta propiedad es true si el cargador está actualmente activo. El valor por defecto de esta propiedad es true.

Si el cargador está inactivo, cambiar source o sourceComponent no causará que el ítem sea instanciado hasta que el cargador sea activado.

Establecer el valor a inactivo causará que cualquier item cargado por el cargador sea liberado, pero no afectará a source o sourceComponent.

El status de un cargador inactivo es siempre Null.

Véase también source y sourceComponent.

asynchronous : bool

Esta propiedad indica si el componente se instanciará de forma asíncrona. Por defecto es false.

Cuando se utiliza junto con la propiedad source, la carga y la compilación también se realizarán en un subproceso en segundo plano.

La carga asíncrona crea los objetos declarados por el componente a través de múltiples fotogramas, y reduce la probabilidad de fallos en la animación. Cuando se carga asíncronamente el estado cambiará a Loader.Loading. Una vez que se haya creado todo el componente, item estará disponible y el estado cambiará a Loader.Ready.

Si se cambia el valor de esta propiedad a false mientras se está realizando una carga asíncrona, se forzará la finalización inmediata y síncrona. Esto permite comenzar una carga asíncrona y luego forzar la finalización si se debe acceder al contenido del cargador antes de que la carga asíncrona haya finalizado.

Para evitar ver los elementos cargándose progresivamente establezca visible adecuadamente, por ejemplo

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

Tenga en cuenta que esta propiedad sólo afecta a la instanciación de objetos; no está relacionada con la carga asíncrona de un componente a través de una red.

item : QtObject [read-only]

Esta propiedad contiene el objeto de nivel superior que se carga actualmente.

Desde QtQuick 2.0, Loader puede cargar cualquier tipo de objeto.

progress : real [read-only]

Esta propiedad contiene el progreso de la carga de datos QML desde la red, de 0.0 (nada cargado) a 1.0 (finalizado). La mayoría de los archivos QML son bastante pequeños, por lo que este valor cambiará rápidamente de 0 a 1.

Véase también status.

source : url

Esta propiedad contiene la URL del componente QML a instanciar.

Desde QtQuick 2.0, Loader es capaz de cargar cualquier tipo de objeto; no está restringido a los tipos Item.

Para descargar el objeto cargado actualmente, establezca esta propiedad a una cadena vacía, o establezca sourceComponent a undefined. Establecer source a una nueva URL también causará que el elemento creado por la URL anterior sea descargado.

Ver también sourceComponent, status, y progress.

sourceComponent : Component

Esta propiedad contiene el Component a instanciar.

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

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

Para descargar el objeto cargado actualmente, establezca esta propiedad a undefined.

Desde QtQuick 2.0, Loader es capaz de cargar cualquier tipo de objeto; no está restringido a los tipos Item.

Ver también source y progress.

status : enumeration [read-only]

Esta propiedad contiene el estado de carga de QML. Puede ser uno de los siguientes:

• Loader.Null - el cargador está inactivo o no se ha establecido ninguna fuente QML.
• Loader.Ready - la fuente QML ha sido cargada
• Loader.Loading - la fuente QML se está cargando actualmente
• Loader.Error - se ha producido un error al cargar la fuente QML

Utilice este estado para proporcionar una actualización o responder al cambio de estado de alguna manera. Por ejemplo, podría

• Activar un cambio de estado:

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

• Implementar un manejador de señales onStatusChanged:

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

• Vincular al valor de estado:

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

Tenga en cuenta que si la fuente es un archivo local, el estado será inicialmente Ready (o Error). Aunque en ese caso no habrá señal onStatusChanged, se invocará onLoaded.

Véase también progress.

Documentación de señales

loaded()

Esta señal se emite cuando status se convierte en Loader.Ready, o en caso de carga inicial correcta.

Documentación del método

object setSource(url source, object properties)

Crea una instancia de objeto del componente source dado que tendrá el properties dado. El argumento properties es opcional. Se podrá acceder a la instancia a través de la propiedad item una vez que se haya completado la carga y la instanciación.

Si la propiedad active es false en el momento en que se llama a esta función, el componente source dado no se cargará, pero el source y el properties inicial se almacenarán en caché. Cuando el cargador se haga active, se creará una instancia del componente source con el properties inicial establecido.

El establecimiento de los valores iniciales de las propiedades de una instancia de un componente de esta manera no activará ningún Behaviors asociado.

Tenga en cuenta que la caché properties se borrará si se cambia source o sourceComponent después de llamar a esta función pero antes de establecer el cargador active.

Ejemplo:

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

Véase también source y active.