Loader3D QML Type
Permite la carga dinámica de un subárbol 3D desde una URL o un componente. Más...
| Import Statement: | import QtQuick3D |
| Inherits: |
Propiedades
- active : bool
- asynchronous : bool
- item : object
- progress : real
- source : url
- sourceComponent : Component
- status : enumeration
Señales
- loaded()
Métodos
- object setSource(url source, object properties)
Descripción detallada
Loader3D se utiliza para cargar dinámicamente componentes QML para Qt Quick 3D.
Loader3D 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.
Nota: Loader3D funciona de la misma manera que Loader. La diferencia entre ambos es que Loader permite cargar dinámicamente objetos que heredan de Item, mientras que Loader3D permite cargar objetos que heredan de Object3D y forman parte de una escena 3D.
Documentación de propiedades
active : bool
Esta propiedad es « true » si « Loader3D » está activo actualmente. El valor por defecto de esta propiedad es « true ».
Si el Loader3D está inactivo, cambiar el source o el sourceComponent no provocará que el elemento se instancie hasta que el Loader3D 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 « Loader3D.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 de « Loader3D » antes de que la carga asíncrona haya finalizado.
Para evitar que se vean los elementos cargándose progresivamente, configura visible adecuadamente, p. ej.
Loader3D {
source: "mycomponent.qml"
asynchronous: true
visible: status == Loader3D.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 : object [read-only]
Esta propiedad contiene el objeto de nivel superior que está cargado actualmente.
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 (finalizada). La mayoría de los archivos QML son bastante pequeños, por lo que este valor pasará 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.
Para descargar el objeto cargado actualmente, establece esta propiedad en una cadena vacía, o cambia sourceComponent a undefined. Al establecer source en una nueva URL, también se descargará el elemento creado por la URL anterior.
Véanse también « sourceComponent », « status » y « progress ».
sourceComponent : Component
Esta propiedad contiene el objeto ` Component ` que se va a instanciar.
Item {
Component {
id: redCube
Model {
source: "#Cube"
materials: DefaultMaterial {
diffuseColor: "red"
}
}
}
Loader3D { sourceComponent: redCube }
Loader3D { sourceComponent: redCube; x: 10 }
}Para descargar el objeto cargado actualmente, establece esta propiedad en « undefined ».
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:
| Constante | Descripción |
|---|---|
Loader3D.Null | El cargador está inactivo o no se ha establecido ninguna fuente QML. |
Loader3D.Ready | Se ha cargado el código fuente QML. |
Loader3D.Loading | El código fuente QML se está cargando actualmente. |
Loader3D.Error | Se ha producido un error al cargar el código fuente QML. |
Utiliza este estado para proporcionar una actualización o responder al cambio de estado de alguna manera. Por ejemplo, podrías:
- Disparar un cambio de estado:
State { name: 'loaded'; when: loader.status == Loader3D.Ready } - Implementar un gestor de señales de tipo «
onStatusChanged»:Loader3D { id: loader onStatusChanged: if (loader.status == Loader3D.Ready) console.log('Loaded') } - Vincularse al valor del estado:
Text { text: loader.status == Loader3D.Ready ? 'Loaded' : 'Not loaded' }
Ten en cuenta que, si la fuente es un archivo local, el estado inicial será «Ready» (o «Error»). Aunque en ese caso no habrá ninguna señal onStatusChanged, la señal onLoaded se invocará de todos modos.
Véase también progress.
Documentación de señales
loaded()
Esta señal se emite cuando status pasa a ser Loader3D.Ready, o al completarse con éxito la carga inicial.
El controlador correspondiente es onLoaded.
Nota: El controlador correspondiente es onLoaded.
Documentación del método
object setSource(url source, object 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é los valores source y properties iniciales. 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.
Tenga en cuenta que el properties almacenado en caché se borrará si se modifica el source o el sourceComponent después de llamar a esta función, pero antes de establecer el cargador active.
© 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.