【QML笔记】在QtCreator中添加自定义QML组件方法

一、引言

目前为止，在QtCreator上进行QML开发是体验最好的，包括语法高亮、代码提示以及组件关联，其他IDE上对QML的支持还不够全面。本文介绍在QtCreator添加自定义QML组件的方法，以实现自定义组件关联、语法高亮以及自定义组件可视化编辑。

本文Qt版本为5.9.6，相关代码链接稍后上传…

二、工程设置

使用QtCreator新建一个QtQuick工程，本文中工程名为QMLConfigTest，其目录如下

project
├─ main.cpp
├─ main.qml
├─ qml.qrc
├─ QtConfigTest.pro
└─ QtConfigTest.pro.user

三、自定义QML文件导入

此章节建议在系统文件夹中直接操作，而不是在QtCreator的管理器中

创建自定义QML模块文件夹MyModule，并在其内部添加qmldir和自己的qml组件
(本文为TestComponent.qml和SubModule/SubComponent.qml)，现在工程目录如下

project
├─ MyModule
│	├─ qmldir
│	├─ TestComponent.qml
│	└─ SubComponent
│		└─ SubComponent.qml
├─ main.cpp
├─ main.qml
├─ qml.qrc
├─ QtConfigTest.pro
└─ QtConfigTest.pro.user

其中 MyModule/qmldir 文件用于提供自定义QML组件的加载名称以及版本，具体形式如下：

module <模块名>
[singleton] <组件名> <版本号> <组件qml文件路径>
[singleton] <组件名> <版本号> <组件qml文件路径>
...

注意模块名必须和qmldir所在目录名相同！
singleton为可选，表示单例组件，相关内容本文不再展开

最终得到本文的qmldir内容如下

module MyModule
TestComponent 1.0 TestComponent.qml
SubComponent 1.0 SubComponent/SubComponent.qml

四、代码配置

在完成QML组件添加后，需要配置相关信息使程序能正常运行。

1. 首先，需要在qml.qrc中添加对应资源文件。为了便于管理，新建一个前缀名Components，在这里引入自定义QML文件以及qmldir文件，得到qml.qrc配置如图所示

2. 在main.cpp，设置QMLEngine的导入路径 engine.addImportPath(“qrc:/Components”);

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.addImportPath("qrc:/Components");
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

3. 愉快地引用你的自定义组件吧，本文在main.qml中对自定义组件的引用如下

注意此时QtCreator还无法正确识别自定义组件（见下一章节），但是不影响运行

import QtQuick 2.9
import QtQuick.Window 2.2
import MyModule 1.0
Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    Column{
        TestComponent{}
        SubComponent{}
    }
}

五、组件关联和可视化配置

第四节完成后，程序可以正常运行，但是QtCreator会提示“QML module not found"，并且可视化设计页面也无法显示自定义组件。

此时需要在.pro文件中进行配置，添加 自定义组件的父级目录 到QML_IMPORT_PATH 和 QML_DESIGNER_IMPORT_PATH中，本文配置如下

请注意是父级目录，在这里是MyModule文件夹的父级目录——即工程根目录

QML_IMPORT_PATH += $$PWD/
QML_DESIGNER_IMPORT_PATH += $$PWD/

之后重启QtCreator，一切都好~