很多朋友在开发自定义 UI 桌面应用时都会遇到同一个瓶颈系统默认的标题栏太“死板”想改样式只能换换颜色换不了结构更实现不了一些品牌化、沉浸式的窗口效果。想要彻底掌控窗口外观最常见的方案就是去掉系统标题栏使用“无边框窗口Frameless Window”然后自己实现拖动、缩放、最大最小化、关闭等交互。这一章的内容在 Qt 学习线路中属于“承上启下”的关键位置既有窗口事件体系的底层原理又有界面布局的综合实战。本文围绕“第五章 事件和无边框窗口 5.2 新建项目、界面布局”的内容带大家从零手动搭建一个无边框窗口项目把项目创建、窗口属性设置、自定义标题栏布局、鼠标事件处理、整体界面布局完整串起来最后附上可直接编译运行的完整代码方便你照着练习和改造。1. 背景与核心概念1.1 无边框窗口为什么要去掉系统标题栏无边框窗口就是把操作系统自带的标题栏、边框隐藏掉只保留窗口的内容区域。这种窗口在音乐播放器、在线会议、聊天工具、截图软件、游戏客户端中非常常见原因是多方面的UI 统一系统标题栏的按钮和文字风格由操作系统决定和应用自身的主题风格往往不一致。去掉之后整个窗口的配色、控件、圆角、阴影可以完全由应用自己控制。交互自由默认标题栏不能嵌入搜索框、头像、标签页等业务控件自绘标题栏则没有这种限制。沉浸体验视频播放器、图片查看器在全屏或自定义状态下往往需要隐藏所有边框和按钮把内容最大化展示。但去掉了系统标题栏并不意味着窗口不再需要“标题栏功能”。恰恰相反移动窗口、双击最大化、关闭窗口这些操作都需要开发者自己通过代码实现。这就是为什么“事件”和“无边框窗口”会出现在同一个章节里。1.2 Qt 事件系统GUI 程序的“神经中枢”Qt 是一个事件驱动框架。所谓“事件驱动”简单说就是程序进入事件循环后并不是一行行顺序执行而是不断接收各种“事件”再分发给对应的控件去处理。常见的 Qt 事件包括事件类型触发场景对应的事件类鼠标按下用户按下鼠标按键QMouseEvent鼠标移动用户按住或移动鼠标QMouseEvent鼠标双击用户快速双击QMouseEvent键盘输入用户按键QKeyEvent重绘窗口内容需要刷新QPaintEvent缩放窗口大小改变QResizeEventQt 事件从产生到处理大体要经历这样一条链路窗口系统产生事件 - QApplication::notify() - QObject::event() - 具体事件处理函数例如 mousePressEvent()对于开发者来说我们通常不关心事件最初是怎么产生的只需要在对应的事件处理函数里编写业务逻辑即可。比如在mousePressEvent里记录鼠标按下的位置在mouseMoveEvent里移动窗口这就是无边框窗口拖动功能的基本原理。1.3 事件与无边框窗口的关系无边框窗口去掉的是“系统提供的外壳”但并没有去掉操作系统对窗口事件的分发能力。我们需要利用事件机制自己重新实现一层“窗口管理逻辑”用鼠标事件实现标题栏拖动。用鼠标双击事件模拟双击系统标题栏最大化。用按钮点击事件实现最小化、最大化、关闭。用QResizeEvent处理窗口变化后的布局更新。用原生窗口事件Windows 下通常是nativeEvent实现边缘缩放、贴边吸附等高级能力。所以学习本章不仅要会“写几行代码把边框隐藏”还要理解事件处理的思路这样遇到“窗口无法拖动”“点击按钮没反应”“最大化状态异常”等问题时才能快速定位根因。2. 环境准备与版本说明2.1 开发环境本文示例以Qt 6.x Qt Creator作为主要开发环境代码中已经做了 Qt 5/Qt 6 的兼容处理使用 Qt 5.15 的读者也可以直接参考。项目说明操作系统Windows / Linux / macOS 均可开发工具Qt CreatorQt 版本以 Qt 6.x 为例兼容 Qt 5.15构建系统CMake编译器MSVC / MinGW / GCC / Clang 均可如果你本机同时安装了多个 Qt 版本建议在 Qt Creator 的“Kit”中选择一个稳定版本。教程代码没有依赖特定编译器特性使用 C17 标准即可。2.2 项目目标在动手之前先明确我们要做出来的效果窗口运行时没有系统标题栏。顶部有一个自定义标题栏包含应用标题、最小化按钮、最大化按钮、关闭按钮。内容区左侧是导航列表右侧是内容切换区域。按住标题栏空白区域可以拖动整个窗口。双击标题栏可以切换最大化/还原状态。点击右上角三个按钮分别执行最小化、最大化、关闭。窗口右下角提供一个QSizeGrip尺寸抓手支持基本缩放。这个项目规模不大但涵盖了“事件 无边框窗口 界面布局”三个核心知识点非常适合作为第五章的学习案例。3. 新建项目与窗口基础设置3.1 使用 Qt Creator 创建 Widgets 项目打开 Qt Creator按以下步骤新建项目点击“文件” → “新建项目”。模板选择“Application” → “Qt Widgets Application”。设置项目名称例如FramelessDemo选择保存路径。构建系统选择 CMake。在类信息页面保持默认的MainWindow类名基类选择QWidget而不是QMainWindow。因为做一个无边框窗口的示例QWidget更干净不需要菜单栏、状态栏等默认结构。当然项目文件也可以在命令行或 IDE 中手动创建。只要最终目录中包含CMakeLists.txt、main.cpp、MainWindow.h、MainWindow.cpp即可。3.2 设置无边框窗口的核心代码创建一个普通的QWidget窗口后默认是有系统标题栏的。去掉它的核心代码只有一行setWindowFlags(Qt::FramelessWindowHint);但直接这样设置出现在任务栏上的窗口会变成一个“无边框裸窗口”并且无法最小化到任务栏。实践中通常这样配合使用setWindowFlags(Qt::FramelessWindowHint | Qt::WindowMinimizeButtonHint);这里解释几个关键点Qt::FramelessWindowHint去掉窗口边框和标题栏。Qt::WindowMinimizeButtonHint保留任务栏窗口入口并让窗口仍然具备最小化语义。Qt::Window这类标志告诉窗口系统这是一个顶层窗口。在MainWindow构造函数中写上该设置后运行程序就能看到没有标题栏的窗口了。不过先别急着运行因为此时窗口还无法移动也关闭不了看起来像“卡死”了。这正好引出无边框窗口的第一个核心矛盾去掉系统标题栏的同时也失去了系统提供的移动和缩放能力必须自己实现。3.3 无边框窗口产生的新问题设置无边框后会立刻遇到三个问题无法拖动鼠标按住窗口任意位置都不会移动因为系统标题栏没了鼠标事件落在了空白控件上。无法缩放默认情况下无边框窗口无法通过拖拽边缘调整大小。无法最小化/最大化系统按钮没了需要自绘按钮。这三个问题分别对应事件处理、布局设计、窗口状态管理。从下一节开始我们先搭建界面布局再通过事件处理把窗口“激活”。4. 界面布局标题栏与内容区域4.1 整体布局规划界面布局的目标是在无边框窗口内部自己实现一个“标题栏 内容区”的应用骨架。整体结构可以用下面的逻辑图表示RootLayout (QVBoxLayout) ├── 自定义标题栏 (QWidget固定高度) │ ├── 窗口标题 QLabel │ ├── 弹簧占位 │ ├── 最小化按钮 QPushButton │ ├── 最大化按钮 QPushButton │ └── 关闭按钮 QPushButton └── 内容区域 (QWidget) ├── 左侧导航 QListWidget └── 右侧页面 QStackedWidget顶部标题栏固定高度例如 48px内容区域占据剩余空间。使用QVBoxLayout作为根布局可以保证窗口大小变化时内容区自动跟随伸缩。4.2 自定义标题栏布局自定义标题栏本质上就是一个QWidget内部使用QHBoxLayout横向排列子控件// 标题栏 m_titleBar new QWidget(this); m_titleBar-setObjectName(titleBar); m_titleBar-setFixedHeight(48); QHBoxLayout *titleLayout new QHBoxLayout(m_titleBar); titleLayout-setContentsMargins(12, 0, 8, 0); titleLayout-setSpacing(6); // 左侧标题 m_titleLabel new QLabel(无边框窗口示例, m_titleBar); // 右侧按钮 m_minButton new QPushButton(—, m_titleBar); m_maxButton new QPushButton(□, m_titleBar); m_closeButton new QPushButton(✕, m_titleBar);布局的关键设计是使用addStretch(1)让标题文本和右侧按钮之间插入一个“弹簧”titleLayout-addWidget(m_titleLabel); titleLayout-addStretch(1); titleLayout-addWidget(m_minButton); titleLayout-addWidget(m_maxButton); titleLayout-addWidget(m_closeButton);addStretch会占据剩余空间的弹性空白区域使三个按钮始终靠右对齐而标题文本靠左排列。4.3 内容区域与导航布局内容区使用QHBoxLayout左侧放QListWidget作为导航菜单右侧放QStackedWidget作为多页面容器QWidget *container new QWidget(this); QHBoxLayout *contentLayout new QHBoxLayout(container); contentLayout-setContentsMargins(16, 16, 16, 16); contentLayout-setSpacing(16); m_navList new QListWidget(container); m_navList-setFixedWidth(200); m_stack new QStackedWidget(container); contentLayout-addWidget(m_navList); contentLayout-addWidget(m_stack, 1);这里的几个布局参数值得展开说明setContentsMargins(16, 16, 16, 16)设置内容区四周的内边距让控件不会紧贴窗口边缘。setSpacing(16)设置子控件之间的间距。addWidget(m_stack, 1)第二个参数是伸缩因子表示右侧内容区会占据所有剩余宽度左侧导航宽度固定为 200px。在QStackedWidget中加入页面时需要保持导航列表和页面的索引一一对应。当左侧菜单选中项变化时右侧页面同步切换connect(m_navList, QListWidget::currentRowChanged, this, MainWindow::onListChanged);槽函数实现void MainWindow::onListChanged(int row) { if (m_stack) { m_stack-setCurrentIndex(row); } }4.4 布局管理中的关键细节使用布局管理器后控件的位置和大小由布局系统自动计算开发者在大多数情况下不需要手动指定坐标。以下三个概念需要掌握边距Margin布局与父容器边缘的距离。根布局的边距通常设为 0因为我们要让标题栏和内容区完全占满窗口。间距Spacing同一布局内相邻控件的间隔。伸缩因子Stretch当布局有多余空间时按比例分配给不同控件。addWidget(widget, 1)表示该控件会尽量扩大。在实际项目中合理的边距和间距能极大提升界面品质。同样的功能边距混乱和边距统一的界面观感差距很明显。5. 事件处理窗口交互的核心界面布局搭建好之后窗口还是静态的。这一节通过事件处理实现无边框窗口的“灵魂操作”拖动、双击最大化、按钮控制。5.1 鼠标按下、移动、松开与窗口拖动窗口拖动的原理并不复杂鼠标按下时记录鼠标全局坐标和窗口左上角坐标之间的偏移量。鼠标移动时用当前鼠标全局坐标减去偏移量得到窗口新位置然后调用move()移动窗口。鼠标松开时停止拖动。对应代码是重写主窗口的三个鼠标事件void MainWindow::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { m_dragging true; m_dragOffset mouseGlobalPos(event) - frameGeometry().topLeft(); event-accept(); return; } } QWidget::mousePressEvent(event); }这里有两个细节需要说明mouseLocalPos(event)返回鼠标在 MainWindow 中的坐标m_titleBar-geometry().contains(local)用来判断鼠标是否落在标题栏区域内避免在内容区拖动时误移动窗口。frameGeometry().topLeft()是窗口左上角的全局坐标而不是pos()。对于普通窗口两者差别不大但区别在于frameGeometry()反映的是包含边框的真实窗口位置。移动事件void MainWindow::mouseMoveEvent(QMouseEvent *event) { if (m_dragging (event-buttons() Qt::LeftButton)) { if (m_maximized) { m_dragging false; event-accept(); return; } move(mouseGlobalPos(event) - m_dragOffset); event-accept(); return; } QWidget::mouseMoveEvent(event); }这里做了一个简单限制窗口处于最大化状态时不允许拖动保证交互不至于混乱。工程上很多软件在最大化状态下按住标题栏拖动时会自动“拖拽还原”这是一个更复杂的交互细节后面最佳实践部分会讲到。松开事件void MainWindow::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton m_dragging) { m_dragging false; event-accept(); return; } QWidget::mouseReleaseEvent(event); }5.2 双击标题栏切换最大化和还原双击标题栏实现最大化是模仿 Windows 系统的标准交互。实现方式是重写mouseDoubleClickEvent判断鼠标双击位置是否在标题栏区域内void MainWindow::mouseDoubleClickEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { onMaximizeClicked(); event-accept(); return; } } QWidget::mouseDoubleClickEvent(event); }双击事件和按下事件是独立的不需要在主窗口里手动去“区分单击还是双击”。这也是 Qt 事件系统对开发者友好的地方系统已经帮你完成了底层判断。5.3 按钮点击与窗口状态切换最大化/还原的逻辑可以用一句话概括如果当前不是最大化状态记录当前窗口几何位置然后扩大到屏幕可用区域如果已经是最大化状态恢复到之前记录的几何位置。void MainWindow::onMaximizeClicked() { if (m_maximized) { setGeometry(m_normalGeometry); m_maximized false; } else { m_normalGeometry geometry(); m_maximized true; #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) setGeometry(screen()-availableGeometry()); #else setGeometry(QApplication::desktop()-availableGeometry(this)); #endif } updateMaximizeButton(); }这里有一个常见误区直接使用showMaximized()可以实现窗口最大化但对于无边框窗口来说最大化后位置和尺寸可能不符合预期而且可以从最大化状态“拖拽还原”。自己记录m_normalGeometry并手动设置几何区域控制力更强也更容易理解状态变化的本质。最小化和关闭按钮的实现最简单void MainWindow::onMinimizeClicked() { showMinimized(); } void MainWindow::onCloseClicked() { close(); }5.4 接触与忽略事件冒泡的 Qt 版本很多前端开发者接触过“事件冒泡”这个概念实际上 Qt 中也有类似机制只不过名字叫“事件的向上传播”。当鼠标事件发生在一个子控件上时Qt 会先把事件发送给最内层的控件。如果该控件的事件处理函数调用了event-ignore()那么事件就会继续向上传播给父控件如果调用了event-accept()传播就会停止。看下面这个例子void MainWindow::mousePressEvent(QMouseEvent *event) { event-accept(); // 事件到此结束不会继续向上传播 }在标题栏拖动逻辑中我们调用event-accept()是有意为之。假如标题栏是一个独立控件并且它自己也处理了鼠标事件那么主窗口的mousePressEvent可能根本收不到事件。这也是很多初学者遇到“为什么我重写了主窗口事件但没反应”的原因之一。5.5 使用 QSizeGrip 提供基础缩放无边框窗口去掉边框后系统不会提供边缘缩放能力。最简单快捷的替代方案是在窗口右下角放一个QSizeGrip。创建QSizeGrip后它并不放入布局而是手动定位到窗口右下角m_sizeGrip new QSizeGrip(this); m_sizeGrip-resize(m_sizeGrip-sizeHint());然后在窗口大小变化时更新位置void MainWindow::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); if (m_sizeGrip) { m_sizeGrip-move(width() - m_sizeGrip-width() - 4, height() - m_sizeGrip-height() - 4); } }QSizeGrip的优点是代码量小几乎开箱即用缺点是只能从右下角调整大小不如原生窗口那样支持四个边和四个角。生产环境通常要配合系统原生事件实现完整的缩放边框这个话题在下文最佳实践部分展开。6. 完整可运行代码下面给出整个示例的完整代码包含三个文件读者可以直接复制到本地项目中编译运行。6.1 CMake 构建文件文件路径CMakeLists.txtcmake_minimum_required(VERSION 3.16) project(FramelessDemo VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) # 以 Qt6 为主如果本机只有 Qt5请将 Qt6 替换为 Qt5 find_package(Qt6 REQUIRED COMPONENTS Widgets) add_executable(FramelessDemo main.cpp MainWindow.h MainWindow.cpp ) target_link_libraries(FramelessDemo PRIVATE Qt6::Widgets)6.2 main.cpp文件路径main.cpp#include MainWindow.h #include QApplication int main(int argc, char *argv[]) { QApplication app(argc, argv); MainWindow window; window.show(); return app.exec(); }6.3 MainWindow.h文件路径MainWindow.h#pragma once #include QWidget class QLabel; class QPushButton; class QListWidget; class QStackedWidget; class QSizeGrip; class QMouseEvent; class QResizeEvent; class MainWindow : public QWidget { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); protected: void mousePressEvent(QMouseEvent *event) override; void mouseMoveEvent(QMouseEvent *event) override; void mouseReleaseEvent(QMouseEvent *event) override; void mouseDoubleClickEvent(QMouseEvent *event) override; void resizeEvent(QResizeEvent *event) override; private: void setupUi(); void setupTitleBar(); QWidget *setupContent(); void updateMaximizeButton(); private slots: void onMinimizeClicked(); void onMaximizeClicked(); void onCloseClicked(); void onListChanged(int row); private: QWidget *m_titleBar nullptr; QLabel *m_titleLabel nullptr; QPushButton *m_minButton nullptr; QPushButton *m_maxButton nullptr; QPushButton *m_closeButton nullptr; QListWidget *m_navList nullptr; QStackedWidget *m_stack nullptr; QSizeGrip *m_sizeGrip nullptr; bool m_dragging false; QPoint m_dragOffset; bool m_maximized false; QRect m_normalGeometry; };6.4 MainWindow.cpp文件路径MainWindow.cpp#include MainWindow.h #include QApplication #include QHBoxLayout #include QLabel #include QListWidget #include QMouseEvent #include QPushButton #include QResizeEvent #include QSizeGrip #include QStackedWidget #include QVBoxLayout #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) #include QDesktopWidget #endif namespace { QPoint mouseGlobalPos(QMouseEvent *event) { #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) return event-globalPosition().toPoint(); #else return event-globalPos(); #endif } QPoint mouseLocalPos(QMouseEvent *event) { #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) return event-position().toPoint(); #else return event-pos(); #endif } } // namespace MainWindow::MainWindow(QWidget *parent) : QWidget(parent) { setObjectName(mainWindow); setWindowTitle(无边框窗口示例 - 事件与界面布局); resize(960, 600); setMinimumSize(800, 400); setWindowFlags(Qt::FramelessWindowHint | Qt::WindowMinimizeButtonHint); setStyleSheet(QWidget#mainWindow { background-color: #f5f6fa; }); setupUi(); } void MainWindow::setupUi() { QVBoxLayout *rootLayout new QVBoxLayout(this); rootLayout-setContentsMargins(0, 0, 0, 0); rootLayout-setSpacing(0); setupTitleBar(); QWidget *content setupContent(); rootLayout-addWidget(m_titleBar); rootLayout-addWidget(content, 1); } void MainWindow::setupTitleBar() { m_titleBar new QWidget(this); m_titleBar-setObjectName(titleBar); m_titleBar-setFixedHeight(48); m_titleBar-setStyleSheet( QWidget#titleBar { background-color: white; border-bottom: 1px solid #e4e7ed; }); QHBoxLayout *titleLayout new QHBoxLayout(m_titleBar); titleLayout-setContentsMargins(12, 0, 8, 0); titleLayout-setSpacing(6); m_titleLabel new QLabel(无边框窗口示例, m_titleBar); m_titleLabel-setStyleSheet(font-size: 15px; font-weight: bold; color: #303133;); m_minButton new QPushButton(—, m_titleBar); m_maxButton new QPushButton(□, m_titleBar); m_closeButton new QPushButton(✕, m_titleBar); QListQPushButton * buttons {m_minButton, m_maxButton, m_closeButton}; for (QPushButton *button : buttons) { button-setFixedSize(36, 28); button-setFocusPolicy(Qt::NoFocus); button-setCursor(Qt::PointingHandCursor); button-setStyleSheet( QPushButton { border: none; border-radius: 4px; background: transparent; color: #303133; font-size: 14px; } QPushButton:hover { background: #e4e7ed; }); } m_closeButton-setStyleSheet( QPushButton { border: none; border-radius: 4px; background: transparent; color: #303133; font-size: 14px; } QPushButton:hover { background: #e81123; color: white; }); titleLayout-addWidget(m_titleLabel); titleLayout-addStretch(1); titleLayout-addWidget(m_minButton); titleLayout-addWidget(m_maxButton); titleLayout-addWidget(m_closeButton); connect(m_minButton, QPushButton::clicked, this, MainWindow::onMinimizeClicked); connect(m_maxButton, QPushButton::clicked, this, MainWindow::onMaximizeClicked); connect(m_closeButton, QPushButton::clicked, this, MainWindow::onCloseClicked); } QWidget *MainWindow::setupContent() { QWidget *container new QWidget(this); QHBoxLayout *contentLayout new QHBoxLayout(container); contentLayout-setContentsMargins(16, 16, 16, 16); contentLayout-setSpacing(16); m_navList new QListWidget(container); m_navList-setFixedWidth(200); m_navList-setStyleSheet( QListWidget { background-color: white; border: none; border-radius: 8px; padding: 8px; } QListWidget::item { height: 40px; padding-left: 12px; border-radius: 6px; } QListWidget::item:selected { background-color: #409eff; color: white; } QListWidget::item:hover:!selected { background-color: #f0f2f5; }); m_stack new QStackedWidget(container); m_stack-setStyleSheet( QStackedWidget { background-color: white; border-radius: 8px; }); QStringList pages {首页, 数据统计, 系统设置, 关于}; for (const QString name : pages) { QWidget *page new QWidget(m_stack); QVBoxLayout *pageLayout new QVBoxLayout(page); QLabel *label new QLabel(name, page); label-setAlignment(Qt::AlignCenter); label-setStyleSheet(font-size: 24px; color: #909399;); pageLayout-addWidget(label); m_stack-addWidget(page); m_navList-addItem(name); } contentLayout-addWidget(m_navList); contentLayout-addWidget(m_stack, 1); m_sizeGrip new QSizeGrip(this); m_sizeGrip-resize(m_sizeGrip-sizeHint()); connect(m_navList, QListWidget::currentRowChanged, this, MainWindow::onListChanged); m_navList-setCurrentRow(0); return container; } void MainWindow::onMinimizeClicked() { showMinimized(); } void MainWindow::onMaximizeClicked() { if (m_maximized) { setGeometry(m_normalGeometry); m_maximized false; } else { m_normalGeometry geometry(); m_maximized true; #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) setGeometry(screen()-availableGeometry()); #else setGeometry(QApplication::desktop()-availableGeometry(this)); #endif } updateMaximizeButton(); } void MainWindow::onCloseClicked() { close(); } void MainWindow::onListChanged(int row) { if (m_stack) { m_stack-setCurrentIndex(row); } } void MainWindow::updateMaximizeButton() { if (!m_maxButton) { return; } m_maxButton-setText(m_maximized ? ❐ : □); } void MainWindow::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { m_dragging true; m_dragOffset mouseGlobalPos(event) - frameGeometry().topLeft(); event-accept(); return; } } QWidget::mousePressEvent(event); } void MainWindow::mouseMoveEvent(QMouseEvent *event) { if (m_dragging (event-buttons() Qt::LeftButton)) { if (m_maximized) { m_dragging false; event-accept(); return; } move(mouseGlobalPos(event) - m_dragOffset); event-accept(); return; } QWidget::mouseMoveEvent(event); } void MainWindow::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton m_dragging) { m_dragging false; event-accept(); return; } QWidget::mouseReleaseEvent(event); } void MainWindow::mouseDoubleClickEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { onMaximizeClicked(); event-accept(); return; } } QWidget::mouseDoubleClickEvent(event); } void MainWindow::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); if (m_sizeGrip) { m_sizeGrip-move(width() - m_sizeGrip-width() - 4, height() - m_sizeGrip-height() - 4); } }6.5 运行与验证在 Qt Creator 中点击运行预期效果如下窗口没有系统标题栏。顶部是一段白色背景的自定义标题栏右侧有最小化、最大化、关闭按钮。内容区左侧有“首页”“数据统计”“系统设置”“关于”四个导航项点击后右侧页面同步切换。按住标题栏空白区域拖动窗口跟随移动。双击标题栏空白区域窗口在最大化和还原之间切换。点击关闭按钮窗口正常关闭。7. 常见问题与排查思路无边框窗口涉及事件、布局、窗口系统三个层面学习过程中难免踩坑。下面整理几个高频问题以及排查方向。问题现象常见原因解决思路设置无边框后窗口无法拖动没有重写鼠标事件或鼠标没有落在标题栏区域内检查mousePressEvent、mouseMoveEvent是否生效拖动时窗口闪烁或卡顿事件处理中频繁移动窗口触发大量重绘减少不必要的update()或考虑拖动时使用窗口快照最大化后再拖动窗口位置错乱最大化状态下没有处理“拖动还原”逻辑判断m_maximized状态先还原再移动双击标题栏没有反应双击位置判断错误或子控件吞掉了事件检查双击坐标是否在标题栏几何范围内按钮点击无效按钮被其他控件遮挡或事件被父窗口拦截使用调试工具查看点击区域调整布局层级无边框窗口没有阴影系统标题栏产生的阴影被去掉了使用QGraphicsDropShadowEffect或自绘阴影右下角缩放后布局错乱未在resizeEvent中更新QSizeGrip位置确保resizeEvent中调用m_sizeGrip-move(...)最大化后按钮图标没变化没有在状态切换后更新按钮文本调用updateMaximizeButton()下面针对其中两个高频问题做稍微详细的说明。为什么设置了无边框窗口还是不能移动最常见的原因是mousePressEvent中判断鼠标位置的方式不对。如果鼠标按在标题栏的子控件比如QLabel上事件可能被该子控件消费掉主窗口的mousePressEvent根本不会触发。解决办法有两种让标题栏及其子控件都忽略鼠标事件使事件向上传播到 MainWindow。判断时使用窗口坐标系中的全局坐标而不是控件自带的局部坐标。本文示例中标题栏本身也是一个子控件但 MainWindow 的mousePressEvent依然能收到事件是因为QLabel默认不处理鼠标按下事件。如果你换成QPushButton或者其他会消费事件的控件情况就会不同这也是为什么需要理解“事件接受与忽略”的原因。为什么无边框窗口无法像系统窗口那样随意缩放无边框窗口并不是真的无法缩放而是缩放功能没人实现了。QSizeGrip只是最基本的一个尺寸抓手。如果希望像原生窗口一样支持四边、四角拖拽缩放需要操作系统级的事件配合Windows 系统上通常在nativeEvent中处理WM_NCHITTEST消息根据鼠标位置返回不同的命中区域比如HTLEFT、HTRIGHT、HTTOP、HTBOTTOM等。macOS 系统上窗口的边角缩放更多依赖原生窗口实现简单无边框实现往往不完美。Linux 平台则需要结合桌面环境特性处理。所以生产环境的无边框窗口方案通常会封装一套跨平台的原生事件处理逻辑而不是只依赖QSizeGrip。8. 最佳实践与工程建议8.1 将标题栏封装为独立控件本文为了讲清原理把标题栏相关代码直接写在了MainWindow中。但在实际工程中标题栏往往是多个页面公用的建议把它封装成一个独立的TitleBar控件通过信号与槽与主窗口通信TitleBar 发出信号: minimizeClicked / maximizeClicked / closeClicked MainWindow 接收信号: showMinimized() / toggleMaximize() / close()这样做的好处很明显如果标题栏要支持不同主题、不同按钮状态只需要修改TitleBar内部实现主窗口不需要跟着变。8.2 生产环境还需考虑阴影、圆角和边缘缩放无边框窗口去掉了系统边框同时也去掉了阴影和圆角效果。生产级应用通常需要额外处理使用QGraphicsDropShadowEffect为窗口添加阴影。使用QPainter自绘窗口背景绘制圆角矩形。处理窗口最大化时圆角是否隐藏的问题。实现完整的边缘缩放逻辑。这里提醒一句阴影和圆角会引入透明度、重绘效率等问题需要根据应用平台做取舍。不要盲目给每个窗口都套一层复杂效果。8.3 事件处理中的性能和边界问题无边框窗口的拖动和缩放非常高频事件函数会被频繁调用。以下几条建议值得重视拖动过程中不要频繁创建对象避免不必要的内存分配。窗口移动使用move()即可但不要在该函数里做耗时操作。处理触摸屏场景时需要额外关注QTouchEvent。如果应用要跑在触摸设备上单靠QMouseEvent可能无法获得理想的跟手体验。高 DPI 屏幕下坐标换算容易出问题建议使用 Qt 高 DPI 缩放机制并在多个分辨率的设备上测试。8.4 合理使用事件过滤器除了重写事件函数Qt 还提供eventFilter事件过滤器。在某些场景下事件过滤器可以让代码更集中。例如为标题栏安装事件过滤器在主窗口统一处理所有标题栏子控件的事件。但事件过滤器是把双刃剑使用过多会让事件流向变得难以追踪排查问题时更费劲。我的建议是能用重写事件函数解决就不优先使用事件过滤器多个控件需要相同事件处理时再考虑事件过滤器。8.5 多平台差异与兼容性无边框窗口在不同操作系统上的表现差异很大Windows无边框窗口表现最“自由”同时需要自己处理的东西也最多。macOS系统对窗口管理限制较多去掉标题栏后可能影响原生拖拽、全屏等能力。Linux不同桌面环境对窗口装饰的支持不一致同样代码在不同发行版上效果可能不同。因此跨平台项目在选择无边框窗口方案之前一定要先确认目标平台范围。如果只做 Windows 客户端用FramelessWindowHint nativeEvent通常是性价比最高的组合。第五章“事件和无边框窗口”不是理论堆砌而是一套非常完整的桌面开发基本功。从新建一个最简单的 Widgets 项目开始到设置无边框属性、搭建自定义标题栏、使用布局管理器组织内容区域再到通过鼠标事件实现窗口拖动和最大最小化这整个流程串起来后你对 Qt 的“事件驱动”和“布局系统”会有一个质的理解提升。建议大家在跑通本文示例后动手做两个小改造第一把标题栏封装成独立控件并扩展出窗口阴影和圆角效果第二尝试处理最大化状态下拖拽标题栏自动还原到普通窗口的交互逻辑。这两个改造做完你对无边框窗口的理解会更深。如果实现过程中遇到问题欢迎在评论区贴出代码和报错信息一起交流。 Qt无边框窗口实战：事件处理与自定义界面布局
很多朋友在开发自定义 UI 桌面应用时都会遇到同一个瓶颈系统默认的标题栏太“死板”想改样式只能换换颜色换不了结构更实现不了一些品牌化、沉浸式的窗口效果。想要彻底掌控窗口外观最常见的方案就是去掉系统标题栏使用“无边框窗口Frameless Window”然后自己实现拖动、缩放、最大最小化、关闭等交互。这一章的内容在 Qt 学习线路中属于“承上启下”的关键位置既有窗口事件体系的底层原理又有界面布局的综合实战。本文围绕“第五章 事件和无边框窗口 5.2 新建项目、界面布局”的内容带大家从零手动搭建一个无边框窗口项目把项目创建、窗口属性设置、自定义标题栏布局、鼠标事件处理、整体界面布局完整串起来最后附上可直接编译运行的完整代码方便你照着练习和改造。1. 背景与核心概念1.1 无边框窗口为什么要去掉系统标题栏无边框窗口就是把操作系统自带的标题栏、边框隐藏掉只保留窗口的内容区域。这种窗口在音乐播放器、在线会议、聊天工具、截图软件、游戏客户端中非常常见原因是多方面的UI 统一系统标题栏的按钮和文字风格由操作系统决定和应用自身的主题风格往往不一致。去掉之后整个窗口的配色、控件、圆角、阴影可以完全由应用自己控制。交互自由默认标题栏不能嵌入搜索框、头像、标签页等业务控件自绘标题栏则没有这种限制。沉浸体验视频播放器、图片查看器在全屏或自定义状态下往往需要隐藏所有边框和按钮把内容最大化展示。但去掉了系统标题栏并不意味着窗口不再需要“标题栏功能”。恰恰相反移动窗口、双击最大化、关闭窗口这些操作都需要开发者自己通过代码实现。这就是为什么“事件”和“无边框窗口”会出现在同一个章节里。1.2 Qt 事件系统GUI 程序的“神经中枢”Qt 是一个事件驱动框架。所谓“事件驱动”简单说就是程序进入事件循环后并不是一行行顺序执行而是不断接收各种“事件”再分发给对应的控件去处理。常见的 Qt 事件包括事件类型触发场景对应的事件类鼠标按下用户按下鼠标按键QMouseEvent鼠标移动用户按住或移动鼠标QMouseEvent鼠标双击用户快速双击QMouseEvent键盘输入用户按键QKeyEvent重绘窗口内容需要刷新QPaintEvent缩放窗口大小改变QResizeEventQt 事件从产生到处理大体要经历这样一条链路窗口系统产生事件 - QApplication::notify() - QObject::event() - 具体事件处理函数例如 mousePressEvent()对于开发者来说我们通常不关心事件最初是怎么产生的只需要在对应的事件处理函数里编写业务逻辑即可。比如在mousePressEvent里记录鼠标按下的位置在mouseMoveEvent里移动窗口这就是无边框窗口拖动功能的基本原理。1.3 事件与无边框窗口的关系无边框窗口去掉的是“系统提供的外壳”但并没有去掉操作系统对窗口事件的分发能力。我们需要利用事件机制自己重新实现一层“窗口管理逻辑”用鼠标事件实现标题栏拖动。用鼠标双击事件模拟双击系统标题栏最大化。用按钮点击事件实现最小化、最大化、关闭。用QResizeEvent处理窗口变化后的布局更新。用原生窗口事件Windows 下通常是nativeEvent实现边缘缩放、贴边吸附等高级能力。所以学习本章不仅要会“写几行代码把边框隐藏”还要理解事件处理的思路这样遇到“窗口无法拖动”“点击按钮没反应”“最大化状态异常”等问题时才能快速定位根因。2. 环境准备与版本说明2.1 开发环境本文示例以Qt 6.x Qt Creator作为主要开发环境代码中已经做了 Qt 5/Qt 6 的兼容处理使用 Qt 5.15 的读者也可以直接参考。项目说明操作系统Windows / Linux / macOS 均可开发工具Qt CreatorQt 版本以 Qt 6.x 为例兼容 Qt 5.15构建系统CMake编译器MSVC / MinGW / GCC / Clang 均可如果你本机同时安装了多个 Qt 版本建议在 Qt Creator 的“Kit”中选择一个稳定版本。教程代码没有依赖特定编译器特性使用 C17 标准即可。2.2 项目目标在动手之前先明确我们要做出来的效果窗口运行时没有系统标题栏。顶部有一个自定义标题栏包含应用标题、最小化按钮、最大化按钮、关闭按钮。内容区左侧是导航列表右侧是内容切换区域。按住标题栏空白区域可以拖动整个窗口。双击标题栏可以切换最大化/还原状态。点击右上角三个按钮分别执行最小化、最大化、关闭。窗口右下角提供一个QSizeGrip尺寸抓手支持基本缩放。这个项目规模不大但涵盖了“事件 无边框窗口 界面布局”三个核心知识点非常适合作为第五章的学习案例。3. 新建项目与窗口基础设置3.1 使用 Qt Creator 创建 Widgets 项目打开 Qt Creator按以下步骤新建项目点击“文件” → “新建项目”。模板选择“Application” → “Qt Widgets Application”。设置项目名称例如FramelessDemo选择保存路径。构建系统选择 CMake。在类信息页面保持默认的MainWindow类名基类选择QWidget而不是QMainWindow。因为做一个无边框窗口的示例QWidget更干净不需要菜单栏、状态栏等默认结构。当然项目文件也可以在命令行或 IDE 中手动创建。只要最终目录中包含CMakeLists.txt、main.cpp、MainWindow.h、MainWindow.cpp即可。3.2 设置无边框窗口的核心代码创建一个普通的QWidget窗口后默认是有系统标题栏的。去掉它的核心代码只有一行setWindowFlags(Qt::FramelessWindowHint);但直接这样设置出现在任务栏上的窗口会变成一个“无边框裸窗口”并且无法最小化到任务栏。实践中通常这样配合使用setWindowFlags(Qt::FramelessWindowHint | Qt::WindowMinimizeButtonHint);这里解释几个关键点Qt::FramelessWindowHint去掉窗口边框和标题栏。Qt::WindowMinimizeButtonHint保留任务栏窗口入口并让窗口仍然具备最小化语义。Qt::Window这类标志告诉窗口系统这是一个顶层窗口。在MainWindow构造函数中写上该设置后运行程序就能看到没有标题栏的窗口了。不过先别急着运行因为此时窗口还无法移动也关闭不了看起来像“卡死”了。这正好引出无边框窗口的第一个核心矛盾去掉系统标题栏的同时也失去了系统提供的移动和缩放能力必须自己实现。3.3 无边框窗口产生的新问题设置无边框后会立刻遇到三个问题无法拖动鼠标按住窗口任意位置都不会移动因为系统标题栏没了鼠标事件落在了空白控件上。无法缩放默认情况下无边框窗口无法通过拖拽边缘调整大小。无法最小化/最大化系统按钮没了需要自绘按钮。这三个问题分别对应事件处理、布局设计、窗口状态管理。从下一节开始我们先搭建界面布局再通过事件处理把窗口“激活”。4. 界面布局标题栏与内容区域4.1 整体布局规划界面布局的目标是在无边框窗口内部自己实现一个“标题栏 内容区”的应用骨架。整体结构可以用下面的逻辑图表示RootLayout (QVBoxLayout) ├── 自定义标题栏 (QWidget固定高度) │ ├── 窗口标题 QLabel │ ├── 弹簧占位 │ ├── 最小化按钮 QPushButton │ ├── 最大化按钮 QPushButton │ └── 关闭按钮 QPushButton └── 内容区域 (QWidget) ├── 左侧导航 QListWidget └── 右侧页面 QStackedWidget顶部标题栏固定高度例如 48px内容区域占据剩余空间。使用QVBoxLayout作为根布局可以保证窗口大小变化时内容区自动跟随伸缩。4.2 自定义标题栏布局自定义标题栏本质上就是一个QWidget内部使用QHBoxLayout横向排列子控件// 标题栏 m_titleBar new QWidget(this); m_titleBar-setObjectName(titleBar); m_titleBar-setFixedHeight(48); QHBoxLayout *titleLayout new QHBoxLayout(m_titleBar); titleLayout-setContentsMargins(12, 0, 8, 0); titleLayout-setSpacing(6); // 左侧标题 m_titleLabel new QLabel(无边框窗口示例, m_titleBar); // 右侧按钮 m_minButton new QPushButton(—, m_titleBar); m_maxButton new QPushButton(□, m_titleBar); m_closeButton new QPushButton(✕, m_titleBar);布局的关键设计是使用addStretch(1)让标题文本和右侧按钮之间插入一个“弹簧”titleLayout-addWidget(m_titleLabel); titleLayout-addStretch(1); titleLayout-addWidget(m_minButton); titleLayout-addWidget(m_maxButton); titleLayout-addWidget(m_closeButton);addStretch会占据剩余空间的弹性空白区域使三个按钮始终靠右对齐而标题文本靠左排列。4.3 内容区域与导航布局内容区使用QHBoxLayout左侧放QListWidget作为导航菜单右侧放QStackedWidget作为多页面容器QWidget *container new QWidget(this); QHBoxLayout *contentLayout new QHBoxLayout(container); contentLayout-setContentsMargins(16, 16, 16, 16); contentLayout-setSpacing(16); m_navList new QListWidget(container); m_navList-setFixedWidth(200); m_stack new QStackedWidget(container); contentLayout-addWidget(m_navList); contentLayout-addWidget(m_stack, 1);这里的几个布局参数值得展开说明setContentsMargins(16, 16, 16, 16)设置内容区四周的内边距让控件不会紧贴窗口边缘。setSpacing(16)设置子控件之间的间距。addWidget(m_stack, 1)第二个参数是伸缩因子表示右侧内容区会占据所有剩余宽度左侧导航宽度固定为 200px。在QStackedWidget中加入页面时需要保持导航列表和页面的索引一一对应。当左侧菜单选中项变化时右侧页面同步切换connect(m_navList, QListWidget::currentRowChanged, this, MainWindow::onListChanged);槽函数实现void MainWindow::onListChanged(int row) { if (m_stack) { m_stack-setCurrentIndex(row); } }4.4 布局管理中的关键细节使用布局管理器后控件的位置和大小由布局系统自动计算开发者在大多数情况下不需要手动指定坐标。以下三个概念需要掌握边距Margin布局与父容器边缘的距离。根布局的边距通常设为 0因为我们要让标题栏和内容区完全占满窗口。间距Spacing同一布局内相邻控件的间隔。伸缩因子Stretch当布局有多余空间时按比例分配给不同控件。addWidget(widget, 1)表示该控件会尽量扩大。在实际项目中合理的边距和间距能极大提升界面品质。同样的功能边距混乱和边距统一的界面观感差距很明显。5. 事件处理窗口交互的核心界面布局搭建好之后窗口还是静态的。这一节通过事件处理实现无边框窗口的“灵魂操作”拖动、双击最大化、按钮控制。5.1 鼠标按下、移动、松开与窗口拖动窗口拖动的原理并不复杂鼠标按下时记录鼠标全局坐标和窗口左上角坐标之间的偏移量。鼠标移动时用当前鼠标全局坐标减去偏移量得到窗口新位置然后调用move()移动窗口。鼠标松开时停止拖动。对应代码是重写主窗口的三个鼠标事件void MainWindow::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { m_dragging true; m_dragOffset mouseGlobalPos(event) - frameGeometry().topLeft(); event-accept(); return; } } QWidget::mousePressEvent(event); }这里有两个细节需要说明mouseLocalPos(event)返回鼠标在 MainWindow 中的坐标m_titleBar-geometry().contains(local)用来判断鼠标是否落在标题栏区域内避免在内容区拖动时误移动窗口。frameGeometry().topLeft()是窗口左上角的全局坐标而不是pos()。对于普通窗口两者差别不大但区别在于frameGeometry()反映的是包含边框的真实窗口位置。移动事件void MainWindow::mouseMoveEvent(QMouseEvent *event) { if (m_dragging (event-buttons() Qt::LeftButton)) { if (m_maximized) { m_dragging false; event-accept(); return; } move(mouseGlobalPos(event) - m_dragOffset); event-accept(); return; } QWidget::mouseMoveEvent(event); }这里做了一个简单限制窗口处于最大化状态时不允许拖动保证交互不至于混乱。工程上很多软件在最大化状态下按住标题栏拖动时会自动“拖拽还原”这是一个更复杂的交互细节后面最佳实践部分会讲到。松开事件void MainWindow::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton m_dragging) { m_dragging false; event-accept(); return; } QWidget::mouseReleaseEvent(event); }5.2 双击标题栏切换最大化和还原双击标题栏实现最大化是模仿 Windows 系统的标准交互。实现方式是重写mouseDoubleClickEvent判断鼠标双击位置是否在标题栏区域内void MainWindow::mouseDoubleClickEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { onMaximizeClicked(); event-accept(); return; } } QWidget::mouseDoubleClickEvent(event); }双击事件和按下事件是独立的不需要在主窗口里手动去“区分单击还是双击”。这也是 Qt 事件系统对开发者友好的地方系统已经帮你完成了底层判断。5.3 按钮点击与窗口状态切换最大化/还原的逻辑可以用一句话概括如果当前不是最大化状态记录当前窗口几何位置然后扩大到屏幕可用区域如果已经是最大化状态恢复到之前记录的几何位置。void MainWindow::onMaximizeClicked() { if (m_maximized) { setGeometry(m_normalGeometry); m_maximized false; } else { m_normalGeometry geometry(); m_maximized true; #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) setGeometry(screen()-availableGeometry()); #else setGeometry(QApplication::desktop()-availableGeometry(this)); #endif } updateMaximizeButton(); }这里有一个常见误区直接使用showMaximized()可以实现窗口最大化但对于无边框窗口来说最大化后位置和尺寸可能不符合预期而且可以从最大化状态“拖拽还原”。自己记录m_normalGeometry并手动设置几何区域控制力更强也更容易理解状态变化的本质。最小化和关闭按钮的实现最简单void MainWindow::onMinimizeClicked() { showMinimized(); } void MainWindow::onCloseClicked() { close(); }5.4 接触与忽略事件冒泡的 Qt 版本很多前端开发者接触过“事件冒泡”这个概念实际上 Qt 中也有类似机制只不过名字叫“事件的向上传播”。当鼠标事件发生在一个子控件上时Qt 会先把事件发送给最内层的控件。如果该控件的事件处理函数调用了event-ignore()那么事件就会继续向上传播给父控件如果调用了event-accept()传播就会停止。看下面这个例子void MainWindow::mousePressEvent(QMouseEvent *event) { event-accept(); // 事件到此结束不会继续向上传播 }在标题栏拖动逻辑中我们调用event-accept()是有意为之。假如标题栏是一个独立控件并且它自己也处理了鼠标事件那么主窗口的mousePressEvent可能根本收不到事件。这也是很多初学者遇到“为什么我重写了主窗口事件但没反应”的原因之一。5.5 使用 QSizeGrip 提供基础缩放无边框窗口去掉边框后系统不会提供边缘缩放能力。最简单快捷的替代方案是在窗口右下角放一个QSizeGrip。创建QSizeGrip后它并不放入布局而是手动定位到窗口右下角m_sizeGrip new QSizeGrip(this); m_sizeGrip-resize(m_sizeGrip-sizeHint());然后在窗口大小变化时更新位置void MainWindow::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); if (m_sizeGrip) { m_sizeGrip-move(width() - m_sizeGrip-width() - 4, height() - m_sizeGrip-height() - 4); } }QSizeGrip的优点是代码量小几乎开箱即用缺点是只能从右下角调整大小不如原生窗口那样支持四个边和四个角。生产环境通常要配合系统原生事件实现完整的缩放边框这个话题在下文最佳实践部分展开。6. 完整可运行代码下面给出整个示例的完整代码包含三个文件读者可以直接复制到本地项目中编译运行。6.1 CMake 构建文件文件路径CMakeLists.txtcmake_minimum_required(VERSION 3.16) project(FramelessDemo VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) # 以 Qt6 为主如果本机只有 Qt5请将 Qt6 替换为 Qt5 find_package(Qt6 REQUIRED COMPONENTS Widgets) add_executable(FramelessDemo main.cpp MainWindow.h MainWindow.cpp ) target_link_libraries(FramelessDemo PRIVATE Qt6::Widgets)6.2 main.cpp文件路径main.cpp#include MainWindow.h #include QApplication int main(int argc, char *argv[]) { QApplication app(argc, argv); MainWindow window; window.show(); return app.exec(); }6.3 MainWindow.h文件路径MainWindow.h#pragma once #include QWidget class QLabel; class QPushButton; class QListWidget; class QStackedWidget; class QSizeGrip; class QMouseEvent; class QResizeEvent; class MainWindow : public QWidget { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); protected: void mousePressEvent(QMouseEvent *event) override; void mouseMoveEvent(QMouseEvent *event) override; void mouseReleaseEvent(QMouseEvent *event) override; void mouseDoubleClickEvent(QMouseEvent *event) override; void resizeEvent(QResizeEvent *event) override; private: void setupUi(); void setupTitleBar(); QWidget *setupContent(); void updateMaximizeButton(); private slots: void onMinimizeClicked(); void onMaximizeClicked(); void onCloseClicked(); void onListChanged(int row); private: QWidget *m_titleBar nullptr; QLabel *m_titleLabel nullptr; QPushButton *m_minButton nullptr; QPushButton *m_maxButton nullptr; QPushButton *m_closeButton nullptr; QListWidget *m_navList nullptr; QStackedWidget *m_stack nullptr; QSizeGrip *m_sizeGrip nullptr; bool m_dragging false; QPoint m_dragOffset; bool m_maximized false; QRect m_normalGeometry; };6.4 MainWindow.cpp文件路径MainWindow.cpp#include MainWindow.h #include QApplication #include QHBoxLayout #include QLabel #include QListWidget #include QMouseEvent #include QPushButton #include QResizeEvent #include QSizeGrip #include QStackedWidget #include QVBoxLayout #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) #include QDesktopWidget #endif namespace { QPoint mouseGlobalPos(QMouseEvent *event) { #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) return event-globalPosition().toPoint(); #else return event-globalPos(); #endif } QPoint mouseLocalPos(QMouseEvent *event) { #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) return event-position().toPoint(); #else return event-pos(); #endif } } // namespace MainWindow::MainWindow(QWidget *parent) : QWidget(parent) { setObjectName(mainWindow); setWindowTitle(无边框窗口示例 - 事件与界面布局); resize(960, 600); setMinimumSize(800, 400); setWindowFlags(Qt::FramelessWindowHint | Qt::WindowMinimizeButtonHint); setStyleSheet(QWidget#mainWindow { background-color: #f5f6fa; }); setupUi(); } void MainWindow::setupUi() { QVBoxLayout *rootLayout new QVBoxLayout(this); rootLayout-setContentsMargins(0, 0, 0, 0); rootLayout-setSpacing(0); setupTitleBar(); QWidget *content setupContent(); rootLayout-addWidget(m_titleBar); rootLayout-addWidget(content, 1); } void MainWindow::setupTitleBar() { m_titleBar new QWidget(this); m_titleBar-setObjectName(titleBar); m_titleBar-setFixedHeight(48); m_titleBar-setStyleSheet( QWidget#titleBar { background-color: white; border-bottom: 1px solid #e4e7ed; }); QHBoxLayout *titleLayout new QHBoxLayout(m_titleBar); titleLayout-setContentsMargins(12, 0, 8, 0); titleLayout-setSpacing(6); m_titleLabel new QLabel(无边框窗口示例, m_titleBar); m_titleLabel-setStyleSheet(font-size: 15px; font-weight: bold; color: #303133;); m_minButton new QPushButton(—, m_titleBar); m_maxButton new QPushButton(□, m_titleBar); m_closeButton new QPushButton(✕, m_titleBar); QListQPushButton * buttons {m_minButton, m_maxButton, m_closeButton}; for (QPushButton *button : buttons) { button-setFixedSize(36, 28); button-setFocusPolicy(Qt::NoFocus); button-setCursor(Qt::PointingHandCursor); button-setStyleSheet( QPushButton { border: none; border-radius: 4px; background: transparent; color: #303133; font-size: 14px; } QPushButton:hover { background: #e4e7ed; }); } m_closeButton-setStyleSheet( QPushButton { border: none; border-radius: 4px; background: transparent; color: #303133; font-size: 14px; } QPushButton:hover { background: #e81123; color: white; }); titleLayout-addWidget(m_titleLabel); titleLayout-addStretch(1); titleLayout-addWidget(m_minButton); titleLayout-addWidget(m_maxButton); titleLayout-addWidget(m_closeButton); connect(m_minButton, QPushButton::clicked, this, MainWindow::onMinimizeClicked); connect(m_maxButton, QPushButton::clicked, this, MainWindow::onMaximizeClicked); connect(m_closeButton, QPushButton::clicked, this, MainWindow::onCloseClicked); } QWidget *MainWindow::setupContent() { QWidget *container new QWidget(this); QHBoxLayout *contentLayout new QHBoxLayout(container); contentLayout-setContentsMargins(16, 16, 16, 16); contentLayout-setSpacing(16); m_navList new QListWidget(container); m_navList-setFixedWidth(200); m_navList-setStyleSheet( QListWidget { background-color: white; border: none; border-radius: 8px; padding: 8px; } QListWidget::item { height: 40px; padding-left: 12px; border-radius: 6px; } QListWidget::item:selected { background-color: #409eff; color: white; } QListWidget::item:hover:!selected { background-color: #f0f2f5; }); m_stack new QStackedWidget(container); m_stack-setStyleSheet( QStackedWidget { background-color: white; border-radius: 8px; }); QStringList pages {首页, 数据统计, 系统设置, 关于}; for (const QString name : pages) { QWidget *page new QWidget(m_stack); QVBoxLayout *pageLayout new QVBoxLayout(page); QLabel *label new QLabel(name, page); label-setAlignment(Qt::AlignCenter); label-setStyleSheet(font-size: 24px; color: #909399;); pageLayout-addWidget(label); m_stack-addWidget(page); m_navList-addItem(name); } contentLayout-addWidget(m_navList); contentLayout-addWidget(m_stack, 1); m_sizeGrip new QSizeGrip(this); m_sizeGrip-resize(m_sizeGrip-sizeHint()); connect(m_navList, QListWidget::currentRowChanged, this, MainWindow::onListChanged); m_navList-setCurrentRow(0); return container; } void MainWindow::onMinimizeClicked() { showMinimized(); } void MainWindow::onMaximizeClicked() { if (m_maximized) { setGeometry(m_normalGeometry); m_maximized false; } else { m_normalGeometry geometry(); m_maximized true; #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) setGeometry(screen()-availableGeometry()); #else setGeometry(QApplication::desktop()-availableGeometry(this)); #endif } updateMaximizeButton(); } void MainWindow::onCloseClicked() { close(); } void MainWindow::onListChanged(int row) { if (m_stack) { m_stack-setCurrentIndex(row); } } void MainWindow::updateMaximizeButton() { if (!m_maxButton) { return; } m_maxButton-setText(m_maximized ? ❐ : □); } void MainWindow::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { m_dragging true; m_dragOffset mouseGlobalPos(event) - frameGeometry().topLeft(); event-accept(); return; } } QWidget::mousePressEvent(event); } void MainWindow::mouseMoveEvent(QMouseEvent *event) { if (m_dragging (event-buttons() Qt::LeftButton)) { if (m_maximized) { m_dragging false; event-accept(); return; } move(mouseGlobalPos(event) - m_dragOffset); event-accept(); return; } QWidget::mouseMoveEvent(event); } void MainWindow::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton m_dragging) { m_dragging false; event-accept(); return; } QWidget::mouseReleaseEvent(event); } void MainWindow::mouseDoubleClickEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QPoint local mouseLocalPos(event); if (m_titleBar m_titleBar-geometry().contains(local)) { onMaximizeClicked(); event-accept(); return; } } QWidget::mouseDoubleClickEvent(event); } void MainWindow::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); if (m_sizeGrip) { m_sizeGrip-move(width() - m_sizeGrip-width() - 4, height() - m_sizeGrip-height() - 4); } }6.5 运行与验证在 Qt Creator 中点击运行预期效果如下窗口没有系统标题栏。顶部是一段白色背景的自定义标题栏右侧有最小化、最大化、关闭按钮。内容区左侧有“首页”“数据统计”“系统设置”“关于”四个导航项点击后右侧页面同步切换。按住标题栏空白区域拖动窗口跟随移动。双击标题栏空白区域窗口在最大化和还原之间切换。点击关闭按钮窗口正常关闭。7. 常见问题与排查思路无边框窗口涉及事件、布局、窗口系统三个层面学习过程中难免踩坑。下面整理几个高频问题以及排查方向。问题现象常见原因解决思路设置无边框后窗口无法拖动没有重写鼠标事件或鼠标没有落在标题栏区域内检查mousePressEvent、mouseMoveEvent是否生效拖动时窗口闪烁或卡顿事件处理中频繁移动窗口触发大量重绘减少不必要的update()或考虑拖动时使用窗口快照最大化后再拖动窗口位置错乱最大化状态下没有处理“拖动还原”逻辑判断m_maximized状态先还原再移动双击标题栏没有反应双击位置判断错误或子控件吞掉了事件检查双击坐标是否在标题栏几何范围内按钮点击无效按钮被其他控件遮挡或事件被父窗口拦截使用调试工具查看点击区域调整布局层级无边框窗口没有阴影系统标题栏产生的阴影被去掉了使用QGraphicsDropShadowEffect或自绘阴影右下角缩放后布局错乱未在resizeEvent中更新QSizeGrip位置确保resizeEvent中调用m_sizeGrip-move(...)最大化后按钮图标没变化没有在状态切换后更新按钮文本调用updateMaximizeButton()下面针对其中两个高频问题做稍微详细的说明。为什么设置了无边框窗口还是不能移动最常见的原因是mousePressEvent中判断鼠标位置的方式不对。如果鼠标按在标题栏的子控件比如QLabel上事件可能被该子控件消费掉主窗口的mousePressEvent根本不会触发。解决办法有两种让标题栏及其子控件都忽略鼠标事件使事件向上传播到 MainWindow。判断时使用窗口坐标系中的全局坐标而不是控件自带的局部坐标。本文示例中标题栏本身也是一个子控件但 MainWindow 的mousePressEvent依然能收到事件是因为QLabel默认不处理鼠标按下事件。如果你换成QPushButton或者其他会消费事件的控件情况就会不同这也是为什么需要理解“事件接受与忽略”的原因。为什么无边框窗口无法像系统窗口那样随意缩放无边框窗口并不是真的无法缩放而是缩放功能没人实现了。QSizeGrip只是最基本的一个尺寸抓手。如果希望像原生窗口一样支持四边、四角拖拽缩放需要操作系统级的事件配合Windows 系统上通常在nativeEvent中处理WM_NCHITTEST消息根据鼠标位置返回不同的命中区域比如HTLEFT、HTRIGHT、HTTOP、HTBOTTOM等。macOS 系统上窗口的边角缩放更多依赖原生窗口实现简单无边框实现往往不完美。Linux 平台则需要结合桌面环境特性处理。所以生产环境的无边框窗口方案通常会封装一套跨平台的原生事件处理逻辑而不是只依赖QSizeGrip。8. 最佳实践与工程建议8.1 将标题栏封装为独立控件本文为了讲清原理把标题栏相关代码直接写在了MainWindow中。但在实际工程中标题栏往往是多个页面公用的建议把它封装成一个独立的TitleBar控件通过信号与槽与主窗口通信TitleBar 发出信号: minimizeClicked / maximizeClicked / closeClicked MainWindow 接收信号: showMinimized() / toggleMaximize() / close()这样做的好处很明显如果标题栏要支持不同主题、不同按钮状态只需要修改TitleBar内部实现主窗口不需要跟着变。8.2 生产环境还需考虑阴影、圆角和边缘缩放无边框窗口去掉了系统边框同时也去掉了阴影和圆角效果。生产级应用通常需要额外处理使用QGraphicsDropShadowEffect为窗口添加阴影。使用QPainter自绘窗口背景绘制圆角矩形。处理窗口最大化时圆角是否隐藏的问题。实现完整的边缘缩放逻辑。这里提醒一句阴影和圆角会引入透明度、重绘效率等问题需要根据应用平台做取舍。不要盲目给每个窗口都套一层复杂效果。8.3 事件处理中的性能和边界问题无边框窗口的拖动和缩放非常高频事件函数会被频繁调用。以下几条建议值得重视拖动过程中不要频繁创建对象避免不必要的内存分配。窗口移动使用move()即可但不要在该函数里做耗时操作。处理触摸屏场景时需要额外关注QTouchEvent。如果应用要跑在触摸设备上单靠QMouseEvent可能无法获得理想的跟手体验。高 DPI 屏幕下坐标换算容易出问题建议使用 Qt 高 DPI 缩放机制并在多个分辨率的设备上测试。8.4 合理使用事件过滤器除了重写事件函数Qt 还提供eventFilter事件过滤器。在某些场景下事件过滤器可以让代码更集中。例如为标题栏安装事件过滤器在主窗口统一处理所有标题栏子控件的事件。但事件过滤器是把双刃剑使用过多会让事件流向变得难以追踪排查问题时更费劲。我的建议是能用重写事件函数解决就不优先使用事件过滤器多个控件需要相同事件处理时再考虑事件过滤器。8.5 多平台差异与兼容性无边框窗口在不同操作系统上的表现差异很大Windows无边框窗口表现最“自由”同时需要自己处理的东西也最多。macOS系统对窗口管理限制较多去掉标题栏后可能影响原生拖拽、全屏等能力。Linux不同桌面环境对窗口装饰的支持不一致同样代码在不同发行版上效果可能不同。因此跨平台项目在选择无边框窗口方案之前一定要先确认目标平台范围。如果只做 Windows 客户端用FramelessWindowHint nativeEvent通常是性价比最高的组合。第五章“事件和无边框窗口”不是理论堆砌而是一套非常完整的桌面开发基本功。从新建一个最简单的 Widgets 项目开始到设置无边框属性、搭建自定义标题栏、使用布局管理器组织内容区域再到通过鼠标事件实现窗口拖动和最大最小化这整个流程串起来后你对 Qt 的“事件驱动”和“布局系统”会有一个质的理解提升。建议大家在跑通本文示例后动手做两个小改造第一把标题栏封装成独立控件并扩展出窗口阴影和圆角效果第二尝试处理最大化状态下拖拽标题栏自动还原到普通窗口的交互逻辑。这两个改造做完你对无边框窗口的理解会更深。如果实现过程中遇到问题欢迎在评论区贴出代码和报错信息一起交流。