为QML创建C++插件（qt qml c++ 开发）

liuian 2025-03-19 14:15 25 浏览

创建插件

由QML 引擎来为QML加载C++ 插件。这种插件通常是以QML扩展模块的形式出现的，它们被QML文档导入，并为QML文档中的客户端提供类型。模块需要至少一个有效的注册类型。
QQmlEngineExtensionPlugin 是一个插件接口，它允许创建，能被动态加载到QML应用中的QML扩展。这些扩展允许自定义被QML引擎识别的QML类型。
要写这样的扩展插件，如下操作：
1、继承QQmlEngineExtensionPlugin 并使用 Q_PLUGIN_METADATA() 宏，用Qt的元对象机制来注册一个插件。
2、使用QML_ELEMENT 和 QML_NAMED_ELEMENT() 宏来声明QML类型。
3、配置构建文件
CMake:

qt_add_qml_module(
    URI 
    VERSION 1.0
    QML_FILES 
    NO_RESOURCE_TARGET_PATH
)

qmake:

CONFIG += qmltypes
QML_IMPORT_NAME = 
QML_IMPORT_MAJOR_VERSION =

4、如果是使用qmake，要创建一个qmldir文件来描述这个插件。注意CMake将会自动生成这个qmldir文件。
QML扩展插件有应用程序规格、类库文件两种。库文件插件应当限定自身来注册类型，因为对引擎根上下文的任意操作可能会引起冲突，或用户库文件代码的其它问题。
链接器可能错误地删除注册类型，而将其当作一种优化。可以通过声明一个指向代码中的某个易失性指针，来阻止以上误删除。如果你的类型名为"my.module"，就应该在全局添加一个声明：

void qml_register_types_my_module();

然后在在同库的实现文件的任意函数中添加如下代码段，实现注册：

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

TimeExample QML 扩展插件

假定有一个新的 TimeModel C++ 类，要成为新的有效QML类型。它能过hour和minute两个属性来提供当前时间。它通过宏QML_NAMED_ELEMENT() 声明了一个名为Time 的QML类型。

class TimeModel : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int hour READ hour NOTIFY timeChanged)
    Q_PROPERTY(int minute READ minute NOTIFY timeChanged)
    QML_NAMED_ELEMENT(Time)
    ...

要使这个类型有效，需要创建一人名为QExampleQmlPlugin，继承自QQmlEngineExtensionPlugin的类。它在类定义中通过向宏Q_PLUGIN_METADATA()传入一个唯一标识符向Qt的元对象系统注册插件。

class QExampleQmlPlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
};

为插件构建设置

构建文件定义工程为插件库，指定其将被生成到imports/TimeExample路径，并为插件注册了目标名称。
使用CMake：

set(qml_files
    imports/TimeExample/Clock.qml
)

set(images
    imports/TimeExample/center.png
    imports/TimeExample/clock.png
    imports/TimeExample/hour.png
    imports/TimeExample/minute.png
)
qt_add_qml_module(qmlqtimeexample
    OUTPUT_DIRECTORY imports/TimeExample
    VERSION 1.0
    URI "TimeExample"
    SOURCES timemodel.cpp timemodel.h
    QML_FILES ${qml_files}
    RESOURCES ${images}
)

使用qmake:

TEMPLATE = lib
CONFIG += qt plugin qmltypes
QT += qml

QML_IMPORT_NAME = TimeExample
QML_IMPORT_MAJOR_VERSION = 1

DESTDIR = imports/$QML_IMPORT_NAME
TARGET  = qmlqtimeexampleplugin

SOURCES += qexampleqmlplugin.cpp

这样就为TimeModel类，注册了导入名为TimeModel 1.0，且QML类型名为Time。文章从C++ 来定义QML类型里有更多信息关于如何注册能在QML中使用的C++ 类型。

在qmldir中的插件定义

最后，需要在imports/TimeExample路径下创建一个qmldir 文件，来描述插件及其导出的类型。插件包含一个Clock.qml文件，和qmlqtimeexampleplugin一起被工程构建。
CMake将自动生成qmldir文件。想了解更多信息，查看自动生成qmldir和类型信息文件
当使用qmake时，要在qmldir文件中写入如下代码：

module TimeExample
Clock 1.0 Clock.qml
plugin qmlqtimeexampleplugin

本例中，为简化起见，TimeExaple源文件路径设为 imports/TimeExample，在源码中构建。然而，源码路径并不重要，因为qmldir文件可以指定路径来安装QML文件。
重要的是qmldir文件所在的文件路径。当用户导入模块，QML引擎使用模块标识符（TimeExample）来查找插件，所以其（qmldir）安装路径必须与模块标识符匹配。
一旦项目被构建和安装，任意导入TimeExample模块的QML都可以访问Time 组件

import TimeExample 1.0 // import types from the plugin

Clock { // this class is defined in QML (imports/TimeExample/Clock.qml)

    Time { // this class is defined in C++ (plugin.cpp)
        id: time
    }

    hours: time.hour
    minutes: time.minute

}

文章转自博客园（sammy621）：为QML创建C++插件 - sammy621 - 博客园

Qt开发必备技术栈学习路线和资料

c++插件