En esta página

Cómo escribir módulos QML

Debes declarar un módulo QML utilizando la API de módulos QML de CMake para:

  • Generar archivos qmldir y *.qmltypes.
  • Registrar tipos de C++ anotados con ` QML_ELEMENT`.
  • Combinar archivos QML y tipos basados en C++ en el mismo módulo.
  • Ejecutar qmlcachegen en todos los archivos QML.
  • Utilizar las versiones precompiladas de los archivos QML dentro del módulo.
  • Proporcionar el módulo tanto en el sistema de archivos físico como en el de recursos.
  • Crear una biblioteca de apoyo y un complemento opcional. Vincular la biblioteca de apoyo a la aplicación para evitar cargar el complemento en tiempo de ejecución.

Todas las acciones anteriores también se pueden configurar por separado. Para obtener más información, consulta la API del módulo QML de CMake.

Varios módulos QML en un único binario

Puedes añadir varios módulos QML al mismo binario. Define un objetivo de CMake para cada módulo y, a continuación, vincula los objetivos al ejecutable. Si los objetivos adicionales son todos bibliotecas estáticas, el resultado será un único binario que contenga varios módulos QML. En resumen, puedes crear una aplicación como esta:

myProject
    | - CMakeLists.txt
    | - main.cpp
    | - main.qml
    | - onething.h
    | - onething.cpp
    | - ExtraModule
        | - CMakeLists.txt
        | - Extra.qml
        | - extrathing.h
        | - extrathing.cpp

Para empezar, supongamos que main.qml contiene una instanciación de Extra.qml:

import ExtraModule
Extra { ... }

El módulo adicional debe ser una biblioteca estática para que puedas vincularlo al programa principal. Por lo tanto, indícalo así en ExtraModule/CMakeLists.txt:

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

qt_add_library(extra_module STATIC)
qt_add_qml_module(extra_module
    URI "ExtraModule"
    VERSION 1.0
    QML_FILES
        Extra.qml
    SOURCES
        extrathing.cpp extrathing.h
    RESOURCE_PREFIX /
)

Esto genera dos objetivos: « extra_module » para la biblioteca de soporte y « extra_moduleplugin » para el complemento. Al ser también una biblioteca estática, el complemento no se puede cargar en tiempo de ejecución.

En myProject/CMakeLists.txt debes especificar el módulo QML al que pertenecen main.qml y cualquier tipo declarado en onething.h:

qt_add_executable(main_program main.cpp)

qt_add_qml_module(main_program
    VERSION 1.0
    URI myProject
    QML_FILES
        main.qml
    SOURCES
        onething.cpp onething.h

)

A partir de ahí, se añade el subdirectorio para el módulo adicional:

add_subdirectory(ExtraModule)

Para garantizar que la vinculación del módulo extra funcione correctamente, debes:

  • Definir un símbolo en el módulo adicional.
  • Crear una referencia al símbolo desde el programa principal.

Los complementos QML contienen un símbolo que puedes utilizar para este fin. Puedes utilizar la macro Q_IMPORT_QML_PLUGIN para crear una referencia a este símbolo. Añade el siguiente código a main.cpp:

#include <QtQml/QQmlExtensionPlugin>
Q_IMPORT_QML_PLUGIN(ExtraModulePlugin)

ExtraModulePlugin es el nombre de la clase del complemento generado. Se compone de la URI del módulo con « Plugin » añadido al final. A continuación, en el archivo CMakeLists.txt del programa principal, vincula el complemento —no la biblioteca de apoyo— al programa principal:

target_link_libraries(main_program PRIVATE extra_moduleplugin)

Versiones

QML cuenta con un sistema complejo para asignar versiones a componentes y módulos. En la mayoría de los casos, debes ignorarlo por completo:

  1. No añadir nunca una versión a tus declaraciones de importación
  2. No especificar nunca ninguna versión en ` qt_add_qml_module`
  3. No utilizar nunca QML_ADDED_IN_VERSION ni QT_QML_SOURCE_VERSIONS
  4. No utilizar nunca ` Q_REVISION ` ni el atributo ` REVISION() ` en Q_PROPERTY
  5. Evitar el acceso sin calificar
  6. Utilizar generosamente los espacios de nombres de importación

