Back to Qt.io
Contact Us Blog Download Qt
Auf dieser Seite

QQmlEngineExtensionPlugin Class

Die Klasse „QQmlEngineExtensionPlugin“ dient als abstrakte Basis für benutzerdefinierte QML-Erweiterungs-Plugins. Mehr...

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

Öffentliche Funktionen

QQmlEngineExtensionPlugin(QObject *parent = nullptr)

Neu implementierte öffentliche Funktionen

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

Makros

(since 6.2) Q_IMPORT_QML_PLUGIN(PluginName)

Ausführliche Beschreibung

QQmlEngineExtensionPlugin ist eine Plugin-Schnittstelle, mit der Sie QML-Erweiterungen erstellen können, die dynamisch in QML-Anwendungen geladen werden können. Diese Erweiterungen ermöglichen es, benutzerdefinierte QML-Typen der QML-Engine zur Verfügung zu stellen.

So schreiben Sie ein QML-Erweiterungs-Plugin:

  1. Erstellen Sie eine Unterklasse von ` QQmlEngineExtensionPlugin ` und verwenden Sie das Makro ` Q_PLUGIN_METADATA()` (), um das Plugin beim Qt-Metaobjektsystem zu registrieren.
  2. Verwenden Sie die Makros „ QML_ELEMENT “ und „ QML_NAMED_ELEMENT()“, um QML-Typen zu deklarieren.
  3. Konfigurieren Sie Ihre Build-Datei.

    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. Wenn Sie qmake verwenden, erstellen Sie eine qmldir-Datei, um das Plugin zu beschreiben. Beachten Sie, dass CMake die qmldir-Datei standardmäßig automatisch generiert.

QML-Erweiterungs-Plugins sind entweder für anwendungsspezifische oder bibliotheksähnliche Plugins vorgesehen. Bibliotheks-Plugins sollten sich auf die Registrierung von Typen beschränken, da jede Manipulation des Root-Kontexts der Engine zu Konflikten oder anderen Problemen im Code des Bibliotheksnutzers führen kann.

Hinweis: Bei Verwendung der CMake-API `qt_add_qml_module ` wird automatisch ein Plugin für Sie generiert. Dieses übernimmt die Typregistrierung. Sie müssen nur dann ein benutzerdefiniertes Plugin schreiben, wenn Sie spezielle Anforderungen haben, wie beispielsweise die Registrierung benutzerdefinierter Bildanbieter. Übergeben Sie in diesem Fall NO_GENERATE_PLUGIN_SOURCE an den Aufruf von ` qt_add_qml_module `, um die Generierung des Standard-Plugins zu deaktivieren.

Der Linker könnte die generierte Typregistrierungsfunktion fälschlicherweise als Optimierung entfernen. Sie können dies verhindern, indem Sie irgendwo in Ihrem Code einen synthetischen, volatilen Zeiger auf die Funktion deklarieren. Die Funktion wird von `qmltyperegistrar` generiert und heißt „ qml_register_types_ “, verkettet mit der Modul-URI, wobei alle Punkte durch Unterstriche ersetzt werden.

Wenn Ihr Modul „my.module“ heißt, würden Sie die Vorabdeklaration im globalen Bereich hinzufügen:

void qml_register_types_my_module();

Fügen Sie anschließend den folgenden Codeausschnitt in die Implementierung einer beliebigen Funktion ein, die Teil derselben Binärdatei wie die Registrierung ist:

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

Das Tutorial „QML-Erweiterungen mit C++ schreiben“ enthält ebenfalls ein Kapitel zum Erstellen von QML-Plugins.

Siehe auch „So erstellen Sie Qt-Plugins“.

Dokumentation zu Mitgliedsfunktionen

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

Erstellt ein QML-Erweiterungs-Plugin mit dem angegebenen ` parent`.

Beachten Sie, dass dieser Konstruktor automatisch durch das Makro „ Q_PLUGIN_METADATA()“ aufgerufen wird, sodass es nicht erforderlich ist, ihn explizit aufzurufen.

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

Initialisiert die Erweiterung aus dem „ uri “ mithilfe von „ engine “. Hier könnte ein Anwendungs-Plugin beispielsweise bestimmte Daten oder Objekte für QML als Kontexteigenschaften im Stammkontext der Engine bereitstellen.

Makro-Dokumentation

[since 6.2] Q_IMPORT_QML_PLUGIN(PluginName)

Stellt sicher, dass das Plugin, dessen Plugin-Erweiterungsklasse zur Deklaration der Metadaten den Namen „ PluginName “ trägt, in statische Builds eingebunden wird. Bei Modulen, die mit „qt_add_qml_module“ erstellt wurden, wird der Standardname der Plugin-Erweiterungsklasse aus der QML-Modul-URI berechnet, indem Punkte durch Unterstriche ersetzt werden, sofern nicht das Argument „ CLASS_NAME “ angegeben wird.

Beispiel:

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

Dieses Makro wurde in Qt 6.2 eingeführt.

Siehe auch „ 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.