En esta página

Creación dinámica de objetos QML desde JavaScript

QML admite la creación dinámica de objetos desde JavaScript. Esto resulta útil para retrasar la instanciación de objetos hasta que sea necesario, mejorando así el tiempo de inicio de la aplicación. También permite crear objetos visuales de forma dinámica y añadirlos a la escena en respuesta a la entrada del usuario u otros eventos.

Advertencia: Los objetos no deben crearse dinámicamente a partir de fuentes no fiables. Las limitaciones aplicables a las fuentes QML estáticas se aplican igualmente a la creación dinámica de objetos.

Creación dinámica de objetos

Hay dos formas de crear objetos dinámicamente desde JavaScript. Puedes llamar a Qt.createComponent() para crear dinámicamente un objeto Component, o utilizar Qt.createQmlObject() para crear un objeto a partir de una cadena de QML. La creación de un componente es la mejor opción si ya tienes un componente definido en un documento QML y deseas crear dinámicamente instancias de dicho componente. Por otra parte, crear un objeto a partir de una cadena de QML resulta útil cuando el propio código QML del objeto se genera en tiempo de ejecución.

Creación dinámica de un componente

Para cargar dinámicamente un componente definido en un archivo QML, llama a la función ` Qt.createComponent()` en ` Qt object`. Esta función toma la URL del archivo QML como único argumento y crea un objeto ` Component ` a partir de dicha URL.

Una vez que se dispone de un ` Component`, se puede llamar a su método ` createObject()` para crear una instancia del componente. Esta función puede tomar uno o dos argumentos:

  • El primero es el padre del nuevo objeto. El padre puede ser un objeto gráfico (es decir, del tipo ` Item `) o un objeto no gráfico (es decir, del tipo ` QtObject ` o ` QObject ` de C++). Solo los objetos gráficos con objetos gráficos como padres se representarán en el Qt Quick lienzo visual. Si deseas establecer el padre más adelante, puedes pasar sin problema null a esta función.
  • El segundo es opcional y consiste en un mapa de pares propiedad-valor que definen los valores iniciales de cualquier propiedad del objeto. Los valores de propiedad especificados por este argumento se aplican al objeto antes de que finalice su creación, lo que evita errores de enlace que podrían producirse si determinadas propiedades debieran inicializarse para habilitar otros enlaces de propiedad. Además, se obtienen pequeñas mejoras de rendimiento en comparación con definir los valores de las propiedades y los enlaces después de crear el objeto.

A continuación se muestra un ejemplo. En primer lugar, está Sprite.qml, que define un componente QML sencillo:

import QtQuick

Rectangle { width: 80; height: 50; color: "red" }

Nuestro archivo principal de la aplicación, « main.qml », importa un archivo JavaScript « componentCreation.js » que creará objetos « Sprite »:

import QtQuick
import "componentCreation.js" as MyScript

Rectangle {
    id: appWindow
    width: 300; height: 300

    Component.onCompleted: MyScript.createSpriteObjects();
}

Aquí está componentCreation.js. Fíjate en que comprueba si el componente status es Component.Ready antes de llamar a createObject(), por si el archivo QML se carga a través de la red y, por lo tanto, no está disponible de inmediato.

var component;
var sprite;

function createSpriteObjects() {
    component = Qt.createComponent("Sprite.qml");
    if (component.status == Component.Ready)
        finishCreation();
    else
        component.statusChanged.connect(finishCreation);
}

function finishCreation() {
    if (component.status == Component.Ready) {
        sprite = component.createObject(appWindow, {x: 100, y: 100});
        if (sprite == null) {
            // Error Handling
            console.log("Error creating object");
        }
    } else if (component.status == Component.Error) {
        // Error Handling
        console.log("Error loading component:", component.errorString());
    }
}

Si estás seguro de que el archivo QML que se va a cargar es un archivo local, puedes omitir la función finishCreation() y llamar a createObject() inmediatamente:

function createSpriteObjects() {
    component = Qt.createComponent("Sprite.qml");
    sprite = component.createObject(appWindow, {x: 100, y: 100});

    if (sprite == null) {
        // Error Handling
        console.log("Error creating object");
    }
}

Obsérvese que, en ambos casos, se llama a ` createObject()` pasando ` appWindow ` como argumento «parent», ya que el objeto creado dinámicamente es un objeto visual (`Qt Quick`). El objeto creado se convertirá en un elemento secundario del objeto ` appWindow ` en ` main.qml` y aparecerá en la escena.

Cuando se utilicen archivos con rutas relativas, la ruta debe ser relativa al archivo en el que se ejecuta Qt.createComponent().

Para conectar señales a (o recibir señales de) objetos creados dinámicamente, utilice el método de señal connect(). Consulte «Conexión de señales a métodos y señales» para obtener más información.

También es posible instanciar componentes sin bloqueo mediante la función ` incubateObject()`.

Creación de un objeto a partir de una cadena de QML

Advertencia: La creación de objetos a partir de una cadena de QML es extremadamente lenta, ya que el motor tiene que compilar la cadena de QML pasada cada vez que se realiza esta operación. Además, es muy fácil generar código QML inválido al construir código QML mediante programación. Es mucho mejor mantener los componentes QML en archivos separados y añadir propiedades y métodos para personalizar su comportamiento, en lugar de crear nuevos componentes mediante la manipulación de cadenas.