Lo ideal es gestionar el control de versiones fuera del propio lenguaje. Por ejemplo, puedes mantener rutas de importación separadas para diferentes conjuntos de módulos QML. O bien, puedes utilizar un mecanismo de control de versiones proporcionado por tu sistema operativo para instalar o desinstalar paquetes con módulos QML.

En algunos casos, los propios módulos Qml de Qt pueden mostrar un comportamiento diferente, dependiendo de la versión que se importe. En concreto, si se añade una propiedad a un componente Qml y tu código contiene un acceso no calificado a otra propiedad con el mismo nombre, tu código dejará de funcionar. En el siguiente ejemplo, el código se comportará de forma diferente según la versión de Qt, ya que la propiedad ` topLeftRadius ` se añadió en Qt 6.7:

import QtQuick

Item {
    // property you want to use
    property real topLeftRadius: 24

    Rectangle {

        // correct for Qt version < 6.7 but uses Rectangle's topLeftRadius in 6.7
        objectName: "top left radius:" + topLeftRadius
    }
}

La solución en este caso es evitar el acceso sin calificar. Se puede utilizar qmllint para detectar este tipo de problemas. El siguiente ejemplo accede a la propiedad a la que realmente te refieres de una forma segura y calificada:

import QtQuick

Item {
    id: root

    // property you want to use
    property real topLeftRadius: 24

    Rectangle {

        // never mixes up topLeftRadius with unrelated Rectangle's topLeftRadius
        objectName: "top left radius:" + root.topLeftRadius
    }
}

También puedes evitar la incompatibilidad importando una versión específica de ` QtQuick`:

// make sure Rectangle has no topLeftRadius property
import QtQuick 6.6

Item {
    property real topLeftRadius: 24
    Rectangle {
        objectName: "top left radius:" + topLeftRadius
    }
}

Otro problema que se resuelve mediante el control de versiones es el hecho de que los componentes QML importados por diferentes módulos puedan enmascararse entre sí. En el siguiente ejemplo, si MyModule introdujera un componente denominado Rectangle en una versión más reciente, el Rectangle creado por este documento ya no sería un QQuickRectangle, sino el nuevo Rectangle introducido por MyModule.

import QtQuick
import MyModule

Rectangle {
    // MyModule's Rectangle, not QtQuick's
}

Una buena forma de evitar el enmascaramiento sería importar QtQuick y/o MyModule a espacios de nombres de tipos de la siguiente manera:

import QtQuick as QQ
import MyModule as MM

QQ.Rectangle {
   // QtQuick's Rectangle
}

Como alternativa, si importas MyModule con una versión fija y el nuevo componente recibe una etiqueta de versión correcta a través de QML_ADDED_IN_VERSION o QT_QML_SOURCE_VERSIONS, también se evita el enmascaramiento:

import QtQuick 6.6

// Types introduced after 1.0 are not available, like Rectangle for example
import MyModule 1.0

Rectangle {
    // QtQuick's Rectangle
}

Para que esto funcione, es necesario utilizar versiones en MyModule. Hay algunas cosas que hay que tener en cuenta.

Si añades versiones, añádelas en todas partes

Debes añadir un atributo ` VERSION ` a ` qt_add_qml_module`. La versión debe ser la más reciente que ofrezca tu módulo. Las versiones menores anteriores de la misma versión mayor se registrarán automáticamente. Para las versiones mayores anteriores, consulta más abajo.

Debes añadir QML_ADDED_IN_VERSION o QT_QML_SOURCE_VERSIONS a todos los tipos que no se hayan introducido en la versión x.0 de tu módulo, donde x es la versión principal actual.

Si olvida añadir una etiqueta de versión, el componente estará disponible en todas las versiones, lo que hará que el control de versiones resulte ineficaz.

