qml自定义Quick模块（使用qml源码）

前言

qml可以单独导出某些特定的控件，以实现代码的重复利用。一种方法是直接将qml源码及资源导入新的工程，另一种方法是做成Quick模块。前者使用时，需要import对应的目录，后者直接引用模块名。

本节会记录下，如何自定义Quick模块，以供读者参考

一、确定模块目录结构

笔者设计的目录结束如下

|- xdquick.pri
|- XdQuick                                模块的主目录
|   |- images                             模块中，qml使用的图片资源
|   |   |- buttons            
|   |   |   |- btn_sel_bg_hov.png         背景图片
|   |   |   |- btn_sel_bg_nor.png         背景图片
|   |   |   |- btn_sel_bg_pre.png         背景图片
|   |- Qml                                模块中，qml文档
|   |   |- CustButton                     第一个，自定义按钮
|   |   |   |- CustButton.qml             qml文件
|   |   |   |- CustButtonForm.ui.qml      qml ui文件
|   |   |- CustRectangle.qml              第二个，自定义矩形
|   |- qmldir                             qmldir文件
|   |- xdquick.qrc                        资源文件

注：

模块的主目录，要大写开头   文件目录的名字，必须和qmldir中模块名相同

说明：笔者计划实现2个独立控件，一个自定义按钮CustButton，一个自定义矩形CustRectangle。

二、创建pri资源

为方便他人使用，笔者将所有资源都放到pri中，其他人使用时，直接在pro文件中include就可以。

以下是笔者的代码

# Additional import path used to resolve QML modules in Qt Creator's code model
QML_IMPORT_PATH += \
    $${PWD}
#QML2_IMPORT_PATH += \
#    $${PWD}

message($$QML_IMPORT_PATH)

# Additional import path used to resolve QML modules just for Qt Quick Designer
#QML_DESIGNER_IMPORT_PATH += \
#    $${PWD}

RESOURCES += \
    $$PWD/XdQuick/xdquick.qrc

说明

1.QML_IMPORT_PATH是给设计器使用的，添加后，设计器import时，才不会报错

2.笔者看到，有教程上会设置QML2_IMPORT_PATH，笔者没有设置，但可以正常工作

3.QML_DESIGNER_IMPORT_PATH是新建工程时添加的，笔者也没胡设置

4.资源文件除了添加外，需要修改下前缀，这个前缀会影响到修改main.cpp文件，且结尾必须是“/”+模块名，笔者设置为“/XdQuick”，以下是笔者资源文件内容

<RCC>
    <qresource prefix="/XdQuick">
        <file>images/buttons/btn_sel_bg_hov.png</file>
        <file>images/buttons/btn_sel_bg_nor.png</file>
        <file>images/buttons/btn_sel_bg_pre.png</file>
    </qresource>
</RCC>

这样可以保证include后，直接就添加资源文件了 

三、实现Qml组件

在QtCreator中，添加两个控件，

CustButton对应文件为Qml/CustButton/CustButton.qml、Qml/CustButton/CustButtonForm.ui.qml

CustRectangle对应文件为Qml/CustRectangle.qml

添加时，一定要选对资源文件，完成添加后，资源文件如下所示

<RCC>
    <qresource prefix="/XdQuick">
        <file>images/buttons/btn_sel_bg_hov.png</file>
        <file>images/buttons/btn_sel_bg_nor.png</file>
        <file>images/buttons/btn_sel_bg_pre.png</file>
        <file>Qml/CustButton/CustButton.qml</file>
        <file>Qml/CustButton/CustButtonForm.ui.qml</file>
        <file>Qml/CustRectangle.qml</file>
    </qresource>
</RCC>

 然后就可以实现对应的控件了

四、实现qmldir文件

这个文件的内容，建议在助手中查看下文档（帮助文档搜索关键词 “qmldir” 或 “Module Definition qmldir…”），添加完后，资源文件内容如下

<RCC>
    <qresource prefix="/XdQuick">
        <file>images/buttons/btn_sel_bg_hov.png</file>
        <file>images/buttons/btn_sel_bg_nor.png</file>
        <file>images/buttons/btn_sel_bg_pre.png</file>
        <file>Qml/CustButton/CustButton.qml</file>
        <file>Qml/CustButton/CustButtonForm.ui.qml</file>
        <file>Qml/CustRectangle.qml</file>
        <file>qmldir</file>
    </qresource>
</RCC>

笔者qmldir文件实现如下

module XdQuick
designersupported
CustRectangle 1.0 Qml/CustRectangle.qml
CustButton 1.0 Qml/CustButton/CustButton.qml

第一行定义模块名，注意一定要大写开头，且与模块的主目录名相同

第二行笔者曾尝试去除，也可以正常工作

剩下的部分，每行是控件的名字、当前的版本号、对应的qml文件名，这里是相对路径

注：只需要把对外导出的控件文件添加就可以，其他的不用添加，如ui文件不用添加

五、修改pro文件

这个比较好理解，就是添加pri文件就可以，添加如下代码

include($${PWD}/component/xdquick.pri)

六、修改main.cpp文件

QQmlApplicationEngine engine;
engine.addImportPath(QStringLiteral("qrc:/"));

注意

1.要在加载main.qml前，添加

2.这里要配合资源文件的前缀，确保import路径后，直接就是模块的主目录，否则会出现模块未加载的提示

3.这里也可以直接使用本地文件，但笔者不建议这么做

七、运行测试

经过以上修改后，在需要的qml文件中，直接添加如下，就可以导入对应的模块

import XdQuick 1.0

Item {
    CustRectangle {}
    CustButton {}
}

对应的控件也可以直接使用

运行结果如下

 笔者的测试源码下载 (笔者使用的Qt5.15.2测试，其他版本对应修改下就可以）

后记

细心的小伙伴可能已经注意了，在设计器中，无法正确显示自定义的控件，笔者会在下篇中记录处理方法，并实现设计器中的拖拽添加