Creación de complementos en C++ para QML
Creación de un complemento
El motor « QML engine » carga complementos de C++ para QML. Estos complementos suelen proporcionarse en un módulo de extensión de QML y pueden ofrecer tipos que los clientes pueden utilizar en documentos QML que importen el módulo. Para que un módulo se considere válido, debe contener al menos un tipo registrado.
QQmlEngineExtensionPlugin es una interfaz de complemento que permite crear extensiones de QML que se pueden cargar dinámicamente en aplicaciones QML. Estas extensiones permiten que los tipos QML personalizados estén disponibles para el motor de QML.
Para escribir un complemento de extensión de QML:
- Crea una subclase de ` QQmlEngineExtensionPlugin ` y utiliza la macro ` Q_PLUGIN_METADATA()` para registrar el complemento en el sistema de metaojetos de Qt.
- Utiliza las macros ` QML_ELEMENT ` y ` QML_NAMED_ELEMENT()` para declarar tipos QML.
- Configura tu archivo de compilación.
CMake:
qt_add_qml_module(<target> URI <my.import.name> VERSION 1.0 QML_FILES <app.qml> NO_RESOURCE_TARGET_PATH )qmake:
CONFIG += qmltypes QML_IMPORT_NAME = <my.import.name> QML_IMPORT_MAJOR_VERSION = <version> - Si utilizas qmake, crea un archivo qmldir para describir el complemento. Ten en cuenta que CMake, por defecto, generará automáticamente el archivo qmldir.
Los complementos de extensión QML están destinados a complementos específicos de una aplicación o similares a bibliotecas. Los complementos de biblioteca deben limitarse a registrar tipos, ya que cualquier manipulación del contexto raíz del motor puede provocar conflictos u otros problemas en el código del usuario de la biblioteca.
Nota: Al utilizar la API qt_add_qml_module de CMake, se generará automáticamente un complemento. Este se encargará del registro de tipos. Solo es necesario escribir un complemento personalizado si se tienen requisitos especiales, como registrar proveedores de imágenes personalizados. En ese caso, pasa NO_GENERATE_PLUGIN_SOURCE a la llamada a qt_add_qml_module para desactivar la generación del complemento predeterminado.
El enlazador podría eliminar por error la función de registro de tipos generada como medida de optimización. Puedes evitarlo declarando un puntero volátil sintético a la función en algún lugar de tu código. La función la genera qmltyperegistrar y se denomina qml_register_types_ concatenado con el URI del módulo, sustituyendo los puntos por guiones bajos.
Si tu módulo se llama «my.module», deberías añadir la declaración anticipada en el ámbito global:
void qml_register_types_my_module();A continuación, añade el siguiente fragmento de código en la implementación de cualquier función que forme parte del mismo binario que el registro:
volatile auto registration = &qml_register_types_my_module;
Q_UNUSED(registration);Referencia
- Escribir extensiones QML con C++: contiene un capítulo sobre la creación de complementos QML.
- Definición de tipos QML desde C++: información sobre cómo registrar tipos de C++ en el QML Runtime.
- Cómo crear complementos de Qt: información sobre los complementos de Qt
© 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.