Sin embargo, no hay forma de añadir versiones a las propiedades, métodos y señales definidos en QML. La única forma de versionar documentos QML es añadir un nuevo documento con una etiqueta QT_QML_SOURCE_VERSIONS distinta para cada cambio.

Las versiones no son transitivas

Si un componente de tu módulo A importa otro módulo B e instancia un tipo de ese módulo como elemento raíz, entonces la versión de importación de B es la que determina las propiedades disponibles en el componente resultante, independientemente de la versión de A que importe el usuario.

Consideremos un archivo TypeFromA.qml con la versión 2.6 en el módulo A:

import B 2.7

// Exposes TypeFromB 2.7, no matter what version of A is imported
TypeFromB { }

Ahora imaginemos a un usuario de TypeFromA:

import A 2.6

// This is TypeFromB 2.7.
TypeFromA { }

El usuario espera ver la versión 2.6, pero en realidad obtiene la versión 2.7 de la clase base TypeFromB.

Por lo tanto, para estar seguro, no solo tienes que duplicar tus archivos QML y asignarles nuevas versiones cuando añadas propiedades por tu cuenta, sino también cuando actualices las versiones de los módulos que importas.

El acceso calificado no respeta el control de versiones

El control de versiones solo afecta al acceso no calificado a los miembros de un tipo o al propio tipo. En el ejemplo con topLeftRadius, si escribes this.topLeftRadius, la propiedad se resolverá si utilizas Qt 6.7, incluso si import QtQuick 6.6.

Versiones y revisiones

Con ` QML_ADDED_IN_VERSION` y las variantes de dos argumentos de ` Q_REVISION ` y ` Q_PROPERTY` (` REVISION()`), solo puedes declarar versiones que estén estrechamente vinculadas a la revisión ` metaobject's `, tal y como se expone en ` QMetaMethod::revision ` y ` QMetaProperty::revision`. Esto significa que todos los tipos de tu jerarquía de tipos deben seguir el mismo esquema de versiones. Esto incluye cualquier tipo proporcionado por el propio Qt del que heredes.

Con ` qmlRegisterType ` y las funciones relacionadas, puedes registrar cualquier correspondencia entre revisiones de metaobjetos y versiones de tipos. A continuación, debes utilizar las formas de un solo argumento de ` Q_REVISION ` y el atributo ` REVISION ` de ` Q_PROPERTY`. Sin embargo, esto puede resultar bastante complejo y confuso, por lo que no se recomienda.

Exportación de varias versiones principales desde el mismo módulo

Por defecto,`qt_add_qml_module` tiene en cuenta la versión principal indicada en su argumento `VERSION`, incluso si los tipos individuales declaran otras versiones en su versión específica añadida mediante ` QT_QML_SOURCE_VERSIONS ` o ` Q_REVISION`. Si un módulo está disponible en más de una versión, también debes decidir en qué versiones están disponibles los archivos QML individuales. Para declarar más versiones principales, puedes utilizar la opción « PAST_MAJOR_VERSIONS » de ` qt_add_qml_module `, así como la propiedad ` QT_QML_SOURCE_VERSIONS ` en los archivos QML individuales.

set_source_files_properties(Thing.qml
    PROPERTIES
        QT_QML_SOURCE_VERSIONS "1.4;2.0;3.0"
)

set_source_files_properties(OtherThing.qml
    PROPERTIES
        QT_QML_SOURCE_VERSIONS "2.2;3.0"
)

qt_add_qml_module(my_module
    URI MyModule
    VERSION 3.2
    PAST_MAJOR_VERSIONS
        1 2
    QML_FILES
        Thing.qml
        OtherThing.qml
        OneMoreThing.qml
    SOURCES
        everything.cpp everything.h
)

