Compilador de tipos QML
El compilador de tipos QML, qmltc, es una herramienta incluida en Qt que traduce los tipos QML a tipos C++ que se compilan por adelantado como parte del código de usuario. El uso de qmltc puede mejorar el rendimiento en tiempo de ejecución, ya que el compilador dispone de más oportunidades de optimización en comparación con la creación de objetos basada en QQmlComponent. qmltc forma parte de la cadena de herramientas del compilador «Qt Quick ».
Por diseño, qmltc genera código destinado al usuario. Se supone que ese código debe ser utilizado directamente por la aplicación en C++; de lo contrario, no se obtendrá ningún beneficio. Este código generado sustituye esencialmente a QQmlComponent y sus API para crear objetos a partir de documentos QML. Puedes encontrar más información en «Uso de qmltc en una aplicación QML » y «Conceptos básicos sobre el código generado».
Para habilitar qmltc:
- Crea un módulo QML adecuado para tu aplicación.
- Invoca qmltc, por ejemplo, a través de la API de CMake.
#includeIncluye los archivos de cabecera generados en el código fuente de la aplicación.- Instancia un objeto del tipo generado.
En este flujo de trabajo, qmltc suele ejecutarse durante el proceso de compilación. Por lo tanto, cuando qmltc rechaza un documento QML (ya sea por errores o advertencias, o debido a construcciones que qmltc aún no admite), el proceso de compilación fallará. Esto es similar a cómo se reciben errores de qmllint cuando se habilita la generación automática de objetivos de linting durante la creación de módulos QML y, a continuación, se intenta «compilarlos» para ejecutar qmllint.
Advertencia: qmltc se encuentra actualmente en fase de vista previa técnica y es posible que no compile un programa QML arbitrario (consulta «Limitaciones conocidas» para obtener más detalles). Cuando qmltc falla, no se genera nada, ya que tu aplicación no puede utilizar de forma adecuada la salida de qmltc. Si tu programa contiene errores (o advertencias irresolubles), estos deben corregirse para permitir la compilación. La regla general es adherirse a las mejores prácticas y seguir los consejos de qmllint.
Nota: qmltc no garantiza que el código C++ generado mantenga la compatibilidad de API, código fuente o binario entre versiones pasadas o futuras, ni siquiera entre versiones de parche. Además, las aplicaciones compiladas con qmltc que utilicen los módulos Qml de Qt requerirán la vinculación con la API privada de Qt. Esto se debe a que los módulos Qml de Qt no suelen proporcionar una API pública de C++, ya que su uso principal se realiza a través de Qml.
Uso de qmltc en una aplicación QML
Desde el punto de vista del sistema de compilación, añadir la compilación con qmltc no difiere mucho de añadir la generación de la caché de QML. A grandes rasgos, el proceso de compilación podría describirse así:

