简介：面向需要实现无边框窗口自定义外观的 C++ Qt 开发者，本工程提供了一个基于 QMainWindow 的完整示例，解决无边框窗口无法拖拽移动、拉伸缩放以及缺少阴影圆角等常见问题。工程在 Win10/Win11 下运行，可呈现窗口阴影与圆角效果。资源压缩包仅 14KB，共 23 个文件，其中 7 个 .cpp 和 6 个 .h 覆盖 TitleBar、ContentWidget、CustomStatusBar 等核心模块，另有 .ui 界面文件、.qrc 资源索引、5 个 .svg 图标以及 Visual Studio 工程配置，方便直接编译与二次修改。已有 699 人学习下载，适合正在学习 Qt 自定义窗口绘制、鼠标事件处理或需要快速集成该功能的开发者参考。通过阅读源码可掌握 QPainter 标题栏绘制、mousePressEvent/mouseMoveEvent 实现拖拽、以及基于 resizeEvent 处理窗口拉伸与圆角的关键写法，能节省不少摸索时间。 做过Qt客户端开发的朋友应该都有这个感觉：默认的标题栏丑且死板，和软件整体风格很难融合。想做一个皮肤好看、看起来专业点的程序，第一步往往就是干掉系统自带标题栏，换成自己画。但无边框之后，窗口拖拽移动、边缘拉伸这些系统自带的行为全部消失，得自己一个个补回来。这篇文章我把整个实现思路、方案选型和踩坑过程完整梳理一遍，代码可以直接抄，原理也会讲清楚，新手老手都能拿走用。
1. 整体方案设计：无边框窗口的三个核心问题
1.1 为什么需要自定义标题栏方案
先聊聊需求本身。自定义标题栏不是为了炫技，而是很多桌面工具类软件的刚需。比如播放器、即时通讯工具、网盘客户端、素材管理软件，它们都会把标题栏和工具栏融合成一条自定义区域，左上角放Logo，中间放搜索框，右上角放最小化、最大化、关闭按钮——这样做出来的界面才有“产品感”。
但系统默认的标题栏是写死在操作系统里的，你没法往里面塞自己的控件，也改不了它的高度和背景。所以常规做法是用Qt::FramelessWindowHint去掉系统边框，然后自己在窗口内部绘制一条“伪标题栏”。问题在于，这个窗口标志只是简单粗暴地把系统边框隐藏了，系统拖拽和resize逻辑也一并被带走。如果不补回来，窗口就变成了一块“僵硬的板子”，用户连移动都做不到，体验会很糟糕。
标题里提到的“可拖拽移动、拉伸改变窗口大小”正是无边框方案的两个核心补全项。我实际测试过，这两个功能看似简单，但细节极多：拖拽时的坐标偏移、拉伸时八个方向的判断、最大化状态下的边界处理、不同系统缩放比例下的像素计算……每一项都藏着坑。下文我会按“移动”和“拉伸”两条主线逐一展开，并把代码和原理一起放出来。
1.2 方案选型：事件重写、nativeEvent还是系统API
实现无边框窗口的拖拽和拉伸，主流有三条技术路线。我分别做一个对比，方便你根据场景选择。
| 方案 | 实现方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 纯Qt事件重写 | 重写mousePressEvent / mouseMoveEvent / mouseReleaseEvent | 跨平台、代码直观、便于阅读维护 | 移动时是全窗口跟随，无法启用系统级Aero Snap；无原生边框过渡动画 | 跨平台工具类软件、自绘UI需求强的场景 |
| 原生API + nativeEvent | Windows下处理WM_NCHITTEST消息，返回HTLeft / HTTOP等 | 系统接管后续拖动与缩放，支持Aero Snap和边缘动画 | 跨平台需重写其他系统实现；需要了解Win32消息机制 | 仅限Windows平台的商业软件 |
| Qt 5.15+ QWindow方法 | 调用startSystemMove / startSystemResize | 官方支持，代码量少，保持原生体验 | 需要自行判断边缘区域；旧版Qt不可用 | 新版Qt项目、想要原生拖动效果 |
我个人建议：如果你是做跨平台工具类软件，以纯Qt事件重写为主；如果只针对Windows发布，可以优先考虑WM_NCHITTEST方案，效果最接近系统原生。本文的重点放在纯Qt事件重写上，因为它控制了所有细节，也方便你在自绘UI里集成全套逻辑。最终方案可以看作“纯Qt事件重写 + 少量系统API补充”。
2. 核心细节解析：拖拽移动的完整实现
2.1 鼠标事件与坐标计算原理
无边框窗口的拖拽移动，本质就是“在鼠标按下时记住偏移量，在鼠标移动时根据偏移量更新窗口位置”。听上去简单，但坐标系的坑很容易踩。
先写一段最核心的代码，作为自定义标题栏控件的基类骨架：
// TitleBar.h #pragma once #include <QWidget> class TitleBar : public QWidget { Q_OBJECT public: explicit TitleBar(QWidget* parent = nullptr); protected: void mousePressEvent(QMouseEvent* event) override; void mouseMoveEvent(QMouseEvent* event) override; void mouseReleaseEvent(QMouseEvent* event) override; private: bool m_dragging = false; QPoint m_dragOffset; // 鼠标按下点相对窗口左上角的偏移 };// TitleBar.cpp #include "TitleBar.h" #include <QMouseEvent> TitleBar::TitleBar(QWidget* parent) : QWidget(parent) { } void TitleBar::mousePressEvent(QMouseEvent* event) { if (event->button() == Qt::LeftButton) { m_dragging = true; // 关键：偏移量用全局坐标减去窗口的frameGeometry左上角 m_dragOffset = event->globalPosition().toPoint() - parentWidget()->frameGeometry().topLeft(); event->accept(); } } void TitleBar::mouseMoveEvent(QMouseEvent* event) { if (m_dragging) { // 更新父窗口位置：全局坐标减去偏移量 QPoint newPos = event->globalPosition().toPoint() - m_dragOffset; parentWidget()->move(newPos); event->accept(); } } void TitleBar::mouseReleaseEvent(QMouseEvent* event) { if (event->button() == Qt::LeftButton) { m_dragging = false; event->accept(); } }这里最关键的是m_dragOffset的计算。很多人第一次写会直接event->pos() - parentWidget()->pos()，但event->pos()是相对TitleBar本身的坐标，parentWidget()->pos()是父窗口相对其父级的坐标。一旦窗口嵌套层级变化，计算就会出错。用globalPosition()和frameGeometry().topLeft()始终保持“全局坐标系”，最稳。
还有一个隐蔽问题：如果你在窗口内部还放了按钮，比如最小化、最大化按钮，这些按钮会优先消费鼠标事件，标题栏的mousePressEvent根本不会触发。所以必须保证这些按钮做event->accept()或者直接放在TitleBar的子控件中并正确传递事件，不让事件穿透到标题栏。我的做法是，按钮自身正常处理，但它们的点击区域不需要拖动功能，因此无需额外处理；而TitleBar的空白区域作为拖拽手柄使用。
2.2 高DPI缩放与多屏场景下的坐标适配
坐标系统还有一个重要的适配问题：高DPI缩放。Windows上如果显示缩放是125%或150%，Qt的physical DPI和logical DPI会出现差异。event->globalPosition()在Qt6里已经返回了逻辑坐标，move()接收的也是逻辑坐标，因此大部分情况下是自洽的。但如果你用了QCursor::pos()或者Win32的GetCursorPos()混用，很容易出现拖拽时窗口偏移、鼠标与标题栏错位的情况。
我的经验是：整个拖拽逻辑里只使用QMouseEvent::globalPosition().toPoint()，不要混用QCursor::pos()，更不要用Win32 API取物理坐标。
多屏场景下，如果副屏的分辨率或缩放比例不同，上述代码依然有效，因为全局坐标本身是跨屏幕统一的。但是要特别注意：如果用户的鼠标在负坐标区域（主屏在左、副屏在右时，副屏左侧是负x），frameGeometry().topLeft()和globalPosition()依然能正确处理，因为它们是带符号的。不要手动取绝对值，否则窗口会在跨屏拖拽时跳变。
2.3 最大限度还原系统拖拽体验
纯Qt的move()方案有一个不小的体验短板：拖动过程中整个窗口只是“贴着手走”，没有系统级的窗口预览、Aero Snap、边缘动画等效果。对于追求细节的软件来说，这会显得不够“原生”。
Qt 5.15之后官方提供了QWindow::startSystemMove()，它可以让你在鼠标按下后把后续拖拽工作交还给系统。但是有个前提：这个接口必须在鼠标按键状态下调用，而且它一旦接管，你就不需要在mouseMoveEvent里手动move()了。实现方式如下：
void TitleBar::mousePressEvent(QMouseEvent* event) { if (event->button() == Qt::LeftButton) { // 需要包含 <QWindow> if (window()->windowHandle()) { window()->windowHandle()->startSystemMove(); event->accept(); return; } } QWidget::mousePressEvent(event); }这样实现的好处是系统会帮你处理移动过程中的边界、Snap等行为。但缺点也很明显：startSystemMove()无法控制拖拽的“手柄区域”，它会从按下位置开始整体移动窗口。如果标题栏里按钮很多，你需要自行判断按下的位置是否是空白区域，否则点击按钮时也会触发窗口拖动，导致按钮点击响应异常。
另外，这个方式在Windows下配合无边框窗口，不会自动开启阴影和系统动画，需要自己补充。所以我在实际项目中，一般优先使用纯Qt事件方案，只有在需要“系统级Aero Snap体验”时才切换成startSystemMove()。
3. 边缘拉伸改变窗口大小：从边缘检测到八方向缩放
3.1 边缘区域划分与光标形状反馈
拉伸窗口的前提是能让用户“知道”哪些地方可以拉。所以第一步是在窗口边缘划定一个“热区”，当鼠标移动到热区时改变光标形状，比如边缘出现左右箭头、上下箭头、对角箭头。
我通常把窗口边缘热区宽度设为8像素（在100%缩放下），这个宽度足够好点中，又不会影响内部布局。划分逻辑如下：
- 左边区域：光标
Qt::SizeHorCursor - 右边区域：光标
Qt::SizeHorCursor - 上边区域：光标
Qt::SizeVerCursor - 下边区域：光标
Qt::SizeVerCursor - 左上角：光标
Qt::SizeFDiagCursor - 右下角：光标
Qt::SizeFDiagCursor - 右上角：光标
Qt::SizeBDiagCursor - 左下角：光标
Qt::SizeBDiagCursor
在窗口中重写mouseMoveEvent，根据鼠标相对窗口的位置判断所处的边缘区域，并动态设置setCursor()。这里必须开启setMouseTracking(true)，否则鼠标在无按键操作时不会持续收到move事件，光标反馈就出不来。
3.2 完整拉伸逻辑：保存基准数据，增量计算新矩形
拉伸窗口的核心方法和拖动移动不同：拖动移动是“位置增量”，拉伸窗口是“几何rect重建”。在鼠标按下时，必须保存以下基准数据：
- 鼠标按下时的全局坐标
- 窗口当前的
QRect（geometry()） - 当前命中的拉伸方向枚举值
在鼠标移动事件里，用当前的全局坐标与保存的基准鼠标坐标做差值，然后基于初始窗口矩形计算新矩形。不能直接在当前窗口矩形上做加减，否则每次移动都会产生误差累积，窗口会“越拉越歪”。
下面的代码只展示核心逻辑，完整的八个方向枚举和判断我已经整理好：
// 拉伸方向 enum class ResizeDir { None, Left, Right, Top, Bottom, TopLeft, TopRight, BottomLeft, BottomRight }; // 在mousePressEvent中记录： // m_resizing = true; // m_resizeDir = hitTest(event->pos()); // 判断鼠标在哪条边上 // m_dragStartGlobal = event->globalPosition().toPoint(); // m_originalRect = window()->geometry();在mouseMoveEvent中：
if (m_resizing) { QPoint delta = event->globalPosition().toPoint() - m_dragStartGlobal; QRect newRect = m_originalRect; switch (m_resizeDir) { case ResizeDir::Left: newRect.setLeft(m_originalRect.left() + delta.x()); break; case ResizeDir::Top: newRect.setTop(m_originalRect.top() + delta.y()); break; case ResizeDir::Right: newRect.setRight(m_originalRect.right() + delta.x()); break; case ResizeDir::Bottom: newRect.setBottom(m_originalRect.bottom() + delta.y()); break; case ResizeDir::TopLeft: newRect.setTopLeft(m_originalRect.topLeft() + delta); break; case ResizeDir::TopRight: newRect.setTopRight(m_originalRect.topRight() + delta); break; case ResizeDir::BottomLeft: newRect.setBottomLeft(m_originalRect.bottomLeft() + delta); break; case ResizeDir::BottomRight: newRect.setBottomRight(m_originalRect.bottomRight() + delta); break; default: break; } window()->setGeometry(newRect); }这段代码的关键在于：所有计算都基于m_originalRect，而不是基于当前窗口的实时位置。这样即便鼠标移动很快，或者中间某次事件没被处理，矩形也是由基准值加增量推导出来的，不会产生累积漂移。
3.3 防止窗口被拉伸到非法尺寸
八方向拉伸还有个很容易忽略的问题：最小尺寸限制。如果用户把窗口拉得特别小，甚至缩成一条线，完全有可能。Qt的setMinimumSize()可以解决一部分问题，但它只约束外部调用，不约束你自己用setGeometry()强行设置的大小。所以在计算 newRect 后，必须手动判断宽高是否过小。
我一般会在处理完方向后，统一执行一次约束检查：
const int minWidth = 400; const int minHeight = 300; if (newRect.width() < minWidth) { // 根据拉伸方向修正基准位置 // 如果拉伸左边，则右边保持不变，左边不能越过 right - minWidth if (m_resizeDir == ResizeDir::Left || m_resizeDir == ResizeDir::TopLeft || m_resizeDir == ResizeDir::BottomLeft) newRect.setLeft(newRect.right() - minWidth + 1); else newRect.setRight(newRect.left() + minWidth - 1); } if (newRect.height() < minHeight) { if (m_resizeDir == ResizeDir::Top || m_resizeDir == ResizeDir::TopLeft || m_resizeDir == ResizeDir::TopRight) newRect.setTop(newRect.bottom() - minHeight + 1); else newRect.setBottom(newRect.top() + minHeight - 1); }这套逻辑相当于把最小尺寸的约束也拆成了“左侧被固定”和“右侧被固定”两种情况，处理方式稍有不同。不加这段代码，用户在快速拖拽时可能出现窗口宽高小于最小值的瞬态，后续再拖动还会出现“弹不回去”的bug。
3.4 nativeEvent方案的取舍
如果你打算在Windows上追求极致的原生体验，可以走nativeEvent路线。思路是重写nativeEvent，拦截WM_NCHITTEST消息，返回Win32的HTLEFT、HTRIGHT、HTTOP、HTBOTTOM、HTTOPLEFT等命中值。这样做的好处是后续的系统缩放、动画、Snap全部自动集成，代码量反而更少。
但缺点也明显：首先是跨平台失效，macOS和Linux需要另外实现；其次是如果你在窗口内部用了自绘阴影或者自绘边框，WM_NCHITTEST这条路线处理起来更复杂，因为命中区域需要和你的自绘视觉效果完全对齐。我做这类功能时，如果只是一个纯Windows工具，会优先考虑nativeEvent；如果是跨平台产品，就老老实实写纯Qt方案，避免维护两套代码。
4. 实操过程：标题栏按钮、阴影与状态细节处理
4.1 最小化、最大化、关闭按钮的实现
自定义标题栏少不了三个功能按钮。坦白说，这三个按钮本身很简单，难点在于统一视觉风格和处理好最大化状态切换。
按钮通常是QPushButton，设置固定大小（如30x30），去掉背景边框，在hover时切换成高亮色，按下时再加深。对于关闭按钮，一般hover时会变成红色背景，这是产品习惯。
一个容易踩坑的地方是：窗口最大化时，系统自带的标题栏会隐藏，但你的自定义标题栏还在。如果你用window()->showMaximized()，你的标题栏高度不变，视觉上完全看不出问题。但如果做成类似“拖动窗口到顶部自动最大化”的效果，就必须在changeEvent里监听WindowStateChange，然后更新标题栏里的按钮图标状态（比如最大化按钮变成还原按钮）以及一些边距处理。
关闭按钮还有一个隐藏考点：如何响应closeEvent。重写主窗口的closeEvent(QCloseEvent* event)，在里面可以决定是否允许关闭，比如弹“是否保存”提示框。你需要在标题栏关闭按钮的槽函数里调用window()->close()，而不是直接qApp->quit()，否则closeEvent里的逻辑永远不会执行。这一点和热词里出现的“qmainwindow关闭响应”是完全对应的。
4.2 无边框窗口的阴影与圆角处理
无边框窗口不只有移动和拉伸的问题，还有一个视觉问题：因为去掉了系统边框，窗口边缘会变得非常生硬，甚至像一块贴图。Windows下常见的做法是给主窗口加一层半透明阴影背景，然后内部再放一个圆角矩形的内容区域。
常用的实现有两个层次：
- 简单方案：用
QGraphicsDropShadowEffect给主窗口设定阴影，优点是代码量极少，缺点是快速拉伸时阴影会和窗口内容脱节，性能一般。 - 稳妥方案：在窗口最外层设置
WA_TranslucentBackground，自行绘制一张带阴影效果的外边框背景，同时内层放一个真正的业务Widget。这套逻辑更复杂，但性能更好，视觉效果可控范围大。
如果你用的是纯Qt事件方案，那么有个经验是：不要给QMainWindow直接加半透明背景，它的内部结构比较复杂，容易导致子控件渲染异常。更稳妥的做法是外层用一个QFrame作为内容容器，给它单独设置setObjectName并写样式表，标题栏和内容区域都放进去，整体视觉效果和裁剪都容易控制。
4.3 拖拽文件与双击标题栏的扩展处理
无边框窗口在标题栏区域拖入文件时，默认是不会接受拖放的。如果你的软件有“拖文件给窗口”的需求，需要在标题栏上启用setAcceptDrops(true)，并重写dragEnterEvent与dropEvent。
有一个来自实际场景的坑：在Qt5的某些版本中，无边框窗口的标题栏拖拽文件会与窗口自身的mouseMoveEvent产生冲突，导致拖入文件时窗口也跟着移动。解决办法是，在dragEnterEvent里设置一个标志位，在mousePressEvent和mouseMoveEvent中检查这个标志，如果正在拖入文件，则忽略移动逻辑。
双击标题栏是另一个常用的系统行为习惯。默认双击标题栏会最大化/还原窗口，如果你不做这个交互，用户会明显感觉到“不原生”。实现方式是在TitleBar里重写mouseDoubleClickEvent：
void TitleBar::mouseDoubleClickEvent(QMouseEvent* event) { if (event->button() == Qt::LeftButton) { QWidget* w = window(); if (w->isMaximized()) w->showNormal(); else w->showMaximized(); } QWidget::mouseDoubleClickEvent(event); }这里有个细节：双击事件出现前，通常已经触发过一次mousePressEvent和一次mouseReleaseEvent，所以你的拖动逻辑要能容忍这种连续事件。如果按下时记录了m_dragging = true，双击的时候要确保第二次press能正确覆盖，或者干脆在doubleClick事件里把m_dragging重置为false，避免出现双击后窗口微微移动一下的劣质感。
5. 常见问题与排查技巧实录
5.1 问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 标题栏无法拖动窗口 | 鼠标事件被子控件拦截 | 确认按钮的event->accept()或标题栏空白区域能收到事件 |
| 拖动时窗口闪烁或残影 | 每帧move时触发布局重算 | 用move()而不是setGeometry()；或临时禁用被拖拽窗口的复杂动画 |
| 拉伸时窗口跳动、不跟手 | 直接在geometry()上加减 | 保存初始矩形，用基准值+增量计算 |
| 边缘光标不变化 | 未开启setMouseTracking(true) | 在窗口构造函数中开启鼠标追踪 |
| 无边框窗口没有阴影 | 系统边框被去掉后不绘制阴影 | 使用QGraphicsDropShadowEffect或自绘半透明背景 |
| Windows下无法贴边最大化 | 纯Qt方案不触发系统Aero Snap | 改用startSystemMove()或WM_NCHITTEST方案 |
| 高DPI下拖动位置偏移 | 混用了逻辑坐标与物理坐标 | 统一使用globalPosition().toPoint() |
| 双击标题栏没有反应 | Widget未设置焦点或者事件被吃掉 | 确保标题栏控件能正常获取鼠标事件，重写mouseDoubleClickEvent |
5.2 调试经验：如何快速定位事件吞吃问题
无边框窗口的事件处理链路比普通窗口复杂。如果你发现某个区域点击没有反应，第一件事不是加打印日志，而是先看这个区域被哪些控件覆盖了。我常用的做法是在mousePressEvent里临时加一行：
qDebug() << "mouse press on" << objectName() << "pos:" << event->position();然后在界面上放一个覆盖全窗口的透明调试层，或者直接对比每个子控件的 geometry 范围。多数情况下，问题出在两个地方：要么是某个子控件把透明背景设置为WA_TransparentForMouseEvents意外的拦截事件，要么是窗口标志里误加了Qt::WindowTransparentForInput。
5.3 性能调优：拖拽过程中的事件风暴
拖动和拉伸本质上都是高频鼠标事件触发布局变更。对于复杂界面，如果每帧都触发全窗口重绘，会出现明显的掉帧现象。我实测下来有两条优化经验：
第一，拖拽移动时，尽量调用move()，它会走高层窗口移动逻辑，不会触发子控件的重排版。而setGeometry()会触发resize事件，如果你的窗口里有复杂的布局计算，成本会高很多。
第二，在拉伸窗口时，如果窗口内部有大面积的自绘内容（比如图片查看器），在resize过程中会频繁触发paintEvent。这时可以把复杂渲染暂时降级，比如只画纯色背景，等鼠标释放后再进行最终高质量重绘。这个做法在图片查看器和绘图工具里效果特别明显。
第三，如果你的窗口使用了QOpenGLWidget或者QGraphicsView，拖拽过程中的帧率更敏感。建议把OpenGL表面更新和窗口移动分离，也就是窗口位置改变时，先只移动容器，不触发OpenGL重绘，等方式稳定后再刷新。
6. 实操总结：完整代码组织与扩展建议
以QMainWindow作为主窗口为例，最常规的组织方式是：
- 主窗口
<QMainWindow>继承类中设置Qt::FramelessWindowHint，关闭系统边框。 - 把
TitleBar作为主窗口的子控件，放在窗口顶部。TitleBar内部包含Logo区、标题文本和三个控制按钮。 - 主窗口的其他内容放在
TitleBar下方的容器中，这个容器占据剩余全部区域。 TitleBar负责处理拖动、双击最大化、按钮点击回调；主窗口MainWindow负责处理resize边缘检测与窗口几何更新。
实际编码时，我一般会把“拖动逻辑”和“拉伸逻辑”分别封装成独立的类，或者用事件过滤器挂到主窗口上，这样多个项目可以复用。尤其建议把resize逻辑独立出来，因为凡是做无边框窗口的项目，迟早都会碰到同样的问题。
最后说一个我在代码里保留的个人习惯：无边框窗口的标志位设置，不要只用Qt::FramelessWindowHint，而建议写成组合标志：
setWindowFlags(Qt::FramelessWindowHint | Qt::WindowMinimizeButtonHint);这样在Windows上至少能保留任务栏中的最小化行为，也避免某些极端情况下窗口在任务栏消失的问题。加不加Qt::Tool需要谨慎，它会让窗口不显示在任务栏，除非你专门做托盘工具，否则不要加。
这些细节都处理好之后，自定义标题栏的无边框窗口用起来就和系统原生窗口没有明显差异了。后面如果你想继续扩展，可以在这个骨架的基础上加上窗口阴影皮肤、主窗口缩放动画、贴边手势识别等功能，底子都是通的。
本文还有配套的精品资源，点击获取