MyModule está disponible en las versiones principales 1, 2 y 3. La versión máxima disponible es la 3.2. Puedes importar cualquier versión 1.x o 2.x con un x positivo. Para Thing.qml y OtherThing.qml hemos añadido información explícita sobre la versión. Thing.qml está disponible a partir de la versión 1.4, y OtherThing.qml, a partir de la versión 2.2. También hay que especificar las versiones posteriores en cada ` set_source_files_properties() `, ya que es posible que se eliminen archivos QML de un módulo al aumentar la versión principal. No hay información explícita sobre la versión de OneMoreThing.qml. Esto significa que OneMoreThing.qml está disponible en todas las versiones principales, a partir de la versión secundaria 0.

Con esta configuración, el código de registro generado registrará el módulo versions utilizando qmlRegisterModule() para cada una de las versiones principales. De esta forma, se podrán importar todas las versiones.

Estructuras de directorios personalizadas

La forma más sencilla de estructurar los módulos QML es guardarlos en directorios cuyo nombre corresponda a sus URI. Por ejemplo, un módulo My.Extra.Module se ubicaría en un directorio My/Extra/Module relativo a la aplicación que lo utiliza. De este modo, cualquier herramienta puede localizarlos fácilmente en tiempo de ejecución.

En proyectos más complejos, esta convención puede resultar demasiado restrictiva. Por ejemplo, es posible que quieras agrupar todos los módulos QML en un único lugar para evitar saturar el directorio raíz del proyecto. O quizá quieras reutilizar un mismo módulo en varias aplicaciones. Para esos casos, se puede utilizar ` QT_QML_OUTPUT_DIRECTORY ` en combinación con ` RESOURCE_PREFIX ` e `IMPORT_PATH`.

Para agrupar los módulos QML en un directorio de salida específico, por ejemplo, un subdirectorio «qml» dentro del directorio de compilación QT_QML_OUTPUT_DIRECTORY, configura lo siguiente en el archivo CMakeLists.txt de nivel superior:

set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/qml)

Los directorios de salida de los módulos QML se trasladan a la nueva ubicación. Del mismo modo, las llamadas a qmllint y qmlcachegen se adaptan automáticamente para utilizar el nuevo directorio de salida como ruta de importación. Dado que el nuevo directorio de salida no forma parte de la ruta de importación predeterminada de QML, debes añadirlo explícitamente en tiempo de ejecución para que se puedan encontrar los módulos QML.

Ahora que ya se ha resuelto la cuestión del sistema de archivos físico, es posible que aún desee trasladar los módulos QML a una ubicación diferente dentro del sistema de archivos de recursos. Para ello sirve la opción RESOURCE_PREFIX. Debes especificarla por separado en cada llamada a `qt_add_qml_module`. El módulo QML se colocará entonces bajo el prefijo especificado, con una ruta de destino generada a partir de la URI añadida al final. Por ejemplo, considera el siguiente módulo:

qt_add_qml_module(
    URI My.Great.Module
    VERSION 1.0
    RESOURCE_PREFIX /example.com/qml
    QML_FILES
        A.qml
        B.qml
)

Esto añadirá un directorio example.com/qml/My/Great/Module al sistema de archivos de recursos y colocará en él el módulo QML definido anteriormente. No es estrictamente necesario añadir el prefijo de recursos a la ruta de importación de QML, ya que el módulo se puede encontrar igualmente en el sistema de archivos físico. Sin embargo, por lo general es recomendable añadir el prefijo de recursos a la ruta de importación de QML, ya que, para la mayoría de los módulos, la carga desde el sistema de archivos de recursos es más rápida que desde el sistema de archivos físico.

Si los módulos QML están destinados a utilizarse en un proyecto más amplio con múltiples rutas de importación, tendrás que realizar un paso adicional: aunque añadas las rutas de importación en tiempo de ejecución, herramientas como qmllint no tienen acceso a ellas y podrían no encontrar las dependencias correctas. Utiliza IMPORT_PATH para indicar a las herramientas las rutas adicionales que deben tener en cuenta. Por ejemplo:

qt_add_qml_module(
    URI My.Dependent.Module
    VERSION 1.0
    QML_FILES
        C.qml
    IMPORT_PATH "/some/where/else"
)

