En esta página

Component QML Type

Encapsula una definición de componente QML. Más...

Import Statement: import QtQml
In C++: QQmlComponent

Propiedades

Señales adjuntas

Métodos

Descripción detallada

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

Los componentes suelen definirse mediante archivos de componentes, es decir, archivos « .qml ». El tipo «Component» permite, en esencia, definir componentes QML de forma inline, dentro de un documento QML, en lugar de hacerlo en un archivo QML independiente. Esto puede resultar útil para reutilizar un componente pequeño dentro de un archivo QML o para definir un componente que, lógicamente, pertenece a otros componentes QML dentro de un mismo archivo.

Por ejemplo, aquí hay un componente que utilizan varios objetos ` Loader `. Contiene un único elemento, un ` Rectangle`:

import QtQuick

Item {
    width: 100; height: 100

    Component {
        id: redSquare

        Rectangle {
            color: "red"
            width: 10
            height: 10
        }
    }

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

Obsérvese que, mientras que un ` Rectangle ` por sí solo se renderizaría y mostraría automáticamente, este no es el caso del rectángulo anterior, ya que está definido dentro de un ` Component`. El componente encapsula los tipos QML en su interior, como si estuvieran definidos en un archivo QML independiente, y no se carga hasta que se solicita (en este caso, por los dos objetos ` Loader `). Dado que «Component» no deriva de «Item», no se puede anclar nada a él.

Definir un « Component » es similar a definir un documento QML. Un documento QML tiene un único elemento de nivel superior que define el comportamiento y las propiedades de ese componente, y no puede definir propiedades ni comportamientos fuera de ese elemento de nivel superior. Del mismo modo, una definición de « Component » contiene un único elemento de nivel superior (que en el ejemplo anterior es un « Rectangle ») y no puede definir ningún dato fuera de este elemento, con la excepción de un identificador (que en el ejemplo anterior es «redSquare»).

El tipo « Component » se utiliza habitualmente para proporcionar componentes gráficos a las vistas. Por ejemplo, la propiedad « ListView::delegate » requiere un « Component » para especificar cómo se debe mostrar cada elemento de la lista.

Component Los objetos también se pueden crear dinámicamente mediante ` Qt.createComponent()`.

ComponentLos son útiles para declarar un tipo cuando solo se necesita una instancia del mismo sin tener que añadir un archivo nuevo completo. Sin embargo, no se puede asignar un nombre a este tipo y, por lo tanto, no se puede utilizar para declarar una propiedad ni en una anotación de tipo. Si necesitas esto, es mejor utilizar componentes en línea.

Contexto de creación

El contexto de creación de un componente corresponde al contexto en el que se declaró dicho componente. Este contexto se utiliza como contexto padre (creando una jerarquía de contextos) cuando el componente es instanciado por un objeto como un ` ListView ` o un `Loader`.

En el siguiente ejemplo, se crea comp1 dentro del contexto raíz de MyItem.qml, y cualquier objeto instanciado a partir de este componente tendrá acceso a los identificadores y propiedades de ese contexto, como internalSettings.color. Cuando se utiliza « comp1 » como delegado « ListView » en otro contexto (como en «main.qml» a continuación), seguirá teniendo acceso a las propiedades de su contexto de creación (que, de otro modo, serían privadas para los usuarios externos).

MyItem.qml
Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}
main.qml
ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

Es importante que la vida útil del contexto de creación sea más larga que la de cualquier objeto creado. Consulta «Mantenimiento de objetos creados dinámicamente» para obtener más detalles.

Documentación de propiedades

progress : real [read-only]

El progreso de la carga del componente, desde 0,0 (no se ha cargado nada) hasta 1,0 (finalizada).

status : enumeration [read-only]

Esta propiedad indica el estado de carga del componente. El estado puede ser uno de los siguientes:

ConstanteDescripción
Component.NullNo hay datos disponibles para el componente
Component.ReadyEl componente se ha cargado y puede utilizarse para crear instancias.
Component.LoadingEl componente se está cargando en este momento
Component.ErrorSe ha producido un error al cargar el componente. Al llamar a errorString() se obtendrá una descripción legible para el usuario de cualquier error.

url : url [read-only]

La URL del componente. Se trata de la URL que se utilizó para crear el componente.

Documentación adjunta sobre señales

[attached] completed()

Se emite una vez que se ha instanciado el objeto. Se puede utilizar para ejecutar código de script al inicio, una vez que se ha establecido por completo el entorno QML.

El controlador de señal ` onCompleted ` puede declararse en cualquier objeto. El orden de ejecución de los controladores no está definido.

Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

Nota: El controlador correspondiente es onCompleted.

[attached] destruction()

