Creación de prototipos con la herramienta QML Runtime

La utilidad qml está pensada principalmente para probar tus aplicaciones y componentes QML. Para ejecutar una aplicación QML en un entorno de producción, a menudo es necesario desarrollar una aplicación C++ personalizada o incluir el archivo QML en un módulo. Consulta «Implementación de aplicaciones QML » para obtener más información.

qml puede instanciar cualquier tipo de QML que se le proporcione, tal cual, incluso si no hay nada que mostrar. Para mostrar contenido QML con un objeto raíz distinto de Window, qml envuelve este contenido en un Window.

Por lo tanto, al pasar de un prototipo desarrollado con qml a una aplicación en C++, debe asegurarse de que el elemento raíz sea un Window o bien crear un QQuickView en C++ para albergar el Item raíz. Sin embargo, mientras tanto, puede cargar y probar partes de su prototipo por separado con la herramienta qml.

Para cargar un archivo .qml, indica la ruta del archivo en la línea de comandos:

$ qml myqmlfile.qml

Para ver las opciones de configuración, ejecuta « qml » con el argumento « --help ».

Cuando el objeto raíz del archivo QML que se está cargando es un «Item» en lugar de una «Window», debe envolverse en un « Window » para que se muestre. Mientras se trabaja en ello, el objeto de nivel superior que ya está cargado se representa mediante un objeto « PartialScene ». A continuación, la herramienta qml carga archivos QML adicionales para decidir qué hacer a continuación: uno de ellos es un archivo de configuración que especifica en qué tipo de contenedor se debe envolver el PartialScene. La propiedad PartialScene.container proporciona una URL que apunta al código fuente QML del componente contenedor, el cual normalmente debería declarar un Window en el que envolver el Item que se cargó en primer lugar. Por lo tanto, el proceso de envolver un «Item» en una «Window» es programable; y, por defecto, estos dos archivos QML adicionales se cargan desde los recursos incluidos en el ejecutable «qml». Puedes ver la lista de configuraciones disponibles con el comando « --list-conf »:

$ qml --list-conf
Built-in configurations:
  default
  resizeToItem

La configuración « default » proporciona el comportamiento predeterminado: el elemento raíz se redimensionará para ocupar toda la ventana contenedora al inicio, así como cuando el usuario cambie el tamaño de la ventana. La configuración alternativa « resizeToItem » funciona al revés: el elemento puede establecer su propio tamaño mediante programación (por ejemplo, creando enlaces a sus propias propiedades « width » y « height »), y la ventana contenedora se redimensionará para adaptarse a él (sujeta a cualquier límite que pueda imponer el sistema de ventanas). Puedes elegir cualquiera de estas opciones utilizando la opción « -c » o « --config »:

$ qml -c resizeToItem selfResizingItem.qml

Se pueden añadir configuraciones adicionales creando directorios de configuración en QStandardPaths::AppConfigLocation, cada uno con dos archivos QML en su interior: un archivo de configuración llamado configuration.qml y un archivo QML que declare el contenedor Item, que puede tener cualquier nombre. Si se ha hecho esto, el comando « qml --list-conf » también mostrará esas configuraciones adicionales, mientras que la opción « --verbose » las desarrollará para proporcionar las rutas completas a dichas configuraciones y las ubicaciones adicionales en las que se ha realizado la búsqueda:

$ qml --list-conf --verbose
Built-in configurations:
  default
  resizeToItem
Other configurations:
  /home/myuser/.config/QtProject/Qml Runtime/simplest
Checked in:
  /home/myuser/.config/QtProject/Qml Runtime
  /etc/xdg/QtProject/Qml Runtime

A continuación se muestra un ejemplo de archivo ` configuration.qml `:

import QmlRuntime.Config

Configuration {
    PartialScene {
        itemType: "QQuickItem"
        container: Qt.resolvedUrl("ItemWrapper.qml")
    }
}

Y este es el archivo « ItemWrapper.qml » más sencillo posible al que podría apuntar la propiedad « container »:

import QtQuick

Window {
    required property Item containedObject: null
    onContainedObjectChanged: {
        if (containedObject == undefined || containedObject == null) {
            visible = false;
        } else {
            containedObject.parent = contentItem;
            visible = true;
        }
    }
}

Una vez creados estos archivos, puedes utilizar la opción « qml -c » indicando el nombre del directorio que contiene el archivo « configuration.qml », el cual especifica la ruta al objeto contenedor:

$ qml -c simplest mycomponent.qml

El entorno de ejecución de « qml » establecerá directamente la propiedad « containedObject », que debe tener ese nombre; y, una vez establecida, la ventana « Item » pasará a estar subordinada a la ventana « Window » y se mostrará. Dado que esta ventana se declara en QML, al escribir tu propia ventana contenedora, tienes total libertad para añadir las características adicionales que desees: para gestionar el cambio de tamaño de forma personalizada o para añadir funcionalidades que te resulten útiles durante la creación de prototipos.

Independientemente de lo que se haya encontrado en AppConfigLocation, también puedes utilizar la opción qml -c indicando la ruta completa al archivo « configuration.qml », y este, a su vez, puede especificar la ruta completa al objeto contenedor; de este modo, estos archivos pueden estar ubicados en cualquier lugar.

Además de las características que se pueden declarar en los archivos de configuración, la herramienta qml también ofrece algunas funciones adicionales a través de opciones de línea de comandos. Utiliza la opción --help para obtener una lista actualizada.

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