En esta página

QQmlIncubator Class

La clase QQmlIncubator permite crear objetos QML de forma asíncrona. Más información...

Encabezado: #include <QQmlIncubator>
CMake: find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml

Tipos públicos

enum IncubationMode { Asynchronous, AsynchronousIfNested, Synchronous }
enum Status { Null, Ready, Loading, Error }

Funciones públicas

QQmlIncubator(QQmlIncubator::IncubationMode mode = Asynchronous)
void clear()
QList<QQmlError> errors() const
void forceCompletion()
QQmlIncubator::IncubationMode incubationMode() const
bool isError() const
bool isLoading() const
bool isNull() const
bool isReady() const
QObject *object() const
void setInitialProperties(const QVariantMap &initialProperties)
QQmlIncubator::Status status() const

Funciones protegidas

virtual void setInitialState(QObject *object)
virtual void statusChanged(QQmlIncubator::Status status)

Descripción detallada

La creación de objetos QML —como delegados en una vista o una nueva página en una aplicación— puede llevar bastante tiempo, especialmente en dispositivos móviles con recursos limitados. Cuando una aplicación utiliza directamente ` QQmlComponent::create()``, la instancia del objeto QML se crea de forma sincrónica, lo que, dependiendo de la complejidad del objeto, puede provocar pausas o tirones perceptibles en la aplicación.

El uso de `QQmlIncubator` ofrece un mayor control sobre la creación de un objeto QML, lo que incluye la posibilidad de crearlo de forma asíncrona aprovechando el tiempo de inactividad de la aplicación. El siguiente ejemplo muestra un uso sencillo de `QQmlIncubator`.

// Initialize the incubator
QQmlIncubator incubator;
component->create(incubator);

Deja que el incubador se ejecute durante un rato (normalmente devolviendo el control al bucle de eventos) y, a continuación, consulta su estado. Hay varias formas de volver al incubador más tarde. Quizás quieras conectarte a una de las señales enviadas por ` QQuickWindow`, o quizá prefieras ejecutar un ` QTimer ` específicamente para ello. También es posible que necesites el objeto para algún fin específico y que consultes la incubadora cuando surja esa necesidad.

// Poll the incubator
if (incubator.isReady()) {
    QObject *object = incubator.object();
    // Use created object
}

Las incubadoras asíncronas se controlan mediante un ` QQmlIncubationController ` que se establece en el ` QQmlEngine`, lo que permite al motor saber cuándo la aplicación está inactiva y deben procesarse los objetos en incubación. Si no se ha establecido un controlador de incubación en el ` QQmlEngine`, ` QQmlIncubator ` crea objetos de forma sincrónica, independientemente del ` IncubationMode` especificado. Por defecto, no hay ningún controlador de incubación establecido. Sin embargo, ` QQuickView`, ` QQuickWindow ` y ` QQuickWidget ` establecen controladores de incubación en sus respectivos ` QQmlEngine`. Estos controladores de incubación distribuyen las incubaciones a lo largo de varios fotogramas mientras se renderiza la vista.

QQmlIncubator admite tres modos de incubación:

  • Sincrónico: La creación se produce de forma sincrónica. Es decir, una vez que la llamada a ` QQmlComponent::create()` devuelve un resultado, el controlador de incubación ya se encontrará en el estado «Error» o «Ready». Un incubador síncrono no ofrece ninguna ventaja real en comparación con el uso directo de los métodos de creación síncrona en QQmlComponent, pero puede simplificar la implementación de una aplicación al utilizar la misma API tanto para creaciones síncronas como asíncronas.
  • Asíncrono (por defecto) La creación se produce de forma asíncrona, siempre que se haya establecido un `QQmlIncubatorController` en ` QQmlEngine`.

    La incubadora permanecerá en el estado «Loading» hasta que se complete la creación o se produzca un error. Se puede utilizar la llamada de retorno de statusChanged() para recibir notificaciones sobre los cambios de estado.

    Las aplicaciones deben utilizar el modo de incubación asíncrono para crear objetos que no se necesiten de forma inmediata. Por ejemplo, el tipo ` ListView ` utiliza la incubación asíncrona para crear objetos que se encuentran ligeramente fuera de la pantalla mientras se desplaza la lista. Si, durante la creación asíncrona, se necesita el objeto de forma inmediata, se puede llamar al método ` QQmlIncubator::forceCompletion()` para completar el proceso de creación de forma síncrona.

  • AsynchronousIfNested La creación se producirá de forma asíncrona si forma parte de una creación asíncrona anidada, o de forma síncrona en caso contrario.

    En la mayoría de los casos en los que un componente QML desee que parezca que la instanciación es sincrónica, debería utilizar este modo.

    Este modo se explica mejor con un ejemplo. Cuando se crea por primera vez el tipo « ListView », necesita rellenarse con un conjunto inicial de delegados que mostrar. Si el ListView tuviera 400 píxeles de altura y cada delegado tuviera 100 píxeles de altura, tendría que crear cuatro instancias iniciales de delegados. Si el ListView utilizara el modo de incubación asíncrono, el ListView siempre se crearía vacío y, más tarde, aparecerían los cuatro elementos iniciales.

    Por el contrario, si el ListView utilizara el modo de incubación síncrono, se comportaría correctamente, pero podría provocar tirones en la aplicación. Dado que QML tendría que detenerse e instanciar de forma síncrona los delegados de ListView, si ListView formara parte de un componente QML que se estuviera instanciando de forma asíncrona, esto anularía gran parte de las ventajas de la instanciación asíncrona.

    El modo « AsynchronousIfNested » resuelve este problema. Al utilizar ` AsynchronousIfNested`, los delegados de ` ListView ` se instancian de forma asíncrona si el propio ` ListView ` ya forma parte de una instanciación asíncrona, y de forma síncrona en caso contrario. En el caso de una instanciación asíncrona anidada, la instanciación asíncrona exterior no se completará hasta que también se hayan completado todas las instanciaciones anidadas. Esto garantiza que, cuando se complete la instanciación asíncrona exterior, los elementos internos como ListView ya hayan terminado de cargar sus delegados iniciales.

    Casi siempre es incorrecto utilizar el modo de incubación «Synchronous»: los elementos o componentes que deseen dar la apariencia de una instanciación sincrónica, pero sin los inconvenientes de provocar bloqueos o tirones en la aplicación, deben utilizar el modo de incubación « AsynchronousIfNested ».

Documentación sobre tipos de miembro

enum QQmlIncubator::IncubationMode

Especifica el modo en el que funciona la incubadora. Independientemente del modo de incubación, un ` QQmlIncubator ` se comportará de forma sincrónica si el ` QQmlEngine ` no tiene un ` QQmlIncubationController ` establecido.

ConstanteValorDescripción
QQmlIncubator::Asynchronous0El objeto se creará de forma asíncrona.
QQmlIncubator::AsynchronousIfNested1Si el objeto se está creando en un contexto que ya forma parte de una creación asíncrona, esta incubadora se unirá a esa incubación existente y se ejecutará de forma asíncrona. La incubación existente no pasará al estado «Listo» hasta que tanto ella como esta incubación se hayan completado. En caso contrario, la incubación se ejecutará de forma sincrónica.
QQmlIncubator::Synchronous2El objeto se creará de forma sincrónica.

enum QQmlIncubator::Status

Especifica el estado de la aplicación « QQmlIncubator ».

ConstanteValorDescripción
QQmlIncubator::Null0La incubación no está en curso. Llama a QQmlComponent::create() para iniciar la incubación.
QQmlIncubator::Ready1El objeto se ha creado por completo y se puede acceder a él llamando a object().
QQmlIncubator::Loading2El objeto se está creando.
QQmlIncubator::Error3Se ha producido un error. Se puede acceder a los errores llamando a errors().

Documentación de las funciones de miembro

QQmlIncubator::QQmlIncubator(QQmlIncubator::IncubationMode mode = Asynchronous)

Crear una nueva incubadora con los datos especificados mode

void QQmlIncubator::clear()

Borra el contenido de la incubadora. Se interrumpen todas las incubaciones en curso. Si la incubadora se encuentra en estado «Listo», el objeto creado no se elimina.

QList<QQmlError> QQmlIncubator::errors() const

Devuelve la lista de errores que se han producido durante la incubación del objeto.

void QQmlIncubator::forceCompletion()

Forza que cualquier incubación en curso finalice de forma sincrónica. Una vez que esta llamada devuelva un resultado, el incubador ya no se encontrará en el estado «Cargando».

QQmlIncubator::IncubationMode QQmlIncubator::incubationMode() const

Devuelve el modo de incubación pasado al constructor de ` QQmlIncubator `.

bool QQmlIncubator::isError() const

Devuelve «true» si el método ` status()` de la incubadora devuelve un error.

bool QQmlIncubator::isLoading() const

Devuelve «true» si el método ` status()` de la incubadora tiene el estado «Loading».

bool QQmlIncubator::isNull() const

Devuelve «true» si el método ` status()` de la incubadora es `Null`.

bool QQmlIncubator::isReady() const

Devuelve «true» si el método ` status()` de la incubadora está listo.

QObject *QQmlIncubator::object() const

Devuelve el objeto incubado si el estado es «Listo»; en caso contrario, devuelve 0.

void QQmlIncubator::setInitialProperties(const QVariantMap &initialProperties)

Almacena una correspondencia entre los nombres de las propiedades y los valores iniciales, que se encuentran en initialProperties, con los que se inicializará el componente incubado.

Véase también QQmlComponent::setInitialProperties.

[virtual protected] void QQmlIncubator::setInitialState(QObject *object)

Se invoca una vez creado el objeto « object », pero antes de que se evalúen los enlaces de propiedades complejas y, si procede, de que se llame a ` QQmlParserStatus::componentComplete()`. Esto equivale al momento comprendido entre ` QQmlComponent::beginCreate()` y ` QQmlComponent::completeCreate()`, y puede utilizarse para asignar valores iniciales a las propiedades del objeto.

La implementación por defecto no realiza ninguna acción.

Nota: Los enlacessimples , como los literales numéricos, se evalúan antes de que se llame a `setInitialState()`. La clasificación de los enlaces en simples y complejos no se especifica intencionadamente y puede variar entre versiones de Qt y dependiendo de si se utiliza qmlcachegen y de cómo se haga. No debes dar por sentado que ningún enlace concreto se evaluará antes o después de que se llame a setInitialState(). Por ejemplo, una expresión constante como MyType.EnumValue puede reconocerse como tal en tiempo de compilación o posponerse para ejecutarse como enlace. Lo mismo ocurre con expresiones constantes como -(5) o «a» + «cadena constante».

QQmlIncubator::Status QQmlIncubator::status() const

Devuelve el estado actual de la incubadora.

[virtual protected] void QQmlIncubator::statusChanged(QQmlIncubator::Status status)

Se invoca cuando cambia el estado de la incubadora. ` status ` es el nuevo estado.

La implementación predeterminada no realiza ninguna acción.

© 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.