【QT】创建项目：从零开始打造你的第一个炫酷应用

个人主页：Guiat
归属专栏：QT

正文

还在对着空白的屏幕发呆，不知如何用QT开启编程之旅？本文将手把手带你穿越项目创建的迷雾森林，用代码、图表和实例武装你，直到第一个窗口在屏幕上骄傲地亮起！

1. 磨刀不误砍柴工：安装与环境搭建

1.1 选择你的“武器库”：QT 安装器

访问 QT 官网，下载适合你操作系统（Windows, macOS, Linux）的 QT Online Installer。安装过程就像组装乐高：

1. 登录/注册： 需要一个 QT 账号（免费即可）。
2. 选择版本： 新手推荐稳定的 LTS（长期支持） 版本，如 QT 6.5.x 或 QT 5.15.x。它们就像经过时间考验的瑞士军刀。
3. 挑选组件： 这是关键！
   • QT 核心库： Qt 6.5.3 (或你选的版本) - 必选，主框架。
   • 编译器：
     • Windows: MinGW 11.2.0 64-bit (推荐，开源免费) 或 MSVC 2019 64-bit (需安装Visual Studio)。
     • macOS: Apple Clang (Xcode) - 确保已安装Xcode命令行工具。
     • Linux: 通常系统自带GCC，安装器会自动检测。
   • 开发工具： Qt Creator 11.0.x - 必选！ 我们的主战场IDE。
   • 附加库： 按需勾选，如 Qt Charts (图表), Qt Multimedia (多媒体), Qt WebEngine (网页嵌入) 等。初次安装可精简。
4. 安装路径： 建议默认或选择一个空间充足的路径（避免中文和空格！）。

【mermaid图】：QT 安装组件依赖关系

1.2 配置 QT Creator：你的指挥中心

首次打开 Qt Creator，它会自动检测安装的 Kits（工具链组合）。

• 检查 Kits: 进入 Tools -> Options -> Kits。
• 关键项：
  • Compiler: 应自动检测到 MinGW 或 Clang 或 MSVC。
  • QT version: 应自动关联到你安装的 QT 版本（如 Qt 6.5.3 MinGW 64-bit）。
  • CMake / QMake: 构建工具路径通常也能自动找到。
  • 确保有一个 Desktop Kit 的状态是 ✅ (Valid)。 这是创建桌面应用的通行证。

【举例】：如果你的 Kit 显示警告（如黄色感叹号），最常见原因是 编译器路径未找到 或 QT 版本未关联。手动点击 Browse... 按钮定位到正确的 g++.exe (MinGW) 或 qmake.exe (QT) 路径即可解决。

1.3 Hello, CMake (或 QMake)：构建系统的选择

QT 主要支持两种构建系统：

• QMake: QT 传统的构建工具，语法相对简单直接，对 QT 项目优化好。
• CMake: 现代推荐！ 功能更强大、更通用（跨平台、管理大型项目、集成第三方库极佳），是 QT 官方积极推动的方向。新项目建议首选 CMake。

【code】: 一个最简单的 QMake 项目文件 (hello.pro)

# 告诉 qmake 这是一个 app 项目模板
QT += core gui widgets  # 需要用到哪些 QT 模块
CONFIG += c++17         # 指定 C++ 标准
TARGET = HelloWorld     # 生成的可执行文件名
TEMPLATE = app          # 项目模板：应用程序

# 包含哪些源文件和头文件
SOURCES += main.cpp \
           mainwindow.cpp

HEADERS += mainwindow.h

# 资源文件（如图标、界面文件 .ui）
RESOURCES += resources.qrc

【code】: 一个最简单的 CMake 项目文件 (CMakeLists.txt)

# 最低要求的 CMake 版本
cmake_minimum_required(VERSION 3.16)

# 项目名称和使用的语言
project(HelloWorld LANGUAGES CXX)

# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 自动包含当前目录和标准模块路径
set(CMAKE_AUTOMOC ON)    # 处理 Qt 的元对象系统 (moc)
set(CMAKE_AUTORCC ON)    # 处理 Qt 资源文件 (.qrc)
set(CMAKE_AUTOUIC ON)    # 处理 Qt 设计师界面文件 (.ui)

# 查找所需的 Qt 库包
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)

# 添加可执行目标
add_executable(HelloWorld
    main.cpp
    mainwindow.cpp
    mainwindow.h
    # 如果使用了 .ui 或 .qrc 文件，CMake 的 AUTOUIC/AUTORCC 会自动处理它们
)

# 链接目标到所需的 Qt 库
target_link_libraries(HelloWorld PRIVATE
    Qt6::Core
    Qt6::Gui
    Qt6::Widgets
)

---

2. 迈出第一步：创建你的第一个 QT 项目

2.1 启动向导：点一点，项目来

1. 启动 QT Creator。
2. 点击 File -> New File or Project... 或欢迎界面的 New Project。
3. 选择项目模板： Application -> QT Widgets Application (经典桌面窗口应用)。点击 Choose...。
4. 项目位置和名称：
   • Name: 给你的项目起个响亮的名字 (e.g., MyFirstQtApp)。
   • Create in: 选择一个干净的文件夹存放项目。
   • Build system: 强烈建议选择 CMake (除非有明确理由用 QMake)。点击 Next。
5. 选择 Kit： 勾选你在 1.2 步骤中配置好的、状态为 Valid 的 Desktop Kit。点击 Next。
6. 类信息 (CMake)： (QMake 步骤类似)
   • Class name: 主窗口类名 (e.g., MainWindow)。
   • Base class: 通常保持 QMainWindow (提供菜单栏、状态栏等)。也可以选 QWidget (更基础)。
   • Header file, Source file, Form file (.ui): 文件名通常自动生成。勾选 Generate form 会创建一个可视化设计的界面文件。务必勾选！ 点击 Next。
7. 项目管理 (CMake)： 通常保持默认（版本控制系统可选）。点击 Finish！

【mermaid图】：QT Creator 新建项目向导流程

2.2 初探项目结构：文件王国巡礼

项目创建完成后，Qt Creator 左侧的 项目 视图 (Project) 会展示你的文件王国：

• CMakeLists.txt (核心)： CMake 的构建蓝图，定义了如何编译你的项目。
• main.cpp (入口点)： 程序的 main() 函数所在地，负责启动应用程序和显示主窗口。
• MainWindow.h / MainWindow.cpp (主窗口类)： 定义和实现了你的应用程序主窗口。
• MainWindow.ui (宝藏文件！)： XML 格式的文件，描述主窗口的界面布局（按钮、文本框等）。双击它会在 Qt Designer 中打开，进行可视化拖拽设计！

【举例】：想象 CMakeLists.txt 是建筑总工程师的施工图纸，main.cpp 是启动项目的钥匙，MainWindow 相关文件是主楼的设计图和施工方案，而 MainWindow.ui 就是精装修设计师的效果图。

2.3 理解 main.cpp：程序的引擎钥匙

打开 main.cpp，你会看到类似这样的代码骨架：

#include "mainwindow.h" // 包含主窗口类的头文件

#include <QApplication> // QT 应用程序类的头文件

int main(int argc, char *argv[])
{
    QApplication a(argc, argv); // 1. 创建 QT 应用程序对象 (管理事件循环)
    MainWindow w;               // 2. 创建你的主窗口对象
    w.show();                   // 3. 显示主窗口 (默认隐藏)
    return a.exec();            // 4. 进入主事件循环，等待用户操作！程序在此"阻塞"
}

【关键点解释】：

1. QApplication a(argc, argv): 每个QT GUI程序必须有且只有一个 QApplication 对象。 它处理系统级的事件（鼠标、键盘、窗口消息）、应用程序设置和事件循环。
2. MainWindow w: 实例化你定义的主窗口类 MainWindow。
3. w.show(): 调用 QWidget 的 show() 方法，让窗口显示出来。窗口默认是隐藏的。
4. return a.exec(): 这是核心！ a.exec() 启动 QT 的主事件循环 (Main Event Loop)。程序会停留在这里，不断地检查是否有事件（如点击按钮、移动鼠标、重绘窗口）发生，并调用相应的事件处理函数（如 on_pushButton_clicked()）。当事件循环结束时（通常在主窗口关闭后），exec() 返回，main() 函数返回，程序退出。

【mermaid图】：QT 应用程序启动与事件循环

---

3. 可视化魔法：用 Designer 设计你的界面

3.1 认识 Qt Designer：所见即所得

在 项目 视图中双击 MainWindow.ui 文件。Qt Creator 会切换到 Design 模式，打开内置的 Qt Designer。这是一个强大的可视化界面设计器，让你通过拖拽控件（Widgets）来构建界面，无需手动编写繁杂的布局代码。

• 左侧 Widget Box: 各种可用的控件分类（Buttons, Display Widgets, Input Widgets, Layouts, Containers, Spacers 等）。就像你的工具箱。
• 中间 Form Editor: 主设计区域，显示你的窗口。初始可能有一个默认的菜单栏、工具栏和中心区域（灰色）。
• 右侧 Property Editor: 显示当前选中控件的属性（位置、大小、文本、字体、颜色、对象名等）。修改属性是定制的关键！
• 右下角 Object Inspector: 以树形结构显示当前界面上的所有控件及其层级关系。管理复杂界面必备。
• 右上角 Action Editor / Signal & Slot Editor: 管理菜单/工具栏动作（Actions）和连接信号与槽（后面讲）。

3.2 动手设计：拖拽出你的第一个界面

我们来添加一些常用控件：

1. 添加按钮： 在 Widget Box 的 Buttons 分组下，找到 Push Button，将其拖拽到设计区域的中心区域 (centralWidget)。
2. 添加标签： 在 Display Widgets 分组下，找到 Label，拖拽到按钮旁边。
3. 添加输入框： 在 Input Widgets 分组下，找到 Line Edit，拖拽到标签下方。
4. 调整布局：
   • 随意摆放控件会很乱。QT 使用 布局管理器 (Layouts) 自动排列控件。
   • 按住 Ctrl 键，点击选中你添加的按钮、标签和输入框（也可以框选）。
   • 在设计器顶部的工具栏，找到布局按钮（或右键选中控件 -> Lay out），选择一个布局，例如 Lay Out Vertically (垂直布局) 或 Lay Out Horizontally (水平布局)。控件会自动排列整齐并随着窗口大小变化而调整。
   • 你也可以先将一个 Vertical Layout 或 Horizontal Layout 控件拖到 centralWidget 上，然后再把其他控件拖到这个布局控件内部。
5. 修改属性 (关键！)： 选中一个控件（如按钮），在右侧 Property Editor 中：
   • 修改 text 属性：将按钮文字改为 "点击我！"。
   • 修改 objectName 属性：给它一个有意义且唯一的标识符，非常重要！ 这将是你在代码中引用它的名字。例如 pushButtonGreet。避免使用默认的 pushButton！
   • 修改标签的 text 为 "请输入你的名字："。
   • 修改输入框的 objectName 为 lineEditName。
6. (可选) 美化： 调整字体大小 (font 属性)、背景色 (styleSheet 属性 - 支持CSS语法)、控件大小等。

【举例】：想象你在布置房间（centralWidget）。按钮、标签、输入框是家具（Widgets）。布局管理器（Layout）就是你的空间规划师，确保家具摆放整齐、空间利用合理，即使房间大小改变了（窗口缩放），家具也会自动调整位置。属性编辑器就是你定制家具颜色、大小、标签的工具箱。

3.3 信号与槽 (Signals & Slots)：GUI 的神经系统

QT 的核心机制，用于对象间的通信。它让按钮点击、文本改变、窗口关闭等用户操作能够触发代码执行。

• 信号 (Signal)： 当一个特定事件发生在某个对象上时（如按钮被点击 clicked()， 输入框文本改变 textChanged(QString)），该对象会 发出 (emit) 一个信号。信号就是事件发生的“广播”。
• 槽 (Slot)： 一个普通的成员函数，可以被调用来响应某个信号。槽就是“广播”的接收者和处理者。
• 连接 (Connection)： 使用 QObject::connect() 函数将一个对象的信号 关联到 另一个对象的槽。当信号发出时，它所连接的槽函数会被自动调用。

【code】: 信号与槽连接的经典语法 (旧式 - 仍常用)

// 语法: connect(发送者对象指针, 发送的信号, 接收者对象指针, 接收的槽函数);
connect(ui->pushButtonGreet, SIGNAL(clicked()), this, SLOT(on_pushButtonGreet_clicked()));

• ui->pushButtonGreet: 指向我们在 Designer 中设置的名为 pushButtonGreet 的按钮对象指针 (ui 是自动生成的界面类指针)。
• SIGNAL(clicked()): 按钮的 clicked() 信号。
• this: 通常指当前窗口类 (MainWindow) 对象本身，作为接收者。
• SLOT(on_pushButtonGreet_clicked()): 我们希望在 MainWindow 类中定义的槽函数 on_pushButtonGreet_clicked() 被调用。

【code】: 信号与槽连接的新式语法 (推荐，编译期检查)

// 语法: connect(发送者对象指针, &发送者类::信号, 接收者对象指针, &接收者类::槽);
connect(ui->pushButtonGreet, &QPushButton::clicked, this, &MainWindow::on_pushButtonGreet_clicked);

• 使用函数指针 (&QPushButton::clicked, &MainWindow::on_pushButtonGreet_clicked)，更安全高效，编译器会检查函数签名是否匹配。

【mermaid图】：信号与槽机制工作流程

---

4. 让界面活起来：编写业务逻辑

4.1 为按钮添加槽函数：响应用户点击

在 Design 模式下设计界面时，最便捷的方式是使用 Qt Creator 的自动槽函数生成功能：

1. 右键点击设计器中的按钮 (pushButtonGreet)。
2. 选择 Go to slot...。
3. 在弹出的对话框中，选择信号 clicked() (通常默认就是它)。
4. 点击 OK。

Qt Creator 会自动做三件事：

1. 在 mainwindow.h 的 private slots: 区域声明槽函数 void on_pushButtonGreet_clicked();。
2. 在 mainwindow.cpp 中生成该槽函数的空实现框架 void MainWindow::on_pushButtonGreet_clicked() { ... }。
3. 在 MainWindow 的构造函数中自动建立 pushButtonGreet 的 clicked() 信号到这个槽函数的连接！(省去了手动 connect 的步骤)。这是 Qt 的一个便利约定：on_控件对象名_信号名() 格式的槽会自动连接。

现在，在 mainwindow.cpp 中找到自动生成的 on_pushButtonGreet_clicked() 函数，添加你的业务逻辑：

void MainWindow::on_pushButtonGreet_clicked()
{
    // 1. 获取用户在 lineEditName 输入框中的文本
    QString userName = ui->lineEditName->text(); // 通过 ui 指针访问界面控件

    // 2. 检查输入是否为空
    if (userName.isEmpty()) {
        userName = "神秘人"; // 如果为空，给个默认名字
    }

    // 3. 使用 QMessageBox 弹出一个信息对话框
    QMessageBox::information(this, // 父窗口是当前主窗口
                             "问候", // 对话框标题
                             "你好, " + userName + "! 欢迎来到 QT 世界！"); // 对话框内容

    // 4. (可选) 清空输入框，方便下次输入
    ui->lineEditName->clear();
    // 5. (可选) 让输入框重新获得焦点，方便用户直接输入
    ui->lineEditName->setFocus();
}

【关键点解释】：

• ui->lineEditName->text(): 通过 ui 指针（它是 Ui::MainWindow 类的实例指针，在 MainWindow 构造函数中通过 ui->setupUi(this) 初始化）访问界面上的 lineEditName 输入框，并获取其当前文本 (text() 方法)。
• QString: QT 提供的强大字符串类，支持 Unicode、丰富的字符串操作。
• QMessageBox::information(...): 静态函数，创建一个标准的“信息”提示对话框。参数依次是父窗口指针、对话框标题、对话框内容文本。
• ui->lineEditName->clear(): 清空输入框内容。
• ui->lineEditName->setFocus(): 将键盘焦点设置回输入框。

4.2 构建与运行：见证奇迹的时刻

1. 保存所有文件 (Ctrl+S / Cmd+S)。
2. 点击 Qt Creator 左下角的构建按钮：
   • 锤子图标 (构建项目) 或 播放图标 (构建并运行)。快捷键通常是 Ctrl+R (Windows/Linux) 或 Cmd+R (macOS)。
3. 观察编译输出： Qt Creator 底部的 Compile Output 面板会显示编译和链接过程。如果有错误（红色文字），仔细阅读错误信息定位问题（通常是语法错误或头文件包含问题）。
4. 运行： 如果构建成功，你的程序将启动！尝试在输入框中输入名字，然后点击按钮。你应该能看到一个弹出对话框问候你！

【mermaid图】：QT 项目构建与运行流程

4.3 调试基础：揪出代码中的小虫子

QT Creator 集成了强大的调试器（GDB/CDB/LLDB）。调试是开发必备技能。

1. 设置断点： 在代码编辑器左侧行号区域点击，出现红色圆点。例如，在 on_pushButtonGreet_clicked() 函数的第一行设置断点。
2. 开始调试： 点击 Qt Creator 左下角 播放图标旁边的小虫子图标 (调试模式运行) 或按 F5 (常见快捷键)。程序启动后会暂停在 main() 入口。
3. 继续执行： 按 F5 或点击调试工具栏的 Continue (绿色三角) 让程序运行。
4. 触发断点： 在运行的程序界面上操作（如点击按钮）。当执行到断点行时，程序会自动暂停，Qt Creator 会高亮显示该行。
5. 查看信息：
   • Locals and Expressions: 查看当前函数内的局部变量值（如 userName）。
   • Call Stack: 查看函数调用栈。
   • Debugging Log: 显示调试器输出。
6. 单步执行：
   • F10 (Step Over): 执行当前行，如果该行有函数调用，不进入该函数内部。
   • F11 (Step Into): 执行当前行，如果该行有函数调用，进入该函数内部。
   • Shift+F11 (Step Out): 执行完当前函数剩余部分，跳出到调用它的地方。
7. 结束调试： 点击调试工具栏的红色方块 Stop 按钮，或关闭应用程序窗口。

【举例】：调试就像侦探破案。断点是你设置的蹲守点（userName 为什么是空的？）。单步执行是跟踪代码执行的每一步脚印。查看变量是检查嫌疑人的物证（userName 的值）。调用栈是回溯案件的来龙去脉（谁调用了这个函数？）。用好这些工具，代码中的“bug”将无处遁形！

---

恭喜你！ 至此，你已经成功闯过了 QT 项目创建的四大关卡：环境搭建、项目创建、界面设计、逻辑编写与调试。一个简单的、带交互的 QT 应用程序已经从你的指尖诞生。

这仅仅是 QT 世界的入口。接下来，你可以探索更复杂的布局、炫酷的图形视图、数据库连接、网络通信、多线程处理，甚至用 QML 打造现代风格的流畅界面。每一次编译运行的绿灯亮起，都是你征服新领域的信号弹！

结语
感谢您的阅读！期待您的一键三连！欢迎指正！