《QT学习第六章：布局管理与模块介绍、Git可视化操作》

工具	出身	核心特点	适用场景	和.pro 文件的关系
qmake	QT 官方开发	专为 QT 定制	新手学习 QT、中小型 QT 项目	`.pro文件` 是 qmake 的专属配置文件
CMake	第三方通用工具	跨平台、跨框架（支持 QT/C++/Python 等）	大型项目、跨框架 / 跨平台项目	不用.pro 文件，用`CMakeLists.txt`

三、QT模块

什么是模块？分类的【头文件、库文件】调用方法，模块大致关系：

cpp 复制代码

┌─────────────────────────────────────────────────────────────┐
│                    绝对根节点：Qt Core                        │
│                    （所有模块的地基）                          │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────┴─────────────────┐
          │                                   │
【分支1：纯功能非图形模块】        【分支2：图形底层核心】
（直接依赖 Qt Core）                Qt GUI（依赖 Core）
├─ Qt Network（网络）              （所有界面/图形的底层）
├─ Qt SQL（数据库）                     │
└─ Qt Test（C++测试）        ┌──────────┼──────────┐
                           │          │          │
                 【分支A：传统Widget】 【分支B：多媒体】 【分支C：现代QML】
                  🖥️ 桌面UI核心        🎵 音视频核心    ✨ 现代UI核心
                   Qt Widgets           Qt Multimedia      Qt QML
                 （依赖GUI+Core）       （依赖GUI+Core） （依赖GUI+Core）
                      │                                     │
                      │                                     │
          Qt Multimedia Widgets                     Qt Quick（QML界面框架）
         （Widget专用视频控件）                        （依赖QML+GUI+Core）
                                                             │
                                                             ├─ Qt Quick Controls（QML控件）
                                                             ├─ Qt Quick Dialogs（QML弹窗）
                                                             ├─ Qt Quick Layouts（QML布局）
                                                             └─ Qt Quick Test（QML测试）

QT附件属于QT模块的插件

（1）核心模块

所有其他模块的依赖项：CORE模块，主要包含以下方法作用：

Qt 核心对象模型（信号槽的底层支撑）

容器类（QList、QVector 等，适配 Qt 的 STL 替代）

字符串、文件 IO、线程、定时器、事件循环

国际化、插件系统、JSON/XML 解析等

（2）窗口/UI模块

（1）QT GUI

作用：所有图形界面底层

窗口系统、鼠标 / 键盘事件处理

2D 绘图（QPainter）、OpenGL 3D 渲染

图片、字体、剪切板、拖放、屏幕管理等

（2）Qt Widgets

作用：传统桌面界面的「控件库」，就是在 Qt Designer 里拖的那些东西

（3）Qt QML

作用：类似 HTML+CSS，用来写动态界面的需要用到的（是 Qt Quick 语言基础）

所有 QML 程序的底层支撑，写 QML 必须依赖它

（4）Qt Quick

作用：现代动态界面的「UI 框架」

（理解：想做好看、流畅的现代界面，用它；想做传统桌面工具，用 Qt Widgets）

提供 QML 的基础 UI 元素（Rectangle、Text、Image、MouseArea 等）

动画系统、状态机、视图组件，用来构建高动态、流畅的触摸界面

（5）Qt Quick Controls

作用：Qt Quick 的「控件库」

（6）Qt Quick Dialogs

作用：Qt Quick 里的「系统对话框（弹窗）」

（7）Qt Quick Layouts

作用：Qt Quick 里的「布局工具」

（3）功能扩展模块

（8）Qt Multimedia

作用：Qt 的「多媒体工具箱」，做播放器 / 摄像头 / 录音功能

（9）Qt Multimedia Widgets

作用：Qt Multimedia 和 Qt Widgets 的「适配器」，让传统界面能显示多媒体内容

（10）Qt Network

作用：网络模块，比如TCP、UDP

（11）Qt SQL

作用：Qt 的「数据库工具箱」，操作本地 / 远程数据库

（4）测试工具模块

（1）Qt Test

作用：C++ 代码的「单元测试框架」，比如测试类、函数正确性

（2）Qt Quick Test

作用：QML 代码的「单元测试框架」，比如验证QML界面的交互

四、QWidget模块属性

（1）enabled

描述：控件是否可用

（2）geometry

描述：位置+尺寸

（3）sizePolicy

描述：窗口放大 / 缩小时，控件怎么跟着变，分水平 / 垂直两个方向

Preferred（默认）：控件保持「自己觉得舒服的大小」，窗口放大时它会适当变大
Fixed：固定大小
Expanding：尽可能占满所有空白空间
Minimum：只保证最小大小
Maximum：只保证最大大小
水平伸展 / 垂直伸展 ：当多个控件在一个布局里时，数值越大的控件，在窗口放大时分到的空白空间越多

（4）`minimumSize` / `maximumSize`

描述：窗口再大/小，控件也不会比这个大小更或者更小

（默认值 ：0×0 代表「没有限制」，16777215×... 是 Qt 里的「无限大」）

（5）`sizeIncrement` / `baseSize`

描述（sizeIncrement）：每次调整大小的「步长」，比如10*10，每次变化+-10

描述（baseSize）：控件的「基础大小」

（6）palette

描述：控件的「调色板」，控制颜色（默认是「继承」，跟着父控件的颜色走）

（7）`font`

描述：控件的文字样式

.....

字距调整：控制字符之间的间距（勾选表示启用自定义字距，未勾选则使用字体默认间距）

Weight：字体的粗细程度

HintingPreference： (字体微调偏好)微调是为了让字体在低分辨率屏幕上更清晰、对齐像素网格）

（8）cursor

描述：鼠标移到控件上时，光标的样式

（9）mouseTracking

描述：

勾选时 ：鼠标在控件上移动就会触发「鼠标移动事件」
取消时 ：只有按住鼠标左键移动才会触发事件（默认）

（10）tabletTracking

描述：控制是否跟踪数位板笔的悬停移动

（11）focusPolicy

描述：控件能不能「获得焦点」（获得焦点后才能接收键盘输入）

NoFocus：不能获得焦点（比如 QLabel 标签，本来就不需要输入）
ClickFocus：点击控件才获得焦点（比如 QPushButton 按钮）
TabFocus：按 Tab 键才能获得焦点
StrongFocus：点击 + Tab 都能获得焦点

（12）`contextMenuPolicy`

描述：右键菜单的策略

DefaultContextMenu ：右键点击控件时，会触发 customContextMenuRequested 信号，你可以自己做右键菜单（比如文本框的「复制 / 粘贴」）
NoContextMenu：没有右键菜单，右键点了没反应

（13）acceptDrops

描述：

勾选时：程序运行后控件接受「拖放」（比如把文件拖到文本框里，自动打开文件）
取消时：不能拖放东西进来

（14）windowTitle

描述：窗口标题

（15）windowIcon

描述：窗口图标

（16）windowOpacity

描述：窗口的透明度

（17）`toolTip` / `toolTipDuration`

描述：

toolTip：鼠标悬停在控件上时，弹出的小提示文字
toolTipDuration：提示文字显示多久，-1 就是「鼠标移走就消失」

（18）`statusTip`

描述：控件获得焦点时，状态栏显示的提示文字

（19）whatsthis

描述：

通俗解释：给控件加 "详细帮助说明"

使用场景：当用户在程序里按Shift+F1，再点击这个控件时，会弹出你设置的这段说明文字

澄清/注释：开发者备注栏，程序运行时不显示

（20）`accessibleName` / `accessibleDescription /` accessibleIdentifier

描述：无障碍功能，给「屏幕阅读器」用的（冷门）

对应的程度：（简短、详细、该控件的唯一标识）

（20）layoutDirection

描述：控件内容排列方式

LeftToRight：从左到右布局
RightToLeft：从右到左布局

（21）autoFillBackground

描述：控制控件是否 "自动填充背景色"（覆盖默认的透明 / 系统背景）

（22）styleSheet

描述：给控件 "设置样式"

（23）locale

描述：区域设置，影响「日期 / 数字 / 货币」的显示格式

（24）windowFilePath

描述：窗口关联的文件路径（如文本编辑器窗口打开了 test.txt，这里就存这个路径）（冷门）

（25）inputMethodHints

描述：给输入法的提示，如 ImhDigitsOnly 就是「只能输入数字」，输入法会自动切换到数字模式

（26）windowModality

描述：模态与非模态（是否阻塞其他窗口操作）

五、ui 底层界面解读

我们主要学习下面这块区域：

（1）Action Editor

描述：编辑「动作」（比如菜单栏的「打开」「保存」，工具栏的图标按钮）

（2）Signals_Slots Editor

描述：让界面「活起来」，比如点按钮要做什么、输入框改了要触发什么（可视化信号操作）

（3）新建动作

Checkable：这个动作是不是「开关型」（勾选后保持状态）

Shortcut：这个动作的快捷键

icon theme：图标的主题

注意：QAction是操作指令，不是控件，可以理解为某种信号，被其他控件复用（通过connect）

如果要实现这个指令的逻辑，可以选中它实现槽函数

（4）可视化信号操作

F4：进入可视化信号设计模式

F3：退出这个模式

可视化信号模式：通过长按住某个控件，拖动到其它控件，可以完成" connect 四个参数"

例如：那么底下这个signals slots 就是显示当前连接的目标

六、常用的快捷键及方法

（1）启动项目

Ctrl+R

（2）预览项目

Alt+Shift+R

（3）搜索

Ctrl+F（如果要高级查找，在右下角选择 advanced（高级））

（4）快速跳转到.cpp.h

先选中这个函数/类，然后F4

（5）跳转到对应文档

选中某个函数/类，然后F1

（6）如何查看对应QT版本

工具 -> 选项 ->Kits ->QT Versions

（7）查看编码方式

工具 -> 选项 -> 文本编辑器 -> 行为

七、"项目"解读

（1）Active Project（当前激活项目）

（2）Build & Run（构建与运行）

构建：把你源码编译从可以运行的 .exe 程序

运行：运行程序

（1）构建

clone：将现在的配置复制一遍

删除/重命名：管理构建场景，比如 clone / 添加了一个配置，进行删除/重命名

（相当于在构建的时候按照你的构建设置来进行，设置多个版本）

Shadow build：把编译产生的中间文件和.exe放到单独文件夹，不和源码混在一起

构建目录：存放编译产物的文件

Build步骤：先由qmake生成对应的makeFile，再由 make执行makefile，生成可执行程序

Clean步骤：要删除的东西，比如可执行程序，makefile文件....

构建环境变量：比如编译器路径、Qt 库路径，可在此导入第三方库

（2）运行

部署：把编译好的.exe和依赖的 Qt 库打包，让用户电脑不用装 Qt 也能运行

运行配置：给运行方式起名字，可创建多个配置（比如一个跑主程序，一个跑测试程序）。

八、git仓库相关操作

（1）自己项目提交到远程仓库

（1）在目的处新建一个仓库

（2）找到你的项目，右键，打开git bash here终端，执行仓库初始化：git init（仅执行一次）

（3）创建一个过滤的文件（根据情况调整）：touch .gitignore，记事本编辑填写以下内容

cpp 复制代码

# Qt编译目录（build开头的文件夹全部忽略）
build-*

# Qt个人配置文件（不要上传，每个人配置不同）
*.pro.user
*.pro.user.*
*.qbs.user
*.qbs.user.*

# Qt编译中间文件
*.moc
moc_*.cpp
qrc_*.cpp
ui_*.h

# 可执行文件/动态库
*.exe
*.dll
*.so

# 系统/临时文件
.DS_Store
Thumbs.db
*.tmp
*.log

（4）设置git全局用户名或者邮箱：

git config --global user.name "你的GitCode用户名"

git config --global user.email "你的GitCode邮箱@xxx.com"

（5）代码加入暂存区：git add .

（6）提交到本地仓库，设置提示词：git commit -m "QWidget_QSS_Study_Ui"

（7）关联远程仓库：

git remote add origin https://gitcode.net/你的账号/QWidget_QSS_Study_Ui.git

（8）把本地master分支重命名为main（和GitCode默认分支一致）： git branch -m master main

也可以在仓库中建新的分支，换成这个新分支也可以

（9）重新推送：git push -u origin main -f

如果需要验证：

（2）修改同事项目并提交分支

注意：他的项目必须是分支，不能是main，先要被他加入开发者权限

（1）先拉取这个分支的最新代码：

cpp 复制代码

# 1. 克隆同事的仓库（替换成实际HTTPS地址，比如https://gitcode.net/colleague/project.git）
git clone https://gitcode.net/同事用户名/项目名.git

# 2. 进入克隆后的项目目录（cd 后面是克隆下来的文件夹名，和项目名一致）
cd 项目名

# 3. 拉取远程所有分支（确保能看到同事的核心分支，比如p**）
git fetch origin

# 4. 切换到同事的核心分支（以p**为例，若为main则替换成main），并关联远程
git checkout -b p** origin/p**

# 5. 拉取该分支的最新代码（关键！确保你的本地代码和同事最新版本一致）
git pull origin p**

（2）创建自己的功能分支

cpp 复制代码

# 创建并切换到自己的功能分支（命名规范：类型/你的名字/功能点，方便同事一眼识别）
git checkout -b fix/Dovis5884/qss_button_style

（3）提交

cpp 复制代码

# 1. 添加修改的文件（. 表示所有修改，实际工作中也可指定文件，比如git add mainwindow.ui）
git add .

# 2. 提交（备注格式：[类型] 分支名：具体修改内容，方便同事/后续自己查记录）
git commit -m "[修复] pjl分支：解决按钮hover状态QSS样式不生效问题"

（4）推送自己的分支（和2的分支名要一致）

cpp 复制代码

# 推送本地功能分支到远程仓库（分支名和本地一致）
git push origin fix/Dovis5884/qss_button_style

（3）如何在VScode可视化操作

（1）直接在VScode的终端中先关联远程仓库：

cpp 复制代码

git remote add origin https://github.com/xxx/xxx.git

如果没有自己的分支：

基于某个远程分支先拷贝（会直接拷贝这个分支的代码）
cpp 复制代码
git checkout -b *** origin/master
或者直接创建新的分支（项目从0写，没有代码）
cpp 复制代码
git checkout -b ***
修改完代码后，在终端依次执行：

第一步：查看改了哪些文件
复制代码
git status
第二步：把改动添加到暂存区
复制代码
git add .
（. 表示所有修改的文件，也可以指定单个文件 git add widget.cpp）

第三步：提交到本地
复制代码
git commit -m "这里写你做了什么修改"
比如：git commit -m "修复了表格显示bug"

第四步：推送到远程（ 把本地当前分支的代码，推送到远程仓库的 ***分支上**）**
cpp 复制代码
git push origin ***

如果有自己的分支：

第一步：切换到自己的分支
cpp 复制代码
git checkout ***
第二步：拉取最新代码（ 拉取P**分支的代码合并过来**）**
cpp 复制代码
git pull origin ***
然后改完代码后提交：
cpp 复制代码
git add .
git commit -m "修改说明"
git push origin ***

九、如何在VScode运行QT项目

（1）qmake

（1）在VScode中执行这两条命令没有问题就可以继续下去：

cpp 复制代码

qmake --version
mingw32-make --version

（2）只需要配置一次：在项目根目录创建（新建文件夹） .vscode/tasks.json：

复制代码

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Qt Project",
      "type": "shell",
      "command": "qmake && mingw32-make -j4",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "cwd": "${workspaceFolder}"
    }
  ]
}

（3）打开VScode的终端，先执行 cmd，然后：

cpp 复制代码

qmake 你的项目名.pro && mingw32-make -j4
release\你的项目名.exe

（2）在VScode中预览ui文件

左下角设置->设置->搜索（qttools.designer）->配置它的路径，比如：

然后点击open this ...........，选择这.ui文件即可，如果需要看Ui代码就点右边这个

十、QT关键语法解读

（1）类的前置声明

前置声明分为两种：一种是Ui里面的，另一种是.cpp这种

如果是Ui里面的，需要用 namespace Ui，编译器会去Ui里面找，例如：

如果是用到其它类，但是非Ui的，就可以直接声明：

（2）qobject_cast

本质：类型转换

原因：Qt 的布局、容器存的都是基类指针（比如QCheckBox存的是QObject或其它基类）

取出来要转换，而 static_cast 如果取出来失败会直接崩溃，qobject_cast会返回 nullptr

例如：

（3）Q_OBJECT

本质：宏，可以使用Qt 的信号槽

原因：

Qt 有一套叫 MOC（元对象编译器） 的机制，它在正式编译前先扫描你的代码，看到 Q_OBJECT 就自动生成一个对应的 .cpp 文件，里面包含信号槽、类型信息等实现代码

加Q_OBJECT场景：类继承自 QObject 且用了信号槽

（4）setUi

作用：立刻创建Qt Designer 里画的所有控件

例如：ui->setupUi(this);

（5）#if

#if、#else、#endif （结束）是 C/C++ 的「预处理指令」，属于条件编译的语法，例如：

cpp 复制代码

#if 条件A
吃(苹果,
#else
吃(香蕉,
#endif
    喝牛奶);

如果条件 A 成立，预处理后变成：吃(苹果, 喝牛奶);
如果条件 A 不成立，预处理后变成：吃(香蕉, 喝牛奶);

#ifdef / #ifndef：专门用来判断「某个宏是否被定义」

QT_VERSION：你正在使用的 Qt 版本号

（6）QSignalMapper

作用举例：

假设你有 3 个开关，分别控制客厅灯、卧室灯、厨房灯：

开关本身只会说「我被按了」（无参信号 clicked()）

你想知道「哪个开关被按了」，才能开对应灯；

QSignalMapper 就是帮你给每个开关贴标签的人：

给开关 1 贴「客厅」→ 按开关 1，翻译官喊「客厅开关被按了」

给开关 2 贴「卧室」→ 按开关 2，翻译官喊「卧室开关被按了」

如何给对应的控建议映射：

映射类型	映射举例代码
字符串	`mapper.setMapping(控件指针, "标签内容");`
整数	`mapper.setMapping(控件指针, 1001);`
对象指针	`mapper.setMapping(控件指针, 任意QObject子类指针);`

如何绑定（控件，控件触发信号，"翻译官"对象，执行处理）：

cpp 复制代码

connect(&btn1, &QPushButton::clicked, &mapper, &QSignalMapper::map);
connect(&btn2, &QPushButton::clicked, &mapper, &QSignalMapper::map);

拿到映射对象：

映射类型	拿映射的信号
字符串	`mappedString(const QString &)`
整数	`mappedInt(int)`
对象指针	`mappedObject(QObject *)`

cpp 复制代码

connect(&mapper, &QSignalMapper::mappedString, [](const QString &tag) { 
                // tag就是我们贴的标签！
                qDebug() << "拿到标签：" << tag;
            });

注意：

QSignalMapper::map 有两个重载版本：
复制代码
void map();                    // 无参版本
void map(QObject *sender);     // 有参版本
当你写 &QSignalMapper::map 时，编译器不知道你要哪一个 ，会报歧义错误。所以需要用 static_cast 明确告诉编译器，比如下面这个是无参版本：
cpp 复制代码
static_cast<void (QSignalMapper::*)()>(&QSignalMapper::map)

十一、弹窗类、工具类的显示

总结：不管是弹窗类还是工具类，在特点的业务场景下显示出来都是：创建实例->show/exec显示

只不过菜单栏的点击信号是：&QAction::triggered

普通按钮的是：.....::clicked