Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QQmlEngineExtensionPlugin Class

La classe QQmlEngineExtensionPlugin fournit une base abstraite pour les plugins d'extension QML personnalisés. Plus d'informations...

En-tête : #include <QQmlEngineExtensionPlugin>
CMake : find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake : QT += qml
Héritages : QObject

Fonctions publiques

QQmlEngineExtensionPlugin(QObject *parent = nullptr)

Fonctions publiques réimplémentées

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

Macros

(since 6.2) Q_IMPORT_QML_PLUGIN(PluginName)

Description détaillée

QQmlEngineExtensionPlugin est une interface de plugin qui vous permet de créer des extensions QML qui peuvent être chargées dynamiquement dans les applications QML. Ces extensions permettent de mettre des types QML personnalisés à la disposition du moteur QML.

Pour écrire un plugin d'extension QML :

  1. Sous-classez QQmlEngineExtensionPlugin et utilisez la macro Q_PLUGIN_METADATA() pour enregistrer le plugin avec le système de méta-objets de Qt.
  2. Utilisez les macros QML_ELEMENT et QML_NAMED_ELEMENT() pour déclarer les types QML.
  3. Configurez votre fichier de compilation.

    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 vous utilisez qmake, créez un fichier qmldir pour décrire le plugin. Notez que CMake génère automatiquement le fichier qmldir par défaut.

Les plugins d'extension QML sont destinés à des applications spécifiques ou à des bibliothèques. Les plugins de bibliothèque doivent se limiter à l'enregistrement des types, car toute manipulation du contexte racine du moteur peut entraîner des conflits ou d'autres problèmes dans le code de l'utilisateur de la bibliothèque.

Note : Lorsque vous utilisez l'API CMake qt_add_qml_module, un plugin sera généré automatiquement pour vous. Il s'occupera de l'enregistrement des types. Vous ne devez écrire un plugin personnalisé que si vous avez des exigences particulières, telles que l'enregistrement de fournisseurs d'images personnalisés. Dans ce cas, passez NO_GENERATE_PLUGIN_SOURCE à l'appel qt_add_qml_module pour désactiver la génération du plugin par défaut.

L'éditeur de liens peut supprimer par erreur la fonction d'enregistrement de type générée à des fins d'optimisation. Vous pouvez éviter cela en déclarant un pointeur volatile synthétique vers la fonction quelque part dans votre code. La fonction est générée par qmltyperegistrar, et est nommée qml_register_types_ concaténée avec l'URI du module, les points étant remplacés par des traits de soulignement.

Si votre module s'appelle "my.module", vous devez ajouter la déclaration forward dans la portée globale :

void qml_register_types_my_module();

Ajoutez ensuite l'extrait de code suivant dans l'implémentation de toute fonction faisant partie du même binaire que l'enregistrement :

volatile auto registration = &qml_register_types_my_module;
Q_UNUSED(registration);

Le tutoriel Writing QML Extensions with C++ contient également un chapitre sur la création de plugins QML.

Voir aussi Comment créer des plugins Qt.

Documentation sur les fonctions membres

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

Construit un plugin d'extension QML avec l'adresse parent.

Notez que ce constructeur est invoqué automatiquement par la macro Q_PLUGIN_METADATA(), il n'est donc pas nécessaire de l'appeler explicitement.

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

Initialise l'extension à partir de uri en utilisant engine. Ici, un plugin d'application peut, par exemple, exposer certaines données ou objets à QML, en tant que propriétés de contexte sur le contexte racine du moteur.

Documentation sur les macros

[since 6.2] Q_IMPORT_QML_PLUGIN(PluginName)

Assure que le plugin dont la classe d'extension de plugin déclarant les métadonnées est nommée PluginName est lié aux constructions statiques. Pour les modules créés à l'aide de qt_add_qml_module, le nom de la classe d'extension de plugin par défaut est calculé à partir de l'URI du module QML en remplaçant les points par des traits de soulignement, sauf si l'argument CLASS_NAME est spécifié.

Par exemple, cette macro a été introduite dans Qt 6 :

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

Cette macro a été introduite dans Qt 6.2.

Voir aussi 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.