Aunque el proceso de compilación real es mucho más complejo, este diagrama recoge los componentes principales que utiliza qmltc: los propios archivos QML y qmldir con la información de qmltypes. Las aplicaciones más sencillas suelen tener un qmldir bastante primitivo; sin embargo, en general, el qmldir puede ser complejo, ya que proporciona información esencial y bien estructurada sobre los tipos, de la que depende qmltc para realizar una traducción correcta de QML a C++.
No obstante, en el caso de qmltc no basta con añadir un paso adicional a la compilación. El código de la aplicación también debe modificarse para utilizar las clases generadas por qmltc en lugar de ` QQmlComponent ` o sus alternativas de nivel superior.
Compilación de código QML con qmltc
Qt, a partir de la versión 6, utiliza CMake para compilar sus diversos componentes. Los proyectos de los usuarios también pueden —y se les anima a ello— utilizar CMake para compilar sus componentes con Qt. Añadir a tu proyecto compatibilidad con la compilación con qmltc «lista para usar» requeriría asimismo un flujo de compilación basado en CMake, ya que este flujo se centra en los módulos QML adecuados y su infraestructura.
La forma más sencilla de añadir la compilación con qmltc es utilizar la API de CMake dedicada como parte de la creación de un módulo QML para la aplicación. Consideremos una estructura de directorios sencilla para la aplicación:
.
├── CMakeLists.txt
├── myspecialtype.h // C++ type exposed to QML
├── myspecialtype.cpp
├── myApp.qml // main QML page
├── MyButton.qml // custom UI button
├── MySlider.qml // custom UI slider
└── main.cpp // main C++ application fileEn ese caso, el código de CMake suele tener un aspecto similar al siguiente:
# Use "my_qmltc_example" as an application name:
set(application_name my_qmltc_example)
# Create a CMake target, add C++ source files, link libraries, etc...
# Specify a list of QML files to be compiled:
set(application_qml_files
myApp.qml
MyButton.qml
MySlider.qml
)
# Make the application into a proper QML module:
qt6_add_qml_module(${application_name}
URI QmltcExample
QML_FILES ${application_qml_files}
# Compile qml files (listed in QML_FILES) to C++ using qmltc and add these
# files to the application binary:
ENABLE_TYPE_COMPILER
NO_GENERATE_EXTRA_QMLDIRS
)
# (qmltc-specific) Link *private* libraries that correspond to QML modules:
find_package(Qt6 COMPONENTS QmlPrivate QuickPrivate)
target_link_libraries(${application_name} PRIVATE Qt::QmlPrivate Qt::QuickPrivate)Uso del C++ generado
A diferencia de lo que ocurre con la instanciación de ` QQmlComponent `, el resultado de `qmltc`, al ser código C++, es utilizado directamente por la aplicación. Por lo general, construir un nuevo objeto en C++ equivale a crear un nuevo objeto mediante ` QQmlComponent::create()`. Una vez creado, el objeto puede manipularse desde C++ o, por ejemplo, combinarse con ` QQuickWindow ` para mostrarlo en pantalla.
Si un tipo compilado expone algunas propiedades obligatorias, `qmltc` exigirá un valor inicial para dichas propiedades en el constructor del objeto generado.
Además, al constructor de un objeto `qmltc` se le puede proporcionar una función de llamada de retorno para establecer los valores iniciales de las propiedades del componente.
Dado un archivo ` myApp.qml `, el código de la aplicación (en ambos casos) tendría normalmente este aspecto:
#include <QtQml/qqmlcomponent.h>
QGuiApplication app(argc, argv);
app.setApplicationDisplayName(QStringLiteral("This example is powered by QQmlComponent :("));
QQmlEngine e;
// If the root element is Window, you don't need to create a Window.
// The snippet is for the cases where the root element is not a Window.
QQuickWindow window;
QQmlComponent component(&e);
component.loadUrl(
QUrl(QStringLiteral("qrc:/qt/qml/QmltcExample/myApp.qml")));
QScopedPointer<QObject> documentRoot(component.create());
QQuickItem *documentRootItem = qobject_cast<QQuickItem *>(documentRoot.get());
documentRootItem->setParentItem(window.contentItem());
window.setHeight(documentRootItem->height());
window.setWidth(documentRootItem->width());
// ...
window.show();
app.exec();#include "myapp.h" // include generated C++ header
QGuiApplication app(argc, argv);
app.setApplicationDisplayName(QStringLiteral("This example is powered by qmltc!"));
QQmlEngine e;
// If the root element is Window, you don't need to create a Window.
// The snippet is for the cases where the root element is not a Window.
QQuickWindow window;
QScopedPointer<QmltcExample::myApp> documentRoot(
new QmltcExample::myApp(&e, nullptr, [](auto& component){
component.setWidth(800);
}));
documentRoot->setParentItem(window.contentItem());
window.setHeight(documentRoot->height());
window.setWidth(documentRoot->width());
// ...
window.show();
app.exec();Motor QML
El código generado utiliza QQmlEngine para interactuar con las partes dinámicas de un documento QML, principalmente el código JavaScript. Para que esto funcione, no se necesitan configuraciones especiales. Cualquier instancia de QQmlEngine pasada al constructor de un objeto de clase generado por qmltc debería funcionar correctamente, al igual que QQmlComponent(engine). Esto también significa que puedes utilizar QQmlEngine methods que afecten al comportamiento de QML. Sin embargo, hay algunas salvedades. A diferencia de la creación de objetos basada en QQmlComponent, el propio qmltc no se basa en QQmlEngine al compilar el código a C++. Por ejemplo, QQmlEngine::addImportPath("/foo/bar/") —que normalmente da lugar a una ruta de importación adicional que hay que analizar— sería completamente ignorado por el procedimiento de compilación anticipada de qmltc.
Nota: Para añadir rutas de importación a la compilación de qmltc, considera utilizar en su lugar un argumento relevante del comando CMake.
En general, puede entenderse de la siguiente manera: « QQmlEngine » implica que el proceso de la aplicación se ejecute, mientras que «qmltc» no lo hace, ya que opera incluso antes de que se compile la aplicación. Dado que qmltc no intenta analizar el código fuente C++ de tu aplicación, no tiene forma de conocer ciertos tipos de manipulaciones de QML que tú, como usuario, realizas. En lugar de utilizar ` QQmlEngine ` y las rutinas de tiempo de ejecución relacionadas para exponer tipos a QML, añadir rutas de importación, etc., en la práctica se requiere crear módulos QML que funcionen correctamente y utilizar el registro declarativo de tipos en QML.
Advertencia: A pesar de que qmltc trabaja en estrecha colaboración con QQmlEngine y crea código C++, las clases generadas no pueden exponerse posteriormente a QML ni utilizarse a través de QQmlComponent.
Conceptos básicos de la salida generada
qmltc pretende ser compatible con el modelo de ejecución de QML existente. Esto implica que el código generado es, a grandes rasgos, equivalente a la lógica interna de configuración de QQmlComponent y, por lo tanto, deberías poder comprender el comportamiento, la semántica y la API de tu tipo QML de la misma forma que lo haces actualmente: inspeccionando visualmente el documento QML correspondiente.
Sin embargo, el código generado sigue resultando algo confuso, sobre todo teniendo en cuenta que su aplicación debería utilizar directamente la salida de qmltc en el lado de C++. El código generado consta de dos partes: la estructura de los archivos de compilación de CMake y el formato C++ generado. La primera se trata en la API de CMake de qmltc y la segunda se aborda aquí.
Consideremos un tipo sencillo «HelloWorld», que tiene una propiedad « hello », una función para mostrar dicha propiedad y una señal que se emite cuando se crea un objeto de ese tipo:
// HelloWorld.qml
import QtQml
QtObject {
id: me
property string hello: "Hello, qmltc!"
function printHello(prefix: string, suffix: string) {
console.log(prefix + me.hello + suffix);
}
signal created()
Component.onCompleted: me.created();
}Al proporcionar una alternativa en C++ para este tipo de QML, la clase de C++ necesitaría una macro del sistema de metaobjetos específica de QML, la decoración « Q_PROPERTY » para la propiedad « hello », la función de impresión en C++ « Q_INVOKABLE » y una definición de señal Qt estándar. Del mismo modo, qmltc traduciría el tipo «HelloWorld» dado en algo parecido a lo siguiente:
class HelloWorld : public QObject
{
Q_OBJECT
QML_ELEMENT
Q_PROPERTY(QString hello READ hello WRITE setHello BINDABLE bindableHello)
public:
HelloWorld(QQmlEngine* engine, QObject* parent = nullptr, [[maybe_unused]] qxp::function_ref<void(PropertyInitializer&)> initializer = [](PropertyInitializer&){});
Q_SIGNALS:
void created();
public:
QString hello();
void setHello(const QString& hello_);
QBindable<QString> bindableHello();
Q_INVOKABLE void printHello(passByConstRefOrValue<QString> prefix, passByConstRefOrValue<QString> suffix);
// ...
};Aunque los detalles concretos del tipo generado puedan variar, los aspectos universales se mantienen. Por ejemplo:
- Los tipos QML de un documento se traducen a tipos de C++, según la información visible para el compilador.
- Las propiedades se traducen a propiedades de C++ con declaraciones de tipo « Q_PROPERTY ».
- Las funciones de JavaScript se convierten en funciones de C++ con `
Q_INVOKABLE`. - Las señales de QML se transforman en señales Qt de C++.
- Las enumeraciones de QML se convierten en enumeraciones de C++ con declaraciones de «
Q_ENUM».
Un detalle adicional es la forma en que qmltc genera los nombres de clase. El nombre de clase de un tipo QML determinado se deduce automáticamente a partir del documento QML que define dicho tipo: el nombre del archivo QML sin extensiones (hasta el primer « . », ambos excluidos; también conocido como «nombre base») se convierte en el nombre de la clase. Se conserva el uso de mayúsculas y minúsculas del nombre del archivo. Así, « HelloWorld.qml » daría lugar a « class HelloWorld » y « helloWoRlD.qml » a « class helloWoRlD ». Siguiendo la convención de QML, si el nombre de un archivo de documento QML comienza con una letra minúscula, se supone que la clase C++ generada es anónima y se marca con « QML_ANONYMOUS ».
Por ahora, aunque el código generado está listo para ser utilizado desde el lado de la aplicación C++, en general deberías limitar las llamadas a las API generadas. En su lugar, es preferible implementar la lógica de la aplicación en QML/JavaScript y en tipos de C++ escritos a mano expuestos a QML, utilizando las clases creadas por qmltc para la instanciación sencilla de objetos. Aunque el C++ generado te proporciona un acceso directo (y normalmente más rápido) a los elementos del tipo definidos en QML, comprender dicho código puede resultar complicado.
Limitaciones conocidas
A pesar de cubrir muchas características comunes de QML, qmltc se encuentra todavía en una fase temprana de desarrollo y aún hay algunas cosas que no son compatibles.
Es posible que los módulos QML importados que constan de tipos definidos en QML (como QtQuick.Controls) no se compilen correctamente, incluso si dichos tipos definidos en QML han sido compilados por qmltc. En la actualidad, se pueden utilizar de forma fiable los módulos QtQml y QtQuick, así como cualquier otro módulo QML que solo contenga clases de C++ expuestas a QML.
Además de esto, hay algunas peculiaridades más fundamentales que hay que tener en cuenta:
- Los módulos Qml de Qt suelen depender de bibliotecas de C++ para realizar las tareas más pesadas. Con bastante frecuencia, estas bibliotecas no proporcionan una API pública de C++ (ya que su uso principal es a través de Qml). Para los usuarios de qmltc, esto significa que sus aplicaciones deben enlazarse con bibliotecas privadas de Qt.
- Debido a la naturaleza de la generación de código de qmltc, los complementos de QML no se pueden utilizar con fines de compilación. En su lugar, los módulos QML —que utilizan un complemento— deben garantizar que se pueda acceder a los datos del complemento en tiempo de compilación. Dichos módulos QML contarían entonces con complementos opcionales. En la mayoría de los casos, la información en tiempo de compilación puede proporcionarse a través de un archivo de cabecera (con declaraciones en C++) y una biblioteca enlazable (con definiciones en C++). El código del usuario se encarga (normalmente a través de CMake) de incluir la ruta al archivo de cabecera y de enlazar con la biblioteca del módulo QML.
Nota: Dado que el compilador se encuentra en fase de vista previa técnica, es posible que también encuentres errores en qmltc, en el código generado o en alguna otra parte relacionada. Te animamos a que envíes un informe de error en este caso.
© 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.