桌面应用 / 系统课时
规划 QML 项目目录和模块
规划 QML 项目目录和模块
QML 项目变大后,真正难维护的往往不是文件数量,而是页面可以随意引用组件、主题和 C++ 对象,最终形成看不见的依赖网。本节把页面、复用组件、主题与 C++ 服务分成明确模块,并用 qt_add_qml_module() 让依赖在构建配置和 import 中显式出现。
学习目标
- 按页面、组件、主题和 C++ 服务划分职责边界
- 使用 QML 模块 URI 代替跨目录相对路径依赖
- 通过 CMake 和
qmllint验证模块是否可以正确解析
先按职责划分目录
一个可持续维护的桌面项目可以把应用入口和可复用能力分开。下面的结构不是唯一答案,但它明确了四类职责:页面负责组合业务界面,组件负责复用 UI,主题保存视觉能力,服务封装 C++ 接口。
src/
CMakeLists.txt
main.cpp
App/
CMakeLists.txt
Main.qml
Pages/
CMakeLists.txt
HomePage.qml
Components/
CMakeLists.txt
PrimaryButton.qml
Theme/
CMakeLists.txt
AppTheme.qml
Services/
CMakeLists.txt
systemservice.h
systemservice.cpp这里不让 HomePage.qml 通过 ../../Components/PrimaryButton.qml 一类路径跨目录取文件,而是让它声明 import App.Components。这样移动目录或拆分模块时,依赖关系仍由稳定的模块 URI 表达。

为职责建立 QML 模块
下面示例以 Qt 6.5 及以上为基线。顶层 src/CMakeLists.txt 创建应用,并按依赖顺序加入各子模块。
cmake_minimum_required(VERSION 3.21)
project(StructuredQml LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 6.5 REQUIRED COMPONENTS Quick)
qt_standard_project_setup(REQUIRES 6.5)
qt_add_executable(appStructured
main.cpp
)
add_subdirectory(App/Theme)
add_subdirectory(App/Components)
add_subdirectory(App/Services)
add_subdirectory(App/Pages)
add_subdirectory(App)
target_link_libraries(appStructured PRIVATE
Qt6::Quick
app_theme
app_components
app_services
app_pages
app_qml
)main.cpp 只负责启动应用并加载入口模块,不承担页面或业务逻辑。
#include <QGuiApplication>
#include <QQmlApplicationEngine>
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QQmlApplicationEngine engine;
engine.loadFromModule("App", "Main");
if (engine.rootObjects().isEmpty())
return -1;
return app.exec();
}应用入口模块的 App/CMakeLists.txt 只保存 Main.qml。模块 URI 使用点分名称,QML 通过 URI 导入,而不是依赖磁盘相对路径。
qt_add_qml_module(app_qml
URI App
QML_FILES
Main.qml
)页面模块显式声明它使用的其他 QML 模块。IMPORTS 用来描述 QML 级依赖,但不会替代顶层的 CMake 目标链接。
qt_add_qml_module(app_pages
URI App.Pages
QML_FILES
HomePage.qml
IMPORTS
App.Components
App.Theme
App.Services
)组件和主题也分别拥有自己的 URI。组件可以依赖主题,但不应反向依赖具体页面。
qt_add_qml_module(app_components
URI App.Components
QML_FILES
PrimaryButton.qml
IMPORTS
App.Theme
)
qt_add_qml_module(app_theme
URI App.Theme
QML_FILES
AppTheme.qml
)C++ 服务则作为独立 QML 模块暴露。下面的 SystemService 使用 QML_ELEMENT 注册类型,使页面只看见接口,而不用了解文件系统或平台 API 的实现细节。
#pragma once
#include <QObject>
#include <QString>
#include <QtQml/qqmlregistration.h>
class SystemService : public QObject
{
Q_OBJECT
QML_ELEMENT
public:
explicit SystemService(QObject *parent = nullptr)
: QObject(parent)
{
}
Q_INVOKABLE QString platformMessage() const
{
return QStringLiteral("service ready");
}
};对应的 App/Services/CMakeLists.txt 把 C++ 类型加入 App.Services 模块。
qt_add_qml_module(app_services
URI App.Services
SOURCES
systemservice.h
systemservice.cpp
)如果实现全部写在头文件中,systemservice.cpp 可以只包含头文件,以便保持示例目录结构清晰。
#include "systemservice.h"在 QML 中只依赖模块接口
HomePage.qml 不需要知道组件文件位于哪个物理目录,只声明自己依赖哪些模块。
import QtQuick
import App.Components
import App.Theme
import App.Services
Item {
SystemService {
id: systemService
}
PrimaryButton {
anchors.centerIn: parent
text: systemService.platformMessage()
}
}这种写法让依赖方向直接出现在文件顶部:页面依赖组件、主题和服务;组件不反向导入页面。项目继续扩大时,可以再拆出 App.Models、App.Dialogs 等模块,而不必让页面依赖一组脆弱的相对路径。
构建并验证模块边界
完成配置后先正常构建,再运行页面模块对应的 qmllint 目标,检查 QML 导入和类型解析。
cmake -S src -B build
cmake --build build
cmake --build build --target app_pages_qmllint预期输出
退出码为 0;appStructured 完成构建,app_pages_qmllint 未报告无法解析的 import 或类型。具体构建进度和文件路径因平台与生成器不同而不同。如果 import App.Components 无法解析,优先检查模块 URI 是否一致、对应子目录是否已加入构建,以及模块目标是否链接到最终应用。不要首先用额外导入路径或大量相对路径绕过错误,否则会重新引入隐式依赖。
目录只是物理组织方式,模块才是依赖边界。页面、组件、主题和 C++ 服务拥有清晰 URI 后,重构时可以直接检查 import 和 CMake 目标关系,而不必在整个仓库搜索跨目录路径。