桌面应用 / 系统课时

看懂 QML 工程目录与 CMake

看懂 QML 工程目录与 CMake

本篇解决 QML 项目文件分工不清的问题。通过理解 main.cpp、Main.qml、CMakeLists.txt 与 QML 模块之间的关系,你可以知道一个 Qt 6 QML 应用从源码到窗口运行经历了哪些构建步骤。

学习目标

  • 理解 Qt 6 QML 工程中主要文件的职责。
  • 掌握 CMake 如何组织 Qt Quick 依赖和 QML 模块。
  • 能够根据项目目录定位界面、入口和构建配置。

QML 工程中的核心文件职责

一个典型 Qt 6 QML 桌面应用通常由 C++ 入口、QML 界面文件和 CMake 构建文件组成。它们分别负责启动程序、描述界面和告诉构建系统如何生成可执行文件。

常见目录结构如下:

text
MyQmlApp/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

main.cpp 是应用入口,负责创建 Qt 应用对象并加载 QML 界面。它通常不负责绘制按钮、布局等界面细节。

Main.qml 是声明式界面文件,用 QML 语法描述窗口、组件、属性和交互逻辑。界面的变化大多数情况下只需要修改 QML 文件。

CMakeLists.txt 管理项目构建过程,包括 Qt 模块查找、源文件注册、QML 模块声明和最终程序生成。

CMake 如何连接 C++ 与 QML

Qt 6 使用 CMake 作为主要构建系统。QML 文件不会像普通资源文件一样简单复制,而是需要通过 QML 模块机制参与构建。

一个基础的 CMake 配置示例如下:

cmake
cmake_minimum_required(VERSION 3.16)

project(MyQmlApp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)

qt_standard_project_setup()

qt_add_executable(MyQmlApp
    main.cpp
)

qt_add_qml_module(MyQmlApp
    URI MyQmlApp
    VERSION 1.0
    QML_FILES
        Main.qml
)

target_link_libraries(MyQmlApp
    PRIVATE Qt6::Quick
)

这段配置完成几个关键动作:

  • find_package 找到 Qt Quick 模块。
  • qt_add_executable 创建 C++ 可执行程序。
  • qt_add_qml_module 将 QML 文件注册到应用对应模块。
  • target_link_libraries 让程序链接 Qt Quick 能力。

QML 模块为什么重要

Qt 6 推荐使用 QML 模块管理界面文件。模块 URI 和版本号会成为 QML 类型系统识别组件的重要信息。

例如:

cmake
qt_add_qml_module(MyQmlApp
    URI MyQmlApp
    VERSION 1.0
    QML_FILES
        Main.qml
)

这里的 URI MyQmlApp 表示该模块名称,后续可以用于导入自定义 QML 类型。

如果没有正确声明模块,项目可能出现 QML 文件找不到、类型无法加载或运行时警告等问题。

如何判断文件应该放在哪里

实际开发中可以按照职责划分:

文件 主要职责 修改频率
main.cpp 启动应用、加载 QML 较低
Main.qml 界面结构和交互 较高
CMakeLists.txt 构建和依赖管理 中等

当你调整窗口布局、按钮样式时,通常修改 QML;当你增加 C++ 后端能力时,通常修改 C++ 文件并更新 CMake。

构建验证工程结构

完成配置后,可以使用 CMake 构建项目:

bash
cmake -S . -B build
cmake --build build

预期输出

text
[100%] Built target MyQmlApp

如果构建成功,说明 CMake 已经识别 C++ 文件、Qt 依赖和 QML 模块配置。

理解这些文件关系后,面对一个陌生 Qt 6 QML 项目时,可以先从 CMake 找依赖,再从 main.cpp 找启动入口,最后进入 QML 文件分析界面逻辑。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

看懂 QML 工程目录与 CMake

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通