Eliminación del acceso al sistema de archivos en tiempo de ejecución

Si todos los módulos QML se cargan siempre desde el sistema de archivos de recursos, puedes implementar la aplicación como un único binario.

Si la política QTP0001 está configurada como « NEW », el argumento « RESOURCE_PREFIX » de qt_add_qml_module() toma por defecto el valor « /qt/qml/ », por lo que tus módulos se colocan en :/qt/qml/ en el sistema de archivos de recursos. Esto forma parte de la ruta de importación predeterminada de QML, pero Qt no la utiliza por sí mismo. Para los módulos que se vayan a utilizar dentro de tu aplicación, este es el lugar adecuado.

Si, por el contrario, has especificado un prefijo de recursos personalizado RESOURCE_PREFIX, debes añadir dicho prefijo a la ruta de importación de QML. También puedes añadir varios prefijos de recursos:

QQmlEngine qmlEngine;
qmlEngine.addImportPath(QStringLiteral(":/my/resource/prefix"));
qmlEngine.addImportPath(QStringLiteral(":/other/resource/prefix"));
// Use qmlEngine to load the main.qml file.

Esto podría ser necesario al utilizar bibliotecas de terceros para evitar conflictos de nombres de módulos. Se desaconseja el uso de un prefijo de recursos personalizado en todos los demás casos.

La ruta :/qt-project.org/imports/ también forma parte de la ruta de importación predeterminada de QML. Para módulos que se reutilizan ampliamente en diferentes proyectos o versiones de Qt, :/qt-project.org/imports/ es un prefijo de recursos aceptable. Sin embargo, los propios módulos QML de Qt se encuentran allí. Debes tener cuidado de no sobrescribirlos.

No añadas rutas de importación innecesarias. De lo contrario, el motor QML podría encontrar tus módulos en una ubicación incorrecta. Esto puede provocar problemas que solo se pueden reproducir en entornos específicos.

Integración de complementos QML personalizados

Si incluyes un « image provider » en el módulo QML, debes implementar el método QQmlEngineExtensionPlugin::initializeEngine(). Esto, a su vez, hace necesario escribir tu propio complemento. Para dar soporte a este caso de uso, se puede utilizar NO_GENERATE_PLUGIN_SOURCE.

Consideremos un módulo que proporciona su propio código fuente de complemento:

qt_add_qml_module(imageproviderplugin
    VERSION 1.0
    URI "ImageProvider"
    PLUGIN_TARGET imageproviderplugin
    NO_PLUGIN_OPTIONAL
    NO_GENERATE_PLUGIN_SOURCE
    CLASS_NAME ImageProviderExtensionPlugin
    QML_FILES
        AAA.qml
        BBB.qml
    SOURCES
        moretypes.cpp moretypes.h
        myimageprovider.cpp myimageprovider.h
        plugin.cpp
)

Puedes declarar un proveedor de imágenes en myimageprovider.h, de la siguiente manera:

class MyImageProvider : public QQuickImageProvider
{
    [...]
};

A continuación, en plugin.cpp puedes definir el ` QQmlEngineExtensionPlugin`:

#include <myimageprovider.h>
#include <QtQml/qqmlextensionplugin.h>

class ImageProviderExtensionPlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
public:
    void initializeEngine(QQmlEngine *engine, const char *uri) final
    {
        Q_UNUSED(uri);
        engine->addImageProvider("myimg", new MyImageProvider);
    }
};

Esto hará que el proveedor de imágenes esté disponible. Tanto el complemento como la biblioteca de soporte se encuentran en el mismo objetivo de CMake, «imageproviderplugin». Esto se hace para que el enlazador no omita partes del módulo en distintos escenarios.

Dado que el complemento crea un proveedor de imágenes, ya no tiene una función ` initializeEngine ` trivial. Por lo tanto, el complemento ya no es opcional.

Véase también Cambios en « Qt Qml », Modernización de módulos QML y Portar módulos QML a CMake.

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