Component QML Type

Encapsula la definición de un componente QML. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• progress : real
• status : enumeration
• url : url

Señales adjuntas

• completed()
• destruction()

Métodos

• QtObject createObject(QtObject parent, object properties)
• string errorString()
• object incubateObject(QtObject parent, object properties, enumeration mode)

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 esencialmente definir componentes QML en línea, dentro de un documento QML, en lugar de como un archivo QML independiente. Esto puede ser útil para reutilizar un componente pequeño dentro de un archivo QML, o para definir un componente que lógicamente pertenece con otros componentes QML dentro de un archivo.

Por ejemplo, éste es un componente que utilizan varios objetos de 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 }
}

Observe que mientras que un Rectangle por sí mismo se representaría y mostraría automáticamente, éste no es el caso del rectángulo anterior porque está definido dentro de un Component. El componente encapsula los tipos QML que contiene, 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 le puede anclar nada.

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 o 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 Rectangle) y no puede definir ningún dato fuera de este elemento, a excepción de un id (que en el ejemplo anterior es redSquare).

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

Component Los objetos también pueden crearse dinámicamente utilizando Qt.createComponent().

Components son útiles para declarar un tipo cuando sólo se necesita una instancia del tipo sin tener que añadir todo un nuevo archivo. Sin embargo, no puede nombrar este tipo y, en consecuencia, no puede utilizarlo para declarar una propiedad o utilizarlo en una anotación de tipo. Si necesita esto, prefiera utilizar componentes inline.

Contexto de creación

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

En el siguiente ejemplo, comp1 se crea dentro del contexto raíz de MyItem.qml, y cualquier objeto instanciado desde este componente tendrá acceso a los ids y propiedades dentro de ese contexto, como internalSettings.color. Cuando comp1 se utiliza como delegado de 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).

Item {
    property Component mycomponent: comp1

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

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

Es importante que el tiempo de vida del contexto de creación sobreviva a cualquier objeto creado. Para obtener más información, consulte Mantenimiento de objetos creados dinámicamente.

Documentación de propiedades

progress : real [read-only]

El progreso de carga del componente, de 0.0 (nada cargado) a 1.0 (finalizado).

status : enumeration [read-only]

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

url : url [read-only]

La URL del componente. Esta es la URL que se utilizó para construir el componente.

Documentación de la señal adjunta

completed()

Se emite después de instanciar el objeto. Puede utilizarse para ejecutar código de script al inicio, una vez que se ha establecido el entorno QML completo.

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

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

destruction()

Emitida cuando el objeto comienza su destrucción. Esto se puede utilizar para deshacer el trabajo realizado en respuesta a la señal completed(), u otro código imperativo en su aplicación.

El manejador de señal onDestruction puede ser declarado en cualquier objeto. El orden de ejecución de los manejadores no está definido.

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

Véase también Qt Qml.

Documentación de métodos

QtObject createObject(QtObject parent, object properties)

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

El objeto se creará en el mismo contexto en el que se creó el componente. Esta función siempre devuelve null cuando se llama a componentes que no se crearon en QML.

Si desea crear un objeto sin establecer un padre, especifique null para el valor parent. Tenga en cuenta que si el objeto devuelto se va a mostrar, debe proporcionar un valor parent válido o establecer la propiedad parent del objeto devuelto; de lo contrario, el objeto no será visible.

Si no se proporciona un parent a createObject(), se debe mantener una referencia al objeto devuelto para que no sea destruido por el recolector de basura. Esto es cierto independientemente de si Item::parent se establece después, porque establecer el elemento padre no cambia la propiedad del objeto. Sólo cambia el padre gráfico.

Este método acepta un argumento opcional properties que especifica un mapa de valores de propiedades iniciales para el objeto creado. Estos valores se aplican antes de finalizar la creación del objeto. Esto es más eficiente que establecer los valores de las propiedades después de la creación del objeto, especialmente cuando se definen grandes conjuntos de valores de propiedades, y también permite que se establezcan los enlaces de las propiedades (utilizando Qt.binding) antes de que se cree el objeto.

El argumento properties se especifica como un mapa de elementos propiedad-valor. Por ejemplo, el código siguiente crea un objeto con valores iniciales 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 pueden eliminarse con el método destroy(). Consulte 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 por humanos de cualquier error.

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

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

object incubateObject(QtObject parent, object 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 no provocan congelaciones en la interfaz de usuario.

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 mantenerse una referencia al objeto creado para que no sea destruido por el recolector de basura.

El argumento properties se especifica como un mapa de elementos 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 síncrona o asíncrona. El valor por defecto es asíncrono. En algunas circunstancias, incluso si se especifica Qt.Synchronous, la incubadora 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 tiene éxito, el método devuelve una incubadora, en caso contrario null. La incubadora tiene las siguientes propiedades:

• status - El estado de la incubadora. Los valores válidos son Component.Ready, Component.Loading y Component.Error.
• object - La instancia del objeto creado. Sólo estará disponible una vez que la incubadora esté en el estado Listo.
• onStatusChanged - Especifica una función de devolución de llamada que se invocará cuando cambie el estado. El estado se pasa como parámetro a la 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(). Consulte Creación dinámica de objetos QML desde JavaScript para obtener más información.

Véase también createObject().