Se emite cuando el objeto comienza a destruirse. Esto puede utilizarse para deshacer el trabajo realizado en respuesta a la señal ` completed()` u otro código imperativo de la aplicación.

El controlador de la señal onDestruction puede declararse en cualquier objeto. El orden de ejecución de los controladores no está definido.

Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

Nota: El controlador correspondiente es ` onDestruction`.

Véase también Qt Qml.

Documentación de métodos

QtObject createObject(QtObject parent, var properties)

Crea y devuelve una instancia de este componente que tendrá los valores especificados para parent y properties. El argumento properties es opcional. Devuelve null si falla la creación del objeto.

El objeto se creará en el mismo contexto en el que se creó el componente. Esta función siempre devolverá null cuando se invoque sobre componentes que no se hayan creado en QML.

Si deseas crear un objeto sin establecer un padre, especifica ` null ` como valor de ` parent `. Ten en cuenta que, si el objeto devuelto va a mostrarse, debes proporcionar un valor válido para ` parent ` o establecer la propiedad ` parent ` del objeto devuelto; de lo contrario, el objeto no será visible.

Si no se proporciona un ` parent ` a `createObject()`, debe conservarse una referencia al objeto devuelto para que el recolector de basura no lo destruya. Esto es así independientemente de si se establece ` Item::parent ` posteriormente, ya que establecer el padre del `Item` no cambia la propiedad del objeto. Solo se modifica el padre gráfico.

Este método acepta un argumento opcional ` properties ` que especifica un mapa de valores iniciales de las propiedades del objeto creado. Estos valores se aplican antes de que finalice la creación del objeto. Esto resulta más eficiente que establecer los valores de las propiedades tras la creación del objeto, especialmente cuando se definen grandes conjuntos de valores de propiedades, y además permite configurar los enlaces de propiedades (mediante ` Qt.binding`) antes de que se cree el objeto.

El argumento ` properties ` se especifica como un mapa de elementos de propiedad-valor. Por ejemplo, el código siguiente crea un objeto con valores iniciales de ` x ` y ` y ` de 100 y 100, respectivamente:

const component = Qt.createComponent("Button.qml");
if (component.status === Component.Ready) {
    component.createObject(parent, { x: 100, y: 100 });
}

Las instancias creadas dinámicamente se pueden eliminar con el método destroy(). Consulta Creación dinámica de objetos QML desde JavaScript para obtener más información.

Véase también incubateObject().

string errorString()

Devuelve una descripción legible para el usuario de cualquier error.

La cadena incluye el archivo, la ubicación y la descripción de cada error. Si hay varios errores, se separan mediante un carácter de nueva línea.

Si no hay errores, se devuelve una cadena vacía.

var incubateObject(QtObject parent, var properties, enumeration mode)

Crea una incubadora para una instancia de este componente. Las incubadoras permiten instanciar nuevas instancias de componentes de forma asíncrona y evitan que la interfaz de usuario se bloquee.

El argumento ` parent ` especifica el padre que tendrá la instancia creada. Si se omite el parámetro o se pasa `null`, se creará un objeto sin padre. En este caso, debe conservarse una referencia al objeto creado para que el recolector de basura no lo destruya.

El argumento ` properties ` se especifica como un mapa de pares propiedad-valor que se establecerán en el objeto creado durante su construcción. ` mode ` puede ser `Qt.Synchronous` o `Qt.Asynchronous`, y controla si la instancia se crea de forma sincrónica o asíncrona. El valor por defecto es asíncrono. En algunas circunstancias, incluso si se especifica Qt.Synchronous, el incubador puede crear el objeto de forma asíncrona. Esto ocurre si el componente que llama a incubateObject() se está creando a su vez de forma asíncrona.

Los tres argumentos son opcionales.

Si se ejecuta correctamente, el método devuelve un «incubator»; en caso contrario, devuelve null. El «incubator» tiene las siguientes propiedades:

  • status - El estado del incubador. Los valores válidos son Component.Ready, Component.Loading y Component.Error.
  • object - La instancia del objeto creado. Solo estará disponible una vez que el incubador se encuentre en estado Ready.
  • onStatusChanged - Especifica una función de llamada de retorno que se invocará cuando cambie el estado. El estado se pasa como parámetro a la función de llamada de retorno.
  • forceCompletion() - Llamada para completar la incubación de forma sincrónica.

El siguiente ejemplo muestra cómo utilizar una incubadora:

const component = Qt.createComponent("Button.qml");

const incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status !== Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status === Component.Ready) {
            print("Object", incubator.object, "is now ready!");
        }
    };
} else {
    print("Object", incubator.object, "is ready immediately!");
}

Las instancias creadas dinámicamente se pueden eliminar con el método ` destroy() `. Consulta Creación dinámica de objetos QML desde JavaScript para obtener más información.

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

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