Loader QML Type
Permite la carga dinámica de un subárbol desde una URL o un componente. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- active : bool
- asynchronous : bool
- item : QtObject
- progress : real
- source : url
- sourceComponent : Component
- status : enumeration
Señales
- loaded()
Métodos
- void setSource(url source, var properties)
Descripción detallada
Loader se utiliza para cargar dinámicamente componentes QML.
El Loader puede cargar un archivo QML (mediante la propiedad source ) o un objeto Component (mediante la propiedad sourceComponent ). Resulta útil para retrasar la creación de un componente hasta que sea necesario: por ejemplo, cuando un componente debe crearse bajo demanda, o cuando no conviene crearlo innecesariamente por motivos de rendimiento.
A continuación se muestra un Loader que carga «Page1.qml» como componente al hacer clic en el 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 cambia « source » o « sourceComponent », se destruyen todos los elementos instanciados previamente. Al establecer « source » en una cadena vacía o « sourceComponent » en « undefined », se destruye el objeto cargado actualmente, lo que libera recursos y deja el Loader vacío.
Comportamiento del Loader en cuanto al tamaño
Cuando se utiliza para cargar tipos visuales, el Loader aplica las siguientes reglas de redimensionamiento:
- Si no se especifica un tamaño explícito para el Loader, este se redimensiona automáticamente al tamaño del elemento cargado una vez que se ha cargado el componente.
- Si el tamaño del Loader se especifica explícitamente estableciendo el ancho, la altura o mediante anclaje, el elemento cargado se redimensionará al tamaño del Loader.
En ambos casos, el tamaño del elemento y del Loader son idénticos. Esto garantiza que el anclaje al Loader sea equivalente al anclaje al elemento cargado.
| sizeloader.qml | sizeitem.qml |
| El rectángulo rojo se ajustará al tamaño del elemento raíz. | El rectángulo rojo tendrá un tamaño de 50x50 y estará centrado en el elemento raíz. |
Si el componente de origen no es de tipo «Item», el «Loader» no aplica ninguna regla especial de dimensionamiento.
Recepción de señales de objetos cargados
Cualquier señal emitida por el objeto cargado se puede recibir 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 »:
| application.qml | MyItem.qml |
|
Eventos de foco y de teclas
Loader es un ámbito de foco. Su propiedad focus debe establecerse en true para que cualquiera de sus elementos hijos pueda obtener el foco activo. (Consulte «Foco del teclado» en Qt Quick para obtener más detalles). Es probable que cualquier evento de tecla recibido en el elemento cargado también deba ser accepted para que no se propague al Loader.
Por ejemplo, el siguiente application.qml carga KeyReader.qml al hacer clic en MouseArea. Obsérvese que la propiedad focus está establecida en true tanto para el Loader como para el Item del objeto cargado dinámicamente:
| application.qml | KeyReader.qml |
Una vez cargado KeyReader.qml, este acepta eventos de teclas y establece event.accepted en true para que el evento no se propague al Rectangle padre.
Dado que QtQuick 2.0, Loader también puede cargar componentes no visuales.
Uso de un Loader dentro de un delegado de vista
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 un aspecto importante que debe tenerse en cuenta en relación con el creation context de un componente.
En el siguiente ejemplo, la propiedad de contexto ` index ` insertada por ` ListView ` en el contexto de ` delegateComponent` no será accesible para `Text`, ya que el `Loader` 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 contexto.
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 para que quede en línea,
a un archivo independiente,
o establecer explícitamente la información necesaria como una propiedad del Loader (esto funciona porque el Loader 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 sobre propiedades
active : bool
Esta propiedad es de tipo « true » si el Loader está activo en ese momento. El valor por defecto de esta propiedad es « true ».
Si el Loader está inactivo, cambiar el valor de « source » o « sourceComponent » no provocará que el elemento se instancie hasta que el Loader se active.
Establecer el valor en «inactive» provocará que cualquier item cargado por el cargador se libere, pero no afectará a source ni a sourceComponent.
El status de un cargador inactivo es siempre Null.
Véase también « source » y « sourceComponent ».
asynchronous : bool
Esta propiedad determina si el componente se instanciará de forma asíncrona. Por defecto, su valor es « false ».
Cuando se utiliza junto con la propiedad « source », la carga y la compilación también se realizarán en un hilo en segundo plano.
La carga asíncrona crea los objetos declarados por el componente a lo largo de varios fotogramas y reduce la probabilidad de que se produzcan fallos en la animación. Al cargar de forma asíncrona, el estado cambiará a «Loader.Loading». Una vez que se haya creado todo el componente, el « 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 iniciar una carga asíncrona y, a continuación, forzar su finalización si es necesario acceder al contenido del Loader antes de que la carga asíncrona haya finalizado.
Para evitar que se vean los elementos cargándose progresivamente, configura « visible » adecuadamente, por ejemplo:
Loader {
source: "mycomponent.qml"
asynchronous: true
visible: status == Loader.Ready
}Ten en cuenta que esta propiedad solo afecta a la instanciación de objetos; no tiene nada que ver 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 está cargado actualmente.
Desde la versión QtQuick 2.0, Loader puede cargar cualquier tipo de objeto.
progress : real [read-only]
Esta propiedad indica el progreso de la carga de datos QML desde la red, desde 0,0 (no se ha cargado nada) hasta 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 que se va a instanciar.
Desde la versión QtQuick 2.0, Loader es capaz de cargar cualquier tipo de objeto; no se limita a los tipos Item.
Para descargar el objeto cargado actualmente, establece esta propiedad en una cadena vacía o establece sourceComponent en undefined. Establecer source en una nueva URL también provocará que se descargue el elemento creado por la URL anterior.
Véase también sourceComponent, status y progress.
sourceComponent : Component
Esta propiedad contiene el objeto ` Component ` que se va 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, establece esta propiedad en ` undefined`.
Dado que QtQuick 2.0, Loader es capaz de cargar cualquier tipo de objeto; no se limita a los tipos de elemento.
Véase también « source » y « progress ».
status : enumeration [read-only]
Esta propiedad indica el estado de la carga de QML. Puede adoptar uno de los siguientes valores:
- Loader.Null: el cargador está inactivo o no se ha establecido ninguna fuente QML
- Loader.Ready: el código fuente QML se ha cargado
- Loader.Loading: el código fuente QML se está cargando en este momento
- Loader.Error: se ha producido un error al cargar el código fuente QML
Utiliza este estado para proporcionar una actualización o responder de alguna forma al cambio de estado. Por ejemplo, podrías:
- Desencadenar un cambio de estado:
State { name: 'loaded'; when: loader.status == Loader.Ready } - Implementar un controlador de señal «
onStatusChanged»:Loader { id: loader onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded') } - Vincularse al valor del estado:
Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' }
Ten en cuenta que, si la fuente es un archivo local, el estado será inicialmente «Ready» (o «Error»). Aunque en ese caso no habrá una señal onStatusChanged, la señal onLoaded se seguirá invocando.
Véase también progress.
Documentación sobre señales
loaded()
Esta señal se emite cuando la propiedad « status » pasa a tener el valor « Loader.Ready », o bien al completarse con éxito la carga inicial.
Nota: El controlador correspondiente es onLoaded.
Documentación del método
void setSource(url source, var properties)
Crea una instancia del componente « source » especificado que tendrá el « properties » indicado. 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 especificado no se cargará, pero se almacenarán en caché la propiedad source y el valor inicial properties. Cuando el cargador se establece en active, se creará una instancia del componente source con el valor inicial properties establecido.
Establecer los valores iniciales de las propiedades de una instancia de un componente de esta manera no activará ningún Behaviorasociado.
Ten en cuenta que la caché de properties se borrará si se modifica el source o el sourceComponent después de llamar a esta función, pero antes de configurar el cargador active.
Ejemplo:
|
© 2026 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.