Si el código QML no se define hasta el momento de la ejecución, puedes crear un objeto QML a partir de una cadena de QML utilizando la función ` Qt.createQmlObject()`, como en el siguiente ejemplo:

const newObject = Qt.createQmlObject(`
    import QtQuick

    Rectangle {
        color: "red"
        width: 20
        height: 20
    }
    `,
    parentItem,
    "myDynamicSnippet"
);

El primer argumento es la cadena de QML que se va a crear. Al igual que en un archivo nuevo, tendrás que importar cualquier tipo que desees utilizar. El segundo argumento es el objeto padre del nuevo objeto, y la semántica del argumento «padre» que se aplica a los componentes es igualmente aplicable a createQmlObject(). El tercer argumento es la ruta del archivo que se asociará al nuevo objeto; se utiliza para la notificación de errores.

Si la cadena de QML importa archivos mediante rutas relativas, la ruta debe ser relativa al archivo en el que se define el objeto padre (el segundo argumento del método).

Importante: Al compilar aplicaciones QML estáticas, se analizan los archivos QML para detectar dependencias de importación. De este modo, todos los complementos y recursos necesarios se resuelven en tiempo de compilación. Sin embargo, solo se tienen en cuenta las declaraciones de importación explícitas (las que se encuentran al principio de un archivo QML), y no las declaraciones de importación incluidas dentro de literales de cadena. Por lo tanto, para que las compilaciones estáticas funcionen, debes asegurarte de que los archivos QML que utilicen ` Qt.createQmlObject()` contengan explícitamente todas las importaciones necesarias al principio del archivo, además de dentro de las cadenas literales.

Mantenimiento de objetos creados dinámicamente

Al gestionar objetos creados dinámicamente, debe asegurarse de que el contexto de creación perdure más que el objeto creado. De lo contrario, si el contexto de creación se destruye primero, los enlaces y los controladores de señales del objeto dinámico dejarán de funcionar.

El contexto de creación real depende de cómo se cree un objeto:

  • Si se utiliza ` Qt.createComponent()`: el contexto de creación es el ` QQmlContext ` en el que se invoca este método
  • Si se invoca a ` Qt.createQmlObject()`, el contexto de creación es el contexto del objeto padre pasado a este método
  • Si se define un objeto ` Component{} ` y se invocan los métodos ` createObject()` o ` incubateObject()` sobre dicho objeto, el contexto de creación es aquel en el que se define el ` Component `

Además, ten en cuenta que, aunque los objetos creados dinámicamente pueden utilizarse igual que los demás objetos, no tienen un identificador (id) en QML.

Eliminación dinámica de objetos

En muchas interfaces de usuario, basta con establecer la opacidad de un objeto visual en 0 o con desplazar el objeto visual fuera de la pantalla en lugar de eliminarlo. Sin embargo, si tienes muchos objetos creados dinámicamente, puedes obtener una mejora significativa del rendimiento si eliminas los objetos que no se utilizan.

Ten en cuenta que nunca debes eliminar manualmente los objetos creados dinámicamente por las fábricas de objetos de QML (como Loader y Repeater). Además, debes evitar eliminar objetos que no hayas creado tú mismo de forma dinámica.

Los elementos se pueden eliminar utilizando el método ` destroy() `. Este método tiene un argumento opcional (cuyo valor por defecto es 0) que especifica el retraso aproximado, en milisegundos, antes de que el objeto sea destruido.

A continuación se muestra un ejemplo. El método ` application.qml ` crea cinco instancias del componente ` SelfDestroyingRect.qml `. Cada instancia ejecuta ` NumberAnimation` y, cuando la animación ha finalizado, llama a ` destroy() ` en su objeto raíz para destruirse a sí misma:

application.qml
import QtQuick

Item {
    id: container
    width: 500; height: 100

    Component.onCompleted: {
        var component = Qt.createComponent("SelfDestroyingRect.qml");
        for (var i=0; i<5; i++) {
            var object = component.createObject(container);
            object.x = (object.width + 10) * i;
        }
    }
}
SelfDestroyingRect.qml
import QtQuick

Rectangle {
    id: rect
    width: 80; height: 80
    color: "red"

    NumberAnimation on opacity {
        to: 0
        duration: 1000

        onRunningChanged: {
            if (!running) {
                console.log("Destroying...")
                rect.destroy();
            }
        }
    }
}

Como alternativa, el application.qml podría haber destruido el objeto creado llamando a object.destroy().

Ten en cuenta que es seguro llamar a `destroy()` en un objeto desde dentro de ese mismo objeto. Los objetos no se destruyen en el instante en que se llama a `destroy()`, sino que se limpian en algún momento entre el final de ese bloque de script y el siguiente fotograma (a menos que se haya especificado un retraso distinto de cero).

Ten en cuenta también que si se creara una instancia de ` SelfDestroyingRect ` de forma estática así:

Item {
    SelfDestroyingRect {
        // ...
    }
}

Esto daría lugar a un error, ya que los objetos solo pueden destruirse dinámicamente si se han creado dinámicamente.

Los objetos creados con ` Qt.createQmlObject()` pueden destruirse de forma similar utilizando ` destroy()`:

const newObject = Qt.createQmlObject(`
    import QtQuick

    Rectangle {
        color: "red"
        width: 20
        height: 20
    }
    `,
    parentItem,
    "myDynamicSnippet"
);
newObject.destroy(1000);

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