Back to Qt.io
Contact Us Blog Download Qt
En esta página

QQmlEngineExtensionPlugin Class

La clase QQmlEngineExtensionPlugin proporciona una base abstracta para plugins de extensión QML personalizados. Más...

Cabecera: #include <QQmlEngineExtensionPlugin>
CMake: find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
Hereda: QObject

Funciones Públicas

QQmlEngineExtensionPlugin(QObject *parent = nullptr)

Funciones Públicas Reimplementadas

virtual void initializeEngine(QQmlEngine *engine, const char *uri) override

Macros

(since 6.2) Q_IMPORT_QML_PLUGIN(PluginName)

Descripción Detallada

QQmlEngineExtensionPlugin es una interfaz de plugin que permite crear extensiones QML que pueden cargarse dinámicamente en aplicaciones QML. Estas extensiones permiten poner tipos QML personalizados a disposición del motor QML.

Para escribir un plugin de extensión QML

  1. Subclase QQmlEngineExtensionPlugin y utilice la macro Q_PLUGIN_METADATA() para registrar el plugin con el sistema de metaobjetos Qt.
  2. Utilice las macros QML_ELEMENT y QML_NAMED_ELEMENT() para declarar los tipos QML.
  3. 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>
  4. Si estás usando qmake, crea un archivo qmldir para describir el plugin. Tenga en cuenta que CMake, por defecto, generará automáticamente el archivo qmldir.

Los plugins de extensión QML son para plugins específicos de aplicaciones o de bibliotecas. Los plugins de biblioteca deben limitarse a registrar tipos, ya que cualquier manipulación del contexto raíz del motor puede causar conflictos u otros problemas en el código del usuario de la biblioteca.

Nota: Cuando se utiliza el CMake qt_add_qml_module API, un plugin se generará automáticamente para usted. Se encargará del registro de tipos. Sólo necesita escribir un plugin personalizado si tiene requisitos especiales, como registrar proveedores de imágenes personalizados. En ese caso, pasa NO_GENERATE_PLUGIN_SOURCE a la llamada qt_add_qml_module para desactivar la generación del plugin por defecto.

El enlazador puede eliminar erróneamente la función de registro de tipos generada como una optimización. Puede evitarlo declarando un puntero sintético volátil a la función en algún lugar de su código. La función es generada por qmltyperegistrar, y se llama qml_register_types_ concatenada con el URI del módulo, con los puntos sustituidos por guiones bajos.

Si tu módulo se llama "mi.módulo", añadirías la declaración forward en el ámbito global:

void qml_register_types_my_module();

A continuación, añada 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);

El tutorial Writing QML Extensions with C++ también contiene un capítulo sobre la creación de plugins QML.

Vea también Cómo crear plugins Qt.

Documentación de funciones miembro

[explicit] QQmlEngineExtensionPlugin::QQmlEngineExtensionPlugin(QObject *parent = nullptr)

Construye un complemento de extensión QML con la dirección parent.

Tenga en cuenta que este constructor es invocado automáticamente por la macro Q_PLUGIN_METADATA(), por lo que no es necesario llamarlo explícitamente.

[override virtual] void QQmlEngineExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)

Inicializa la extensión desde uri usando engine. Aquí un plugin de aplicación podría, por ejemplo, exponer algunos datos u objetos a QML, como propiedades de contexto en el contexto raíz del motor.

Documentación de macros

[since 6.2] Q_IMPORT_QML_PLUGIN(PluginName)

Garantiza que el complemento cuya clase de extensión de complemento que declara metadatos se denomina PluginName se vincule a las compilaciones estáticas. Para los módulos creados mediante qt_add_qml_module, el nombre predeterminado de la clase de extensión del complemento se calcula a partir del URI del módulo QML sustituyendo los puntos por guiones bajos, a menos que se especifique el argumento CLASS_NAME.

Por ejemplo:

qt_add_qml_module(myplugin
    # The plugin extension class name in this case is my_Company_QmlComponents.
    URI my.Company.QmlComponents
    ...
)

Esta macro se introdujo en Qt 6.2.

Véase también Q_IMPORT_PLUGIN.

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