制作 QML 扩展插件（Qt Quick 2 Extension Plugin）

向右看齐 2023-07-02 03:15 18阅读 0赞

**（本文测试环境为Qt5.12.11/Qt5.15.2+MSVC2019+QtCreator）**

制作插件（或者说动态库）是很常见的需求，QtQuick 也提供了这一功能，插件的源码既可以是 QML 的，也可以是 C++ 的。一般是用来制作界面控件。

# 1.做一个最简单的插件 #

**（建议先看官方示例：plugin qml 和 c++ extensions qml with writing）**

### 1.1.创建 Qt Quick 2 Extension Plugin 项目 ###

在QtCreator中点新建项目，在对话框中选择 Qt Quick 2 Extension Plugin，就可以创建一个简单的插件工程。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9nb25namlhbmJvMTk5Mi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9nb25namlhbmJvMTk5Mi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 1][]

![20200124132500424.png][]

除了工程名和 pro 中的 uri 名，一路默认就行了，先把流程跑通（uri 由 com.mycompany.qmlcomponents 改为和 module 模块名一致，也可以和我一样模块名( module )和 dll 名( plugin )也写一样）。可以看到，它默认生成了一个 lib 项目（TEMPLATE = lib），里面还包含一个 qmldir 文件，这个文件比较重要，dll 路径里没有它的话编辑器没法找到这个模块，也就没法自动提示了。此外，工程默认生成了一个 QQuickItem 的派生类，并在 xxx\_plugin.cpp 文件里注册为了 QML 类型， QQuickItem 对应QML 中的 Item 类型，对于非可视类型，我们继承 QObject 就行了。

### 1.2.修改 MyItem ###

既然工程默认生成了 MyItem ，那我直接用这个类来自定义。作为演示，我定义了一个属性和一个函数。

//myitem.h
    #ifndef MYITEM_H
    #define MYITEM_H
    
    #include <QQuickItem>
    
    class MyItem : public QQuickItem
    {
        Q_OBJECT
        Q_DISABLE_COPY(MyItem)
        //自定义属性
        Q_PROPERTY(QString name READ getName WRITE setName NOTIFY nameChanged)
    public:
        explicit MyItem(QQuickItem *parent = nullptr);
        ~MyItem() override;
    
        QString getName() const;
        void setName(const QString &name);
    
        //自定义方法
        Q_INVOKABLE int getStringLength(const QString &str);
    
    signals:
        void nameChanged();
    
    private:
        QString _name;
    };
    
    #endif // MYITEM_H

//myitem.cpp
    #include "myitem.h"
    
    MyItem::MyItem(QQuickItem *parent):
        QQuickItem(parent)
    {
        // By default, QQuickItem does not draw anything. If you subclass
        // QQuickItem to create a visual item, you will need to uncomment the
        // following line and re-implement updatePaintNode()
    
        // setFlag(ItemHasContents, true);
    }
    
    MyItem::~MyItem()
    {
    }
    
    QString MyItem::getName() const
    {
        return _name;
    }
    
    void MyItem::setName(const QString &name)
    {
        if(_name!=name){
            _name=name;
            emit nameChanged();
        }
    }
    
    int MyItem::getStringLength(const QString &str)
    {
        return str.length();
    }

Qt5.15 之前的旧的注册为 QML 组件的方式是继承 QObject 及其子类，使用 qmlRegisterType 等系列函数手动注册：

qmlRegisterType<MyItem>(uri, 1, 0, "MyItem");

Qt5.15 推出了新的方式，在 pro 中写上对应配置，然后直接在组件类中加一句 QML\_ELEMENT 宏。目前 QtCreator 还是使用的旧的模板生成代码，所以先用旧的就好了。

CONFIG += qmltypes
    #uri = xxxxx
    QML_IMPORT_NAME = xxxx
    QML_IMPORT_MAJOR_VERSION = 1

class MyItem: public QQuickPaintedItem
    {
        Q_OBJECT
        QML_ELEMENT
    //...
    }

修改完后点击构建，会生成 dll，这里先手动创建一个 dll 模块同名的文件夹，然后把 dll 以及 qmldir 文件放进去，并把文件夹放到安装目录的 qml 文件夹下。（相当于 install 到了安装目录的 qml 文件夹下）

![20200124132554191.png][]

除了把文件夹放到运行环境 qml 目录里，也可以使用 QQmlApplicationEngine 的 addImportPath 指定文件夹所在的目录（qml 文件夹本身也在 importPath 列表中），如：

![20200209194136813.png][]

其中，我们的模块文件夹在路径的下一级。

### 1.3.使用插件 ###

新建一个 QtQuick 项目，测试刚才生成的插件：

import QtQuick 2.12
    import QtQuick.Window 2.12
    
    import TestQml_20200124_Plugin 1.0
    
    Window {
        visible: true
        width: 640
        height: 480
        title: qsTr("Hello World")
    
        MyItem{
            name: "test"
    
            Component.onCompleted: {
                console.log(name)
    
                let length=getStringLength("asdaa")
                console.log(length)
            }
        }
    }

如果操作正确，可以正常运行：

![20200124132753132.png][]

### 1.4.总结 ###

**第一点：**我没发现 Qt 有提供编译后执行 install 安装步骤的 CONFIG，一般是使用 copy 命令或者 make 参数加上 install（示例有写 CONFIG += install\_ok，但是没发现有任何用；我把生成的插件放到 Qt 安装目录下是方便 QtCreator 检测到，以便有编码提示）；**第二点：**qmldir 中的 module 就是 QML 中 import 那个模块名，plugin 就是 dll 的文件名，如果 module 使用小数点隔开，那么对应多级文件夹目录结构；**第三点：**很多人用 qmlplugindump 来生成 qmltypes 描述文件，但是目前还没发现该文件的必要性（Qt5.15 开始的新配置方式貌似会自动执行这一步）；其他问题以后遇到再补充。

# 2.将组件封装为插件 #

在 QQmlExtensionPlugin 派生类中，通过重写 registerTypes 方法，可以注册我们自己的组件，使用 qmlRegisterType 等函数可以将 C++ 类型注册给 QML（和我们平时注册C++类型是一样的操作），也可以使用 Q\_INIT\_RESOURCE 宏包含 .qrc 文件，文件里放有我们的 QML 代码，达到封装 QML 组件的目录，Qt5.15 之后则可以使用 QML\_ELEMENT 宏来注册。

我做了一个简单的示例，包括新旧两种方式，github链接如下：

[https://github.com/gongjianbo/QmlExtensionPlugin][https_github.com_gongjianbo_QmlExtensionPlugin]

（如果你运行这个 Demo 出现问题可以留言）

![watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA6b6a5bu65rOi_size_15_color_FFFFFF_t_70_g_se_x_16][]

# 3.参考 #

官方文档：[Creating C++ Plugins for QML | Qt QML 5.15.6][Creating C_ Plugins for QML _ Qt QML 5.15.6]

博客：[QML插件扩展（一） - 程序创造世界 - 博客园][QML_ - _ -]

博客：[QML插件扩展2（基于C++的插件扩展） - 程序创造世界 - 博客园][QML_2_C_ - _ -]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9nb25namlhbmJvMTk5Mi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200124120538964.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9nb25namlhbmJvMTk5Mi5ibG9nLmNzZG4ubmV0,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9nb25namlhbmJvMTk5Mi5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200124120640855.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9nb25namlhbmJvMTk5Mi5ibG9nLmNzZG4ubmV0,size_16,color_FFFFFF,t_70
[20200124132500424.png]: https://img-blog.csdnimg.cn/20200124132500424.png
[20200124132554191.png]: https://img-blog.csdnimg.cn/20200124132554191.png
[20200209194136813.png]: https://img-blog.csdnimg.cn/20200209194136813.png
[20200124132753132.png]: https://img-blog.csdnimg.cn/20200124132753132.png
[https_github.com_gongjianbo_QmlExtensionPlugin]: https://github.com/gongjianbo/QmlExtensionPlugin
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA6b6a5bu65rOi_size_15_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/20210911170848785.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA6b6a5bu65rOi,size_15,color_FFFFFF,t_70,g_se,x_16
[Creating C_ Plugins for QML _ Qt QML 5.15.6]: https://doc.qt.io/qt-5/qtqml-modules-cppplugins.html
[QML_ - _ -]: https://www.cnblogs.com/yanhuiw/p/4719597.html
[QML_2_C_ - _ -]: https://www.cnblogs.com/yanhuiw/p/4722557.html