QQmlEngineExtensionPlugin Class
QQmlEngineExtensionPlugin 类为自定义 QML 扩展插件提供了一个抽象基类。更多内容...
| 头文件： | #include <QQmlEngineExtensionPlugin> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake： | QT += qml |
| 继承自： | QObject |
- 所有成员列表（包括继承的成员）
- QQmlEngineExtensionPlugin 属于插件类。
公共函数
| QQmlEngineExtensionPlugin(QObject *parent = nullptr) |
重新实现的公共函数
| virtual void | initializeEngine(QQmlEngine *engine, const char *uri) override |
宏
(since 6.2) | Q_IMPORT_QML_PLUGIN(PluginName) |
详细说明
QQmlEngineExtensionPlugin 这是一个插件接口，允许您创建可动态加载到 QML 应用程序中的 QML 扩展。这些扩展使自定义 QML 类型能够被 QML 引擎使用。
要编写一个 QML 扩展插件：
- 继承QQmlEngineExtensionPlugin 类，并使用Q_PLUGIN_METADATA()宏将插件注册到Qt元对象系统中。
- 使用QML_ELEMENT 和QML_NAMED_ELEMENT() 宏来声明 QML 类型。
- 配置您的构建文件。
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> - 如果您使用的是 qmake，请创建一个qmldir 文件来描述该插件。请注意，CMake 默认会自动生成qmldir 文件。
QML 扩展插件适用于应用程序专用插件或类库插件。类库插件应仅限于注册类型，因为对引擎根上下文的任何操作都可能在类库用户的代码中引发冲突或其他问题。
注意： 使用 CMake 的qt_add_qml_moduleAPI时，系统 会自动为您生成一个插件，该插件将负责类型注册。 只有当您有特殊需求（例如注册自定义图像提供程序）时，才需要编写自定义插件。在这种情况下，请在调用 `qt_add_qml_module ` 时传递`NO_GENERATE_PLUGIN_SOURCE`参数，以禁用默认插件的生成。
链接器可能会出于优化目的而错误地移除生成的类型注册函数。您可以在代码中的某处声明一个指向该函数的合成易失性指针，以此防止这种情况发生。该函数由qmltyperegistrar 生成，其名称由qml_register_types_ 与模块 URI 拼接而成，其中所有点号均替换为下划线。
如果您的模块名为“my.module”，则需在全局作用域中添加前向声明：
void qml_register_types_my_module();然后在与该注册函数属于同一二进制文件的任何函数的实现中，添加以下代码片段：
volatile auto registration = &qml_register_types_my_module;
Q_UNUSED(registration);《使用 C++ 编写 QML 扩展》教程中还包含一章关于创建 QML 插件的内容。
另请参阅 《如何创建 Qt 插件》。
成员函数文档
[explicit] QQmlEngineExtensionPlugin::QQmlEngineExtensionPlugin(QObject *parent = nullptr)
根据给定的parent 构建一个QML扩展插件。
请注意，此构造函数会由Q_PLUGIN_METADATA()宏自动调用，因此无需显式调用它。
[override virtual] void QQmlEngineExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)
使用engine 从uri 初始化该扩展。例如，应用程序插件可能会将某些数据或对象作为引擎根上下文中的上下文属性暴露给QML。
宏文档
[since 6.2] Q_IMPORT_QML_PLUGIN(PluginName)
确保其元数据声明的插件扩展类名为PluginName 的插件被链接到静态构建中。对于使用qt_add_qml_module创建的模块，默认的插件扩展类名是通过将QML模块URI中的点替换为下划线来计算的，除非指定了CLASS_NAME 参数。
例如：
qt_add_qml_module(myplugin
# The plugin extension class name in this case is my_Company_QmlComponents.
URI my.Company.QmlComponents
...
)该宏自 Qt 6.2 起引入。
另请参阅 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.
