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. En savoir plus...

En-tête : #include <QQmlEngineExtensionPlugin>
CMake : find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake : QT += qml
Hérite de : 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 pouvant être chargées dynamiquement dans des 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. Créez une sous-classe de ` QQmlEngineExtensionPlugin ` et utilisez la macro ` Q_PLUGIN_METADATA()` pour enregistrer le plugin auprès du système de méta-objets Qt.
  2. Utilisez les macros QML_ELEMENT et QML_NAMED_ELEMENT() pour déclarer des types QML.
  3. Configurez votre fichier de construction.

    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 ce fichier par défaut.

Les plugins d'extension QML sont destinés soit à des applications spécifiques, soit à 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.

Remarque : lorsque vous utilisez l’API CMake qt_add_qml_module, un plugin est généré automatiquement pour vous. Celui-ci se charge de l’enregistrement des types. Vous n’avez besoin d’é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, par erreur, supprimer la fonction d'enregistrement de type générée dans le cadre d'une optimisation. Vous pouvez éviter cela en déclarant un pointeur volatile synthétique vers cette fonction quelque part dans votre code. La fonction est générée par qmltyperegistrar et porte le nom « qml_register_types_ » concaténé à l'URI du module, les points étant remplacés par des traits de soulignement.

Si votre module s’appelle « my.module », vous ajouteriez la déclaration anticipée dans la portée globale :

void qml_register_types_my_module();

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

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

Le tutoriel « Écrire des extensions QML avec C++ » contient également un chapitre consacré à la création de plugins QML.

Voir également Comment créer des plug-ins Qt.

Documentation sur les fonctions membres

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

Crée un plugin d'extension QML à partir de l'parent fournie.

Notez que ce constructeur est appelé 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 l'uri à l'aide de l'engine. Ici, un plugin d'application peut, par exemple, exposer certaines données ou certains objets à QML, sous forme de propriétés de contexte dans le contexte racine du moteur.

Documentation sur les macros

[since 6.2] Q_IMPORT_QML_PLUGIN(PluginName)

Garantit que le plugin dont la classe d’extension déclarant les métadonnées est nommée « PluginName » soit intégré aux builds statiques. Pour les modules créés à l’aide de `qt_add_qml_module`, le nom par défaut de la classe d’extension du plugin 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 :

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 également 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.