En esta página

QQmlComponent Class

La clase QQmlComponent encapsula la definición de un componente QML. Más información...

Encabezado: #include <QQmlComponent>
CMake: find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
En QML: Component
Heredan de: QObject

Tipos públicos

enum CompilationMode { PreferSynchronous, Asynchronous }
enum Status { Null, Ready, Loading, Error }

Propiedades

Funciones públicas

QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)
QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)
QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)
QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)
QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)
(since 6.5) QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)
(since 6.5) QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)
virtual ~QQmlComponent() override
virtual QObject *beginCreate(QQmlContext *context)
virtual void completeCreate()
virtual QObject *create(QQmlContext *context = nullptr)
void create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)
QObject *createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)
QQmlContext *creationContext() const
QQmlEngine *engine() const
QList<QQmlError> errors() const
(since 6.5) bool isBound() const
bool isError() const
bool isLoading() const
bool isNull() const
bool isReady() const
qreal progress() const
void setInitialProperties(QObject *object, const QVariantMap &properties)
QQmlComponent::Status status() const
QUrl url() const

Ranuras públicas

(since 6.5) void loadFromModule(QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode = PreferSynchronous)
void loadUrl(const QUrl &url)
void loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)
void setData(const QByteArray &data, const QUrl &url)

Señales

void progressChanged(qreal progress)
void statusChanged(QQmlComponent::Status status)

Descripción detallada

Los componentes son tipos QML reutilizables y encapsulados con interfaces bien definidas.

Se puede crear una instancia de `QQmlComponent` a partir de un archivo QML. Por ejemplo, si hay un archivo ` main.qml ` como este:

import QtQuick 2.0

Item {
    width: 200
    height: 200
}

El siguiente código carga este archivo QML como un componente, crea una instancia de este componente utilizando create() y, a continuación, consulta el valor width de Item:

QQmlEngine*engine = new QQmlEngine;
QQmlComponent component(engine, QUrl::fromLocalFile("main.qml"));
if (component.isError()) {
    qWarning() << "Failed to load main.qml:" << component.errors();
   return 1;
}

QObject*myObject = component.create();
if (component.isError()) {
    qWarning() << "Failed to create instance of main.qml:" << component.errors();
   return 1;
}

QQuickItem*item = qobject_cast<QQuickItem*>(myObject);
int width = item->width();  // width = 200

Para crear instancias de un componente en código donde no hay una instanci QQmlEngine, puedes utilizar qmlContext() o qmlEngine(). Por ejemplo, en el siguiente escenario, se están creando elementos secundarios dentro de una subclase de QQuickItem:

void MyCppItem::init()
{
    QQmlEngine *engine = qmlEngine(this);
    // Or:
    // QQmlEngine *engine = qmlContext(this)->engine();
    QQmlComponent component(engine, QUrl::fromLocalFile("MyItem.qml"));
    QQuickItem *childItem = qobject_cast<QQuickItem*>(component.create());
    childItem->setParentItem(this);
}

Ten en cuenta que estas funciones devolverán ` null ` cuando se invoquen dentro del constructor de una subclase de ` QObject `, ya que la instancia aún no tendrá ni contexto ni motor.

Componentes de red

Si la URL pasada a `QQmlComponent` es un recurso de red, o si el documento QML hace referencia a un recurso de red, el `QQmlComponent` tiene que recuperar los datos de red antes de poder crear objetos. En este caso, el `QQmlComponent` tendrá un ` Loading ` ` status`. Una aplicación tendrá que esperar hasta que el componente esté ` Ready ` antes de llamar a ` QQmlComponent::create()`.

El siguiente ejemplo muestra cómo cargar un archivo QML desde un recurso de red. Tras crear el QQmlComponent, comprueba si el componente se está cargando. Si es así, se conecta a la señal QQmlComponent::statusChanged() y, en caso contrario, llama directamente al método continueLoading(). Ten en cuenta que QQmlComponent::isLoading() puede ser «false» para un componente de red si este se ha almacenado en caché y está listo de inmediato.

MyApplication::MyApplication()
{
    // ...
    component = new QQmlComponent(engine, QUrl("http://www.example.com/main.qml"));
    if (component->isLoading()) {
        QObject::connect(component, &QQmlComponent::statusChanged,
                         this, &MyApplication::continueLoading);
    } else {
        continueLoading();
    }
}

void MyApplication::continueLoading()
{
    if (component->isError()) {
        qWarning() << component->errors();
    } else {
        QObject*myObject = component->create();
    }
}

Documentación sobre tipos de miembros

enum QQmlComponent::CompilationMode

Especifica si el ` QQmlComponent ` debe cargar el componente de forma inmediata o asíncrona.

ConstanteValorDescripción
QQmlComponent::PreferSynchronous0Prefiere cargar/compilar el componente de forma inmediata, bloqueando el hilo. Esto no siempre es posible; por ejemplo, las URL remotas siempre se cargarán de forma asíncrona.
QQmlComponent::Asynchronous1Carga o compila el componente en un hilo en segundo plano.

enum QQmlComponent::Status

Especifica el estado de carga de QQmlComponent.

ConstanteValorDescripción
QQmlComponent::Null0Este QQmlComponent no tiene datos. Llama a loadUrl() o a setData() para añadir contenido QML.
QQmlComponent::Ready1Este « QQmlComponent » está listo y se puede llamar a « create()».
QQmlComponent::Loading2Este QQmlComponent está cargando datos de red.
QQmlComponent::Error3Se ha producido un error. Llama a ` errors()` para recuperar una lista de ` errors`.

Documentación de la propiedad

[read-only] progress : qreal

El progreso de la carga del componente, desde 0,0 (sin nada cargado) hasta 1,0 (finalizado).

Funciones de acceso:

qreal progress() const

Señal de notificación:

void progressChanged(qreal progress)

[read-only] status : Status

status e actual del componente.

Funciones de acceso:

QQmlComponent::Status status() const

Señal de notificación:

void statusChanged(QQmlComponent::Status status)

[read-only] url : const QUrl

La URL del componente. Se trata de la URL que se pasa al constructor o a los métodos ` loadUrl()` o ` setData()`.

Funciones de acceso:

QUrl url() const

Documentación de las funciones miembro

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

Crea un QQmlComponent sin datos y asígnale los valores especificados en « engine » y « parent ». Establece los datos con « setData()».

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

Crea un QQmlComponent a partir del ` fileName ` proporcionado y asígnale el ` parent ` y el ` engine` especificados.

Véase también loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

Crea un QQmlComponent a partir del url proporcionado y asígnale los valores especificados de parent y engine.

Asegúrate de que la URL proporcionada sea completa y correcta; en particular, utiliza QUrl::fromLocalFile() al cargar un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán con respecto a QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique lo contrario.

Véase también loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Crea un QQmlComponent a partir del fileName proporcionado y asígnale los valores especificados para parent y engine. Si mode es Asynchronous, el componente se cargará y compilará de forma asíncrona.

Véase también loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Crea un QQmlComponent a partir de la URL proporcionada ( url ) y asígnale los valores especificados para parent y engine. Si mode es Asynchronous, el componente se cargará y compilará de forma asíncrona.

Asegúrate de que la URL proporcionada sea completa y correcta; en particular, utiliza QUrl::fromLocalFile() al cargar un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán con respecto a QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique lo contrario.

Véase también ` loadUrl()`.

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)

Crea un QQmlComponent a partir de los valores proporcionados en « uri » y « typeName », y asígnale los valores especificados en « parent » y « engine ». Si es posible, el componente se cargará de forma sincrónica.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.5.

Véase también loadFromModule().

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Crea un QQmlComponent a partir de los valores proporcionados en ` uri ` y ` typeName `, y asígnale los valores especificados en ` parent ` y ` engine`. Si ` mode ` es ` Asynchronous`, el componente se cargará y compilará de forma asíncrona.

Se trata de una función sobrecargada.

Esta función se introdujo en Qt 6.5.

Véase también loadFromModule().

[override virtual noexcept] QQmlComponent::~QQmlComponent()

Destruye el « QQmlComponent ».

[virtual] QObject *QQmlComponent::beginCreate(QQmlContext *context)

Crea una instancia de objeto a partir de este componente, dentro del ámbito especificado context. Devuelve nullptr si la creación ha fallado.

Nota: Este método ofrece un control avanzado sobre la creación de instancias del componente. En general, los programadores deben utilizar QQmlComponent::create() para crear instancias de objetos.

Cuando QQmlComponent construye una instancia, el proceso se lleva a cabo en tres pasos:

  1. Se crea la jerarquía de objetos y se asignan los valores constantes.
  2. Se evalúan por primera vez los enlaces de propiedades.
  3. Si procede, se llama a ` QQmlParserStatus::componentComplete()` en los objetos.

`QQmlComponent::beginCreate()` se diferencia de ` QQmlComponent::create()` en que solo lleva a cabo el paso 1. Se debe llamar a ` QQmlComponent::completeCreate()` para completar los pasos 2 y 3.

Este punto de interrupción resulta útil en ocasiones al utilizar propiedades adjuntas para comunicar información a un componente instanciado, ya que permite configurar sus valores iniciales antes de que las vinculaciones de propiedades surtan efecto.

La propiedad de la instancia del objeto devuelta se transfiere al llamante.

Nota: La clasificación de los enlaces en valores constantes y enlaces reales no está especificada intencionadamente y puede variar entre versiones de Qt y dependiendo de si se utiliza qmlcachegen y de cómo se haga. No se debe dar por sentado que ningún enlace concreto se evalúe antes o después de que beginCreate() devuelva un valor. Por ejemplo, una expresión constante como MyType.EnumValue puede reconocerse como tal en tiempo de compilación o aplazarse para ejecutarse como enlace. Lo mismo ocurre con expresiones constantes como -(5) o «a» + «cadena constante».

Véase también completeCreate() y QQmlEngine::ObjectOwnership.

[virtual] void QQmlComponent::completeCreate()

Este método ofrece un control avanzado sobre la creación de instancias de componentes. En general, los programadores deben utilizar ` QQmlComponent::create()` para crear un componente.

Esta función completa la creación del componente iniciada con ` QQmlComponent::beginCreate()` y debe llamarse a continuación.

Véase también beginCreate().

[virtual] QObject *QQmlComponent::create(QQmlContext *context = nullptr)

Crea una instancia de objeto a partir de este componente, dentro de la ruta especificada context. Devuelve nullptr si la creación ha fallado.

Si context es nullptr (valor por defecto), creará la instancia en el root context del motor.

La propiedad de la instancia del objeto devuelta se transfiere al llamante.

Si el objeto que se crea a partir de este componente es un elemento visual, debe tener un padre visual, que se puede establecer llamando a QQuickItem::setParentItem(). Consulte «Conceptos - Padre visual» en Qt Quick para obtener más detalles.

Véase también QQmlEngine::ObjectOwnership.

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

Crea una instancia de objeto a partir de este componente utilizando el parámetro ` incubator` proporcionado. ` context ` especifica el contexto en el que se creará la instancia de objeto.

Si context es nullptr (el valor por defecto), creará la instancia en el root context del motor.

forContext Especifica un contexto del que depende la creación de este objeto. Si el ` forContext ` se está creando de forma asíncrona y el ` QQmlIncubator::IncubationMode ` es ` QQmlIncubator::AsynchronousIfNested`, este objeto también se creará de forma asíncrona. Si ` forContext ` es ` nullptr ` (por defecto), se utilizará el ` context ` para tomar esta decisión.

El objeto creado y su estado de creación están disponibles a través de incubator.

Véase también QQmlIncubator.

QObject *QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

Crea una instancia de este componente, dentro del context especificado, e inicializa sus propiedades de nivel superior con initialProperties.

Si no se puede establecer alguno de los valores de ` initialProperties `, se emite una advertencia. Si hay propiedades obligatorias sin establecer, la creación del objeto falla y devuelve ` nullptr`; en ese caso, ` isError()` devolverá ` true`.

Si context es nullptr (el valor por defecto), se creará la instancia en el root context del motor.

La propiedad de la instancia del objeto devuelta se transfiere al llamante.

Véase también QQmlComponent::create.

QQmlContext *QQmlComponent::creationContext() const

Devuelve el ` QQmlContext ` en el que se creó el componente. Esto solo es válido para componentes creados directamente desde QML.

QQmlEngine *QQmlComponent::engine() const

Devuelve el ` QQmlEngine ` de este componente.

QList<QQmlError> QQmlComponent::errors() const

Devuelve la lista de errores que se produjeron durante la última operación de compilación o creación. Se devuelve una lista vacía si no se ha establecido ` isError()`.

[since 6.5] bool QQmlComponent::isBound() const

Devuelve «true» si el componente se ha creado en un archivo QML que especifica ` pragma ComponentBehavior: Bound`; en caso contrario, devuelve «false».

Esta función se introdujo en Qt 6.5.

bool QQmlComponent::isError() const

Devuelve «true» si ` status()` == ` QQmlComponent::Error`.

bool QQmlComponent::isLoading() const

Devuelve «true» si ` status()` == ` QQmlComponent::Loading`.

bool QQmlComponent::isNull() const

Devuelve «true» si ` status()` == ` QQmlComponent::Null`.

bool QQmlComponent::isReady() const

Devuelve «true» si status() == QQmlComponent::Ready.

[slot, since 6.5] void QQmlComponent::loadFromModule(QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode = PreferSynchronous)

Carga el « QQmlComponent » para « typeName » en el módulo « uri ». Si el tipo se implementa mediante un archivo QML, se utiliza « mode » para cargarlo. Los tipos basados en C++ siempre se cargan de forma sincrónica.

QQmlEngine engine;
QQmlComponent component(&engine);
component.loadFromModule("QtQuick", "Item");
// once the component is ready
std::unique_ptr<QObject> item(component.create());
Q_ASSERT(item->metaObject() == &QQuickItem::staticMetaObject);

Esta función se introdujo en Qt 6.5.

Véase también loadUrl().

[slot] void QQmlComponent::loadUrl(const QUrl &url)

Carga el archivo « QQmlComponent » desde la dirección proporcionada: url.

Asegúrate de que la URL proporcionada sea completa y correcta; en particular, utiliza QUrl::fromLocalFile() al cargar un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán con respecto a QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique lo contrario.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url) { receiver->loadUrl(url); });
Para ver más ejemplos y enfoques, consulta «Conexión a ranuras sobrecargadas».

[slot] void QQmlComponent::loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)

Carga el ` QQmlComponent ` desde la URL proporcionada: url. Si mode es Asynchronous, el componente se cargará y compilará de forma asíncrona.

Asegúrate de que la URL proporcionada sea completa y correcta; en particular, utiliza QUrl::fromLocalFile() al cargar un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán con respecto a QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique lo contrario.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url, QQmlComponent::CompilationMode mode) { receiver->loadUrl(url, mode); });
Para ver más ejemplos y enfoques, consulta «Conexión a ranuras sobrecargadas».

[signal] void QQmlComponent::progressChanged(qreal progress)

Se emite cada vez que cambia el progreso de carga del componente. ` progress ` será el progreso actual, comprendido entre 0,0 (sin nada cargado) y 1,0 (finalizado).

Nota: Señalde notificador para la propiedad progress.

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &url)

Establece el componente « QQmlComponent » para que utilice el QML « data » especificado. Si se proporciona « url », se utiliza para establecer el nombre del componente y para proporcionar una ruta base para los elementos resueltos por este componente. El componente se cargará y compilará de forma sincrónica.

Advertencia: El nuevo componente anulará cualquier componente existente con la misma URL. No debes pasar la URL de un componente ya existente.

void QQmlComponent::setInitialProperties(QObject *object, const QVariantMap &properties)

Establece el ` properties ` de nivel superior del ` object ` que se creó a partir de un ` QQmlComponent`.

Este método ofrece un control avanzado sobre la creación de instancias de componentes. En general, los programadores deben utilizar ` QQmlComponent::createWithInitialProperties ` para crear una instancia de objeto a partir de un componente.

Utilice este método después de haber llamado a beginCreate y antes de llamar a completeCreate. Si una propiedad proporcionada no existe, se emite una advertencia.

Este método no permite establecer directamente propiedades anidadas iniciales. En su lugar, para establecer un valor inicial para propiedades de tipo «value» con propiedades anidadas, hay que crear ese tipo de valor, asignarle su propiedad anidada y, a continuación, pasar el tipo de valor como propiedad inicial del objeto que se va a construir.

Por ejemplo, para establecer «fond.bold», puedes crear un ` QFont`, establecer su peso en negrita y, a continuación, pasar la fuente como propiedad inicial.

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

Se emite cada vez que cambia el estado del componente. status será el nuevo estado.

Nota: Señalde notificación para la propiedad status.

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