Qt QML元类型注册include路径不识别子目录的问题咨询

问题背景 #

构建包含QML的Qt项目时，QML元类型注册无法检索子目录中的头文件，导致编译报错。项目结构、代码配置及错误信息如下：

项目结构 #

./CMakeLists.txt
./ui
./ui/MainWindow.qml
./src
./src/controller
./src/controller/Foo.cpp
./src/controller/FileController.cpp
./src/controller/FileController.h
./main.cpp

CMakeLists.txt 配置 #

cmake_minimum_required(VERSION 3.25)
project(testproject)
find_package(Qt6 REQUIRED COMPONENTS Core Gui Quick Widgets)

qt_standard_project_setup()

qt_add_executable(testproject)
target_sources(testproject PRIVATE 
    main.cpp
)


target_link_libraries(testproject PRIVATE 
    Qt6::Widgets
    Qt6::Gui 
    Qt6::Quick 
)

set_target_properties(testproject PROPERTIES
        CXX_STANDARD 17
        CXX_STANDARD_REQUIRED ON
        CXX_EXTENSIONS OFF
        OUTPUT_NAME some_test_exec
)

target_include_directories(testproject PUBLIC ${PROJECT_SOURCE_DIR}/include)


qt_add_qml_module(testproject
        URI testproject
        VERSION 1.0
        SOURCES
            src/controller/FileController.h
            src/controller/FileController.cpp
        QML_FILES
            ui/MainWindow.qml
)

main.cpp 代码 #

#include <iostream>
#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char* argv[]) {
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;
    const QUrl url(u"qrc:/testproject/ui/MainWindow.qml"_qs);
    engine.load(url);
    return app.exec();
}

MainWindow.qml 代码 #

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    id: mainwindow
    visible: true
    width: 640
    height: 480
    menuBar: MenuBar {
        Menu {
            title: "File"
            MenuItem { text: "open" }
        }
    }
}

FileController.h 代码 #

#include <QObject>
#include <QtQml/qqmlregistration.h>

class FileController : public QObject {
    Q_OBJECT
    QML_ELEMENT // WITHOUT THIS IT COMPILES FINE
    Q_PROPERTY(QString file  READ name WRITE setName NOTIFY filenameChanged)
private:
    QString filename;
    void setName(QString name);
public:
    FileController(QObject *parent);
    QString name();
signals:
    void filenameChanged();
};

FileController.cpp 代码 #

#include "FileController.h"

FileController::FileController(QObject *parent) : QObject(parent) {}

void FileController::setName(QString name) {filename = name;}

QString FileController::name() {return filename;}

编译错误信息 #

[13/19] Building CXX object CMakeFiles/test....dir/testproject_qmltyperegistrations.cpp.o
FAILED: CMakeFiles/testproject.dir/testproject_qmltyperegistrations.cpp.o 
/usr/bin/c++ -DQT_CORE_LIB -DQT_GUI_LIB -DQT_NETWORK_LIB -DQT_NO_DEBUG -DQT_OPENGL_LIB -DQT_QMLINTEGRATION_LIB -DQT_QMLMODELS_LIB -DQT_QML_LIB -DQT_QUICK_LIB -DQT_WIDGETS_LIB -I/some/test/directory/build/testproject_autogen/include -I/ome/test/directory/include -I/some/test/directory -isystem /usr/include/qt6/QtQml/6.4.1 -isystem /usr/include/qt6/QtQml/6.4.1/QtQml -isystem /usr/include/qt6/QtCore/6.4.1 -isystem /usr/include/qt6/QtCore/6.4.1/QtCore -isystem /usr/include/qt6/QtCore -isystem /usr/include/qt6 -isystem /usr/lib/qt6/mkspecs/linux-g++ -isystem /usr/include/qt6/QtQml -isystem /usr/include/qt6/QtQmlIntegration -isystem /usr/include/qt6/QtNetwork -isystem /usr/include/qt6/QtWidgets -isystem /usr/include/qt6/QtGui -isystem /usr/include/qt6/QtQuick -isystem /usr/include/qt6/QtQmlModels -isystem /usr/include/qt6/QtOpenGL -fPIC -std=c++17 -MD -MT CMakeFiles/testproject.dir/testproject_qmltyperegistrations.cpp.o -MF CMakeFiles/testproject.dir/testproject_qmltyperegistrations.cpp.o.d -o CMakeFiles/testproject.dir/testproject_qmltyperegistrations.cpp.o -c /some/test/directory/build/testproject_qmltyperegistrations.cpp
/some/test/directory/qt/qml_in_other_dir/build/testproject_qmltyperegistrations.cpp:10:10: fatal error: FileController.h: No such file or directory
   10 | #include <FileController.h>

编辑补充：将FileController.h放到./include/controller/目录，修改target_include_directories并调整FileController.cpp中的#include <controller/FileController.h>后，问题仍存在。

问题解答 #

1. 为什么CMake和Qt不保留目录结构？ #

Qt生成qmltyperegistrations.cpp的元类型工具，只会提取头文件的文件名，不会保留原文件的目录路径。工具默认假设头文件可通过编译器的包含路径直接找到，而非依赖相对路径。

问题根源：

• 使用QML_ELEMENT宏时，生成的注册代码会以<FileController.h>的方式包含头文件，但头文件实际位于子目录中，而CMake未将这些子目录添加到编译器的包含路径。
• 即使将头文件移到include/controller，工具生成的代码仍会尝试查找顶层的FileController.h，而非controller/FileController.h，因为工具未记录头文件的子目录结构。

2. QML_ELEMENT宏是否适合当前场景？正确做法是什么？ #

QML_ELEMENT是Qt6推荐的C++类注册到QML的方式，本身是正确的。解决问题的合理方案如下：

方案一：调整头文件包含路径与引用方式

1. 保持目录结构：FileController.h放在include/controller/，FileController.cpp放在src/controller/。
2. 在CMake中添加子目录到包含路径：

   target_include_directories(testproject PUBLIC 
       ${PROJECT_SOURCE_DIR}/include
       ${PROJECT_SOURCE_DIR}/src
   )
   

3. 修改qt_add_qml_module的SOURCES路径，并确保头文件引用正确：

   qt_add_qml_module(testproject
           URI testproject
           VERSION 1.0
           SOURCES
               src/controller/FileController.cpp
               include/controller/FileController.h
           QML_FILES
               ui/MainWindow.qml
   )
   

4. 在FileController.h中添加明确的注册宏（可选，增强兼容性）：

   QML_IMPORT_NAME testproject
   QML_IMPORT_MAJOR_VERSION 1
   

方案二：手动注册类（特殊场景使用）

若不想调整目录结构，可去掉头文件中的QML_ELEMENT宏，在main.cpp中手动注册：

#include "src/controller/FileController.h"

int main(int argc, char* argv[]) {
    QGuiApplication app(argc, argv);
    qmlRegisterType<FileController>("testproject", 1, 0, "FileController");
    QQmlApplicationEngine engine;
    const QUrl url(u"qrc:/testproject/ui/MainWindow.qml"_qs);
    engine.load(url);
    return app.exec();
}

文件对话框逻辑实现建议

实现QML打开文件对话框并传递结果给C++类的正确流程：

1. QML中导入QtQuick.Dialogs，使用FileDialog组件触发选择。
2. 将选中路径绑定到FileController的属性，或通过信号传递给C++槽函数。

示例QML代码：

import QtQuick
import QtQuick.Controls
import QtQuick.Dialogs

ApplicationWindow {
    id: mainwindow
    visible: true
    width: 640
    height: 480

    FileDialog {
        id: fileDialog
        onAccepted: {
            fileController.file = fileDialog.fileUrl.toString()
        }
    }

    menuBar: MenuBar {
        Menu {
            title: "File"
            MenuItem { 
                text: "open" 
                onClicked: fileDialog.open()
            }
        }
    }

    FileController {
        id: fileController
        onFilenameChanged: console.log("Selected file:", file)
    }
}

内容的提问来源于stack exchange，提问作者Mohammed Li