简介面向需要实现无边框界面效果的 Qt 开发者这份示例工程演示了如何基于 Qt 框架创建可移动、可调整大小的无边框窗口核心功能包括窗口样式设置、自定义标题栏、移动区域控制以及边缘拖拽缩放适用于桌面工具、播放器、启动器等多类自绘界面场景。压缩包内共 18 个文件整体体积约 72KB其中包含 5 个 C 源码文件、4 个头文件、1 个 UI 界面文件、1 个工程文件和 1 个 QRC 资源文件另有 5 张按钮图标与 1 份 CSS 样式表涵盖从工程配置、界面布局到样式修饰的完整环节。目前已有 437 人浏览学习。配套源码结构清晰framelesshelper 辅助类集中处理窗口事件BaseTitleBar 与 CustomMainWindow 则分别展示标题栏绘制和主窗口组装逻辑便于读者直接移植或按需扩展快速为自己的项目加入无边框窗口能力。 QT开发里有个很经典的“真相时刻”界面草图终于定稿配色和布局都满意了结果一运行系统自带的灰色标题栏往上一放整个气质就垮了。这时候十有八九会想到Qt::FramelessWindowHint把边框干掉。但真的去掉了之后第二个问题马上就来窗口拖不动了也拉不大了。默认的系统边框同时承担了“拖动移动”和“边缘缩放”两件事你一旦关掉它这两件事就得自己重新实现。这篇文章就聚焦这一个点如何在QT里做一个支持移动控制和窗口大小调整的自定义无边框窗口。我尽量把实现思路、完整代码、以及实际调试中踩过的坐标系、DPI、最大化的坑都讲清楚。适合正在做桌面客户端自定义标题栏的朋友参考也适合刚开始折腾无边框窗口、被鼠标事件绕晕的人。1. 为什么把系统边框去掉之后麻烦全来了先聊动机。自定义无边框窗口的典型场景是做深色主题、圆角卡片、沉浸式界面或者像播放器、聊天软件一样把标题栏和工具栏融为一体。系统原生的标题栏不仅样式不可控在Windows上还依赖系统主题别人换个主题你的界面就跟着变确实没法忍。但代价是你得自己接管原本由系统处理的行为。这里面最关键的就两个窗口移动和窗口缩放。系统边框在被移除的那一瞬间不会再帮你响应标题栏拖拽也不会再根据鼠标是否贴近窗口边缘来自动切换缩放光标。更隐蔽的是很多人在实现时用错了坐标系导致窗口一拖动就“跳”一下——这就是典型的globalPos()和localPos()混用的问题。另外一个容易被忽略的点是无边框窗口在Windows上和Linux上的表现不一样。Windows下setWindowFlags(Qt::FramelessWindowHint)比较干净但配合一些窗口效果比如阴影、圆角需要额外处理Linux上取决于窗口管理器有时去掉边框后连阴影都一并去掉甚至出现鼠标事件穿透的问题。所以这篇文章我以Windows为主场景来讲但核心代码在Linux上稍微调整也能跑。2. 无边框窗口的基础配置先跑通最小Demo2.1 setWindowFlags 的几个关键选项去掉边框最常用的代码是一行setWindowFlags(Qt::FramelessWindowHint);这里有个细节如果你只是设置这一个Flag窗口会变成无边框的顶层窗口但默认连“最小化/最大化/关闭”按钮也没了。这是合理的因为你的自定义标题栏本来就要放自己的按钮或者用系统托盘菜单来替代。如果你的需求只是想隐藏标题栏、但保留系统边缘的缩放边框可以尝试setWindowFlags(Qt::CustomizeWindowHint);在Windows上Qt::CustomizeWindowHint会保留窗口的可缩放边框但去掉标题栏文字和图标。不过这个组合在不同平台上的效果差别很大不一定靠得住。最稳妥、可预期性最强的方案还是FramelessWindowHint然后自己实现移动和缩放。另外建议设置setAttribute(Qt::WA_TranslucentBackground)如果你需要做圆角或者阴影效果。这个属性让窗口背景变成可透明的但注意它也会影响整个窗口的绘制效率后面我会专门讲坑。2.2 一个能跑的最简无边框窗口我建议把这个类独立出来命名成FramelessWindow后续所有移动和缩放逻辑都封装在里面业务子类继承它就行。这样代码复用度最高。class FramelessWindow : public QWidget { Q_OBJECT public: explicit FramelessWindow(QWidget *parent nullptr); protected: void mousePressEvent(QMouseEvent *event) override; void mouseMoveEvent(QMouseEvent *event) override; void mouseReleaseEvent(QMouseEvent *event) override; private: enum class ResizeDirection { None, Left, Right, Top, Bottom, TopLeft, TopRight, BottomLeft, BottomRight }; ResizeDirection hitTest(const QPoint pos) const; bool m_leftButtonPressed false; QPoint m_dragStartPos; // 按下时的全局坐标 QPoint m_windowStartPos; // 按下时的窗口左上角坐标 QRect m_startGeometry; // 缩放开始时的窗口几何 QPoint m_resizeStartPos; // 缩放开始时的全局坐标 int m_borderWidth 6; // 边缘热区宽度像素 ResizeDirection m_resizeDirection ResizeDirection::None; };构造函数里FramelessWindow::FramelessWindow(QWidget *parent) : QWidget(parent) { setWindowFlags(Qt::FramelessWindowHint); setMinimumSize(400, 300); }这样一个窗口跑起来之后是纯白的无边框矩形暂时还拖不动。接下来分两块补全移动和缩放。3. 拖动移动全局坐标和窗口坐标别搞混3.1 事件入口与三个核心函数无边框窗口的移动逻辑本质上是一个很简单的公式窗口新位置 按下时窗口位置 (当前鼠标全局坐标 - 按下时鼠标全局坐标)这里的关键是鼠标坐标必须用全局坐标也就是屏幕上实际的位置而不是相对于窗口的局部坐标。因为鼠标移动之后窗口本身也在跟着移动如果用局部坐标event-pos()你会发现窗口在跟着鼠标“抖”永远对不上。在Qt6里获取全局鼠标位置用event-globalPosition().toPoint()如果还在用Qt5接口是event-globalPos()。为了兼容5.15和6.x可以写一个小工具函数包装一下static QPoint globalMousePos(QMouseEvent *event) { #if QT_VERSION QT_VERSION_CHECK(6, 0, 0) return event-globalPosition().toPoint(); #else return event-globalPos(); #endif }3.2 移动的完整代码void FramelessWindow::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_leftButtonPressed true; m_dragStartPos globalMousePos(event); m_windowStartPos frameGeometry().topLeft(); event-accept(); return; } QWidget::mousePressEvent(event); } void FramelessWindow::mouseMoveEvent(QMouseEvent *event) { QPoint globalPos globalMousePos(event); if (m_leftButtonPressed m_resizeDirection ResizeDirection::None) { QPoint delta globalPos - m_dragStartPos; move(m_windowStartPos delta); event-accept(); return; } QWidget::mouseMoveEvent(event); } void FramelessWindow::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_leftButtonPressed false; m_resizeDirection ResizeDirection::None; event-accept(); } QWidget::mouseReleaseEvent(event); }这里有三个细节要特别说第一记录窗口位置用的是frameGeometry().topLeft()而不是geometry().topLeft()。普通情况下两者几乎一样但如果你后面加了阴影、半透明边距geometry()是窗口的实际内容矩形frameGeometry()才是包含“隐式边框”的整个区域。用frameGeometry()做位置基准更稳。第二按下事件里就要立刻记录坐标不要在移动事件里才记录否则第一次移动会直接跳一段距离。第三我在按下事件里做了event-accept()。如果窗口内部有可拖动的子控件比如一个QSlider、一个列表这个处理会吞掉子控件的鼠标事件导致它们没法交互。这是新手最容易踩的坑之一。通常的解决方法是只允许在“标题栏区域”触发移动。实际项目中标题栏一般是一个子QWidget你把这个类应用到标题栏上而不是整个窗口。整个窗口的移动逻辑要在标题栏子控件里实现然后用window()-move(...)来移动父窗口。4. 窗口缩放边缘检测、光标切换和几何计算4.1 八个方向的判定与光标反馈窗口缩放比移动复杂但核心思路是不变的在鼠标没有任何按键按下时判断鼠标是否落在边缘热区如果落进去了就切换光标如果按下左键就进入缩放模式。边缘热区的宽度建议设成6到8像素太窄了鼠标很难点到太宽了影响内容区的正常操作。触屏设备上可以放宽到12像素左右因为手指的点击精度远不如鼠标。hitTest函数是缩放的基础它根据鼠标在窗口内的局部坐标判断当前落在哪个方向上FramelessWindow::ResizeDirection FramelessWindow::hitTest(const QPoint pos) const { int x pos.x(); int y pos.y(); int w width(); int h height(); bool onLeft x m_borderWidth; bool onRight x w - m_borderWidth; bool onTop y m_borderWidth; bool onBottom y h - m_borderWidth; if (onLeft onTop) return ResizeDirection::TopLeft; if (onRight onTop) return ResizeDirection::TopRight; if (onLeft onBottom) return ResizeDirection::BottomLeft; if (onRight onBottom) return ResizeDirection::BottomRight; if (onLeft) return ResizeDirection::Left; if (onRight) return ResizeDirection::Right; if (onTop) return ResizeDirection::Top; if (onBottom) return ResizeDirection::Bottom; return ResizeDirection::None; }在无按键的mouseMoveEvent里调用它根据方向设置光标Qt::CursorShape cursor Qt::ArrowCursor; switch (m_resizeDirection) { case ResizeDirection::Left: case ResizeDirection::Right: cursor Qt::SizeHorCursor; break; case ResizeDirection::Top: case ResizeDirection::Bottom: cursor Qt::SizeVerCursor; break; case ResizeDirection::TopLeft: case ResizeDirection::BottomRight: cursor Qt::SizeFDiagCursor; break; case ResizeDirection::TopRight: case ResizeDirection::BottomLeft: cursor Qt::SizeBDiagCursor; break; default: unsetCursor(); break; } setCursor(cursor);注意这个方向判断的结果需要保存到成员m_resizeDirection里因为当鼠标按下进入缩放模式后mouseMoveEvent里还需要根据它计算新的窗口几何那时不再重新做hitTest。一旦重新检测鼠标可能已经离开边缘区域方向就丢了。4.2 调整大小的核心逻辑代码缩放时的核心计算思路是按下鼠标时记录窗口的起始几何m_startGeometry和鼠标全局坐标m_resizeStartPos移动鼠标时用当前鼠标坐标减去起始坐标得到偏移量再根据缩放方向修改起始几何的对应边。void FramelessWindow::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_leftButtonPressed true; m_dragStartPos globalMousePos(event); m_windowStartPos frameGeometry().topLeft(); m_startGeometry geometry(); m_resizeStartPos globalMousePos(event); // 如果按下时鼠标在边缘热区进入缩放模式 if (m_resizeDirection ResizeDirection::None) { m_resizeDirection hitTest(event-position().toPoint()); } event-accept(); return; } QWidget::mousePressEvent(event); }然后mouseMoveEvent里如果有按键且处于缩放模式走缩放逻辑void FramelessWindow::mouseMoveEvent(QMouseEvent *event) { QPoint globalPos globalMousePos(event); if (m_leftButtonPressed m_resizeDirection ! ResizeDirection::None) { int dx globalPos.x() - m_resizeStartPos.x(); int dy globalPos.y() - m_resizeStartPos.y(); QRect r m_startGeometry; switch (m_resizeDirection) { case ResizeDirection::Right: r.setWidth(qMax(minimumWidth(), m_startGeometry.width() dx)); break; case ResizeDirection::Bottom: r.setHeight(qMax(minimumHeight(), m_startGeometry.height() dy)); break; case ResizeDirection::BottomRight: r.setWidth(qMax(minimumWidth(), m_startGeometry.width() dx)); r.setHeight(qMax(minimumHeight(), m_startGeometry.height() dy)); break; case ResizeDirection::Left: r.setLeft(r.left() dx); if (r.width() minimumWidth()) r.setLeft(r.right() - minimumWidth()); break; case ResizeDirection::Top: r.setTop(r.top() dy); if (r.height() minimumHeight()) r.setTop(r.bottom() - minimumHeight()); break; case ResizeDirection::TopLeft: r.setLeft(r.left() dx); r.setTop(r.top() dy); if (r.width() minimumWidth()) r.setLeft(r.right() - minimumWidth()); if (r.height() minimumHeight()) r.setTop(r.bottom() - minimumHeight()); break; case ResizeDirection::TopRight: r.setTop(r.top() dy); r.setWidth(qMax(minimumWidth(), m_startGeometry.width() dx)); if (r.height() minimumHeight()) r.setTop(r.bottom() - minimumHeight()); break; case ResizeDirection::BottomLeft: r.setLeft(r.left() dx); r.setHeight(qMax(minimumHeight(), m_startGeometry.height() dy)); if (r.width() minimumWidth()) r.setLeft(r.right() - minimumWidth()); break; default: break; } setGeometry(r); event-accept(); return; } // 无按键时更新光标 if (!m_leftButtonPressed) { m_resizeDirection hitTest(event-position().toPoint()); // ... 光标切换逻辑 } QWidget::mouseMoveEvent(event); }这里有一个容易算错的地方拖左边界或者上边界时窗口的left()和top()会改变但宽度和高度的计算必须用right()减去新的left()而不是简单地从m_startGeometry直接减。所以上面的代码里用了“如果宽度小于最小值就把left重新调整到right - 最小宽度”这种方式确保窗口不会缩到比最小尺寸还小。另外setGeometry的参数是(x, y, width, height)这里统一用QRect来操作读起来清晰也避免手写出错。5. 实际项目里绕不开的细节和坑5.1 无边框窗口最大化与还原的处理如果你的窗口还提供最大化按钮那必须处理一个问题无边框窗口最大化时会直接顶到屏幕最边缘把Windows任务栏盖住。因为系统并不知道你的“最大化按钮”到底是什么含义。最简单的做法是在点击最大化按钮时不要调用showMaximized()而是自己计算可用屏幕区域void FramelessWindow::toggleMaximize() { if (isMaximized()) { showNormal(); } else { m_normalGeometry geometry(); QScreen *screen QGuiApplication::screenAt(pos()); setGeometry(screen-availableGeometry()); m_maximized true; } }这里有个体验问题自绘无边框窗口的“最大化”如果只是简单把窗口铺满工作区那么还原时的动画和位置记忆也得自己处理。还有最大化状态下应该禁止进入缩放模式可以在mouseMoveEvent开头加一句判断if (isMaximized()) { unsetCursor(); QWidget::mouseMoveEvent(event); return; }5.2 阴影、圆角和其他视觉效果去掉边框后Windows系统自带的阴影也没有了。如果想让窗口“浮起来”更有质感常见的做法是给窗口设置WA_TranslucentBackground再用QGraphicsDropShadowEffect给内容widget加阴影。setAttribute(Qt::WA_TranslucentBackground); QGraphicsDropShadowEffect *shadow new QGraphicsDropShadowEffect(this); shadow-setBlurRadius(20); shadow-setOffset(0, 0); shadow-setColor(QColor(0, 0, 0, 80)); ui-centralWidget-setGraphicsEffect(shadow);注意一个比较容易踩的坑QGraphicsDropShadowEffect不要直接加在顶层窗口上否则在某些Windows版本上阴影不会生效。一般做法是加在内容容器QWidget上给容器周围留一圈透明边距阴影才会显示出来。圆角也是同理用QSS设置border-radius配合FramelessWindowHint和WA_TranslucentBackground。不过在Windows上窗口一旦设了透明背景整个窗口的绘制就走另一条渲染路径如果窗口内容很大、刷新频繁性能会略差。如果只是想要一个简单矩形窗口不追求圆角就不建议开透明背景。5.3 高DPI下的坐标错乱这个话题在无边框窗口里特别容易被忽视。Windows现在普遍开启了125%或150%的缩放如果Qt5程序没有正确开启高DPI支持那么globalPosition()拿到的坐标和屏幕实际坐标会不一致导致窗口移动时偏移越来越大。在Qt5里必须在main()函数创建QApplication之前加上QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);Qt6默认开启高DPI不用再写这两行。但跨不同缩放比例的显示器拖动窗口时又会出现新问题鼠标从100%缩放的屏幕拖到150%缩放的屏幕坐标换算不连续窗口可能会闪跳。这是多显示器高DPI下的老难题目前每个人的解法都不同好在大部分人的场景是单显示器先把高DPI支持打开基本坑就填平大半了。6. 更优解Windows原生缩放与发布注意6.1 nativeEvent 拾起 WM_NCHITTEST如果你只做Windows平台不想维护上面这一堆鼠标事件、光标切换逻辑还有一个更接近系统原生效果的方案直接用native event处理Windows消息。原理是告诉Windows“这个窗口哪个区域是可移动的哪个区域是可缩放的”让系统自己处理缩放动画和光标。关键代码在nativeEvent里处理WM_NCHITTESTbool FramelessWindow::nativeEvent(const QByteArray eventType, void *message, qintptr *result) { #ifdef Q_OS_WIN MSG *msg static_castMSG*(message); if (msg-message WM_NCHITTEST) { QPoint globalPos QCursor::pos(); QPoint localPos mapFromGlobal(globalPos); int x localPos.x(); int y localPos.y(); int w width(); int h height(); if (x 0 x m_borderWidth y 0 y m_borderWidth) { *result HTTOPLEFT; return true; } // ... 其他方向类似 if (y 0 y 20) { // 顶部区域当作标题栏 *result HTCAPTION; return true; } } #endif return QWidget::nativeEvent(eventType, message, result); }这种方式的好处是移动窗口时系统会帮忙暂停主线程的窗口重绘拖拽过程更顺滑缩放边缘的光标切换也完全由系统处理。但它只能在Windows上用如果产品需要跨平台发布就得写平台分支。我的建议是项目工期紧、只出Windows版优先用这个方案需要保跨平台就用前面的纯Qt方案。6.2 windeployqt 打包时的琐碎提醒无边框窗口本身的代码不会引入新的依赖但如果你把有阴影、圆角的窗口发布出去经常会遇到“开发机上正常换一台电脑就崩溃或界面异常”的情况。这一点和打包工具windeployqt的完整性关系很大。跑windeployqt最忌讳的是直接对整个release目录一次性处理比如windeployqt F:\build\MyApp这样会把目录下所有的exe都复制一遍运行库很可能覆盖成错误版本。更规范的做法是windeployqt F:\build\MyApp\release\MyApp.exe另外要注意如果项目用了Qt5.15.2的msvc2019版本目标机器上必须装了对应的Visual C Redistributable否则一启动就报“找不到VCRUNTIME140.dll”。无边框窗口和这项依赖无关但很多人第一次打包发布才发现这个问题建议提前把VC运行库一并带上。7. 最后再分享一个实际项目里的调整经验我最早实现无边框窗口时把边缘热区宽度设置成3像素以为这样更像原生边框结果用户反馈“太难抓了鼠标要对准一会儿才能拉到边框”。后来改成了6像素效果好很多。Windows系统原生的缩放热区其实也是8像素左右所以这个值不是越小越精致太小了反而难用。还有一次在做嵌套布局时子控件覆盖了整个窗口导致mousePressEvent根本不会被窗口接收到。排查了很久才发现原来是一个透明背景的QLabel被子控件撑大了鼠标事件全被它吸收了。解决方式是给那个子控件设置setAttribute(Qt::WA_TransparentForMouseEvents)。这个属性在做自定义边框时非常好用如果窗口内有不需要响应鼠标的装饰性控件可以直接让它透明鼠标消息就不会被吃掉。无边框窗口的“移动”和“缩放”看起来是两个微不足道的函数但真正埋点踩一遍之后会发现它牵扯到坐标系、事件分发、平台差异、高DPI、打包发布等一堆事。希望这篇文章能帮你少走一点弯路。如果你在实现过程中遇到什么怪问题欢迎在评论区把现象和代码贴出来大家一起看看到底是哪个环节的锅。本文还有配套的精品资源点击获取