简介Qt-Advanced-Docking-System 是一套面向 C/Qt 开发者的高级停靠窗口框架适合需要构建类 Visual Studio 风格可定制布局的桌面应用开发者尤其是使用 Qt5 或 Qt6 的中高级工程师。它解决了传统 Qt 停靠系统存在中央部件限制、布局灵活性不足的问题支持到处停靠、浮动窗口内停靠、分组拖动标签页以及快速切换主窗口布局透视图等能力并新增 Qt6 支持、概念支持与焦点高亮等特性。资源以 zip 压缩包形式提供整体约 8.03MB上游未提供文件总数与类型明细可视为源码级工程包便于直接集成到现有项目中编译使用。目前已有 2729 人学习下载读者可借此掌握无中央部件的停靠架构设计思路、浮动窗口与主窗口统一处理方式以及分组拖拽和透视图布局的实现机制为自研 IDE 或复杂工具软件提供可复用的扩展坞方案。1. 从一堆散乱窗口到可停靠工作台Qt-Advanced-Docking-System 能解决什么如果你用 Qt 写过稍微复杂点的桌面工具大概率遇到过这个场景主窗口里塞了七八个面板日志、属性、工程树、预览各占一块用户想把日志拖到右边、把属性面板叠到工程树下面甚至拖出主窗口变成独立浮窗再拖回来还能自动吸附。Qt 自带的 QDockWidget 能做基础停靠但一旦涉及嵌套布局、拖出成独立窗口、保存还原布局状态代码就会迅速膨胀成一团玄学。Qt-Advanced-Docking-System 就是冲着这个痛点来的它是一套基于 C 和 Qt5 的高级扩展坞框架把「可拖拽、可嵌套、可浮动、可序列化」的停靠系统做成可复用组件。适合谁适合正在做 IDE、图形编辑器、监控台、数据分析工具这类多面板桌面应用的开发者尤其是已经用 Qt 搭好主框架、但被 QDockWidget 的布局限制卡住的人。它不绑定具体业务你把它当成一个「窗口布局引擎」接进现有工程即可。2. 架构拆解ADS 的窗口容器、区域与状态管理是怎么组织的2.1 核心对象模型DockManager、DockWidget 与 DockAreaWidgetADS 的骨架由三个核心类撑起来。CDockManager是整个停靠系统的根挂在主窗口上负责全局调度CDockWidget是每个可停靠面板的包装你把自己的 QWidget 塞进去CDockAreaWidget是承载一组 DockWidget 的容器区域多个区域可以再嵌套进CDockSplitter形成分割布局。理解这三层关系后面改布局才不会迷路。// 创建停靠管理器绑定到主窗口 CDockManager::setConfigFlag(CDockManager::OpaqueSplitterResize, true); CDockManager::setConfigFlag(CDockManager::FocusHighlighting, true); CDockManager* dockManager new CDockManager(this); // 创建一个可停靠面板内部放你自己的 QWidget CDockWidget* logDock new CDockWidget(日志); logDock-setWidget(new QTextEdit()); // 把面板加到管理器的顶部区域 CDockAreaWidget* area dockManager-addDockWidget( TopDockWidgetArea, logDock);这段代码里setConfigFlag决定全局行为比如OpaqueSplitterResize让拖动分割条时实时重绘FocusHighlighting给当前聚焦面板加高亮边框。addDockWidget的第一个参数是停靠方位枚举第二个是面板对象返回的CDockAreaWidget就是这块面板所在的区域容器后续想再往同一区域塞面板直接拿这个返回值继续加即可。参数上最容易踩的是面板名它既是显示标题也是序列化时的唯一键重名会导致布局还原错乱。2.2 布局持久化saveState 与 restoreState 的配合多面板工具最怕用户调好布局后下次打开全乱。ADS 提供saveState()和restoreState()把整个停靠树序列化成 QByteArray你可以存进 QSettings 或配置文件。// 退出时保存布局 QSettings settings(MyCompany, MyTool); settings.setValue(dockLayout, dockManager-saveState()); // 启动时还原布局 QVariant layout settings.value(dockLayout); if (layout.isValid()) { dockManager-restoreState(layout.toByteArray()); }saveState返回的字节数组包含每个面板的可见性、浮动状态、所在区域和分割比例。restoreState会按面板名去匹配当前已注册的 DockWidget所以顺序上必须先创建好所有面板再还原否则找不到对应名字的面板就会被丢弃。常见做法是在主窗口构造函数里先建完所有 DockWidget最后一步才调 restoreState这个顺序反了就会出现「布局还原后少了几个面板」的翻车现场。2.3 浮动窗口与嵌套分割拖出主窗口后发生了什么ADS 允许把面板拖出主窗口变成独立顶层窗口这背后是CFloatingDockContainer在接管。当你把 DockAreaWidget 拖离主窗口管理器会创建一个浮动容器把区域从主分割树里摘出来挂到浮动容器上拖回去时再重新插入分割树。嵌套分割则靠CDockSplitter递归实现一个区域可以水平或垂直再分形成任意深度的布局。// 把两个面板并排放在同一区域形成标签页 CDockAreaWidget* area dockManager-addDockWidget(CenterDockWidgetArea, treeDock); dockManager-addDockWidget(CenterDockWidgetArea, propertyDock, area); // 再在右侧开一个独立区域放预览面板 dockManager-addDockWidget(RightDockWidgetArea, previewDock);addDockWidget的第三个参数是可选的参考区域传了就把新面板叠进该区域变成标签页不传就按方位新建区域。这里的关键参数是方位枚举和参考区域方位决定新区域挂在哪参考区域决定是合并还是新建。实际项目里我一般先用方位把大块布局定下来再用参考区域做标签页合并这样布局树层次清晰后期加面板不容易乱。3. 跑起来从源码编译到第一个可停靠窗口3.1 环境准备与工程接入方式ADS 是纯头文件加少量源文件的库接入方式有两种把源码目录直接拖进你的工程或者编译成静态库链接。常见做法是直接把src目录加进 INCLUDEPATH把几个 cpp 加进 SOURCES省去单独编译库的步骤。依赖上只需要 Qt5 的 Core、Gui、Widgets 三个模块qmake 和 CMake 都支持。# qmake 工程文件片段 QT core gui widgets INCLUDEPATH $$PWD/ads/src SOURCES $$PWD/ads/src/DockManager.cpp \ $$PWD/ads/src/DockWidget.cpp \ $$PWD/ads/src/DockAreaWidget.cpp \ $$PWD/ads/src/FloatingDockContainer.cpp HEADERS $$PWD/ads/src/DockManager.h这段 qmake 配置把 ADS 源码直接编进主工程。INCLUDEPATH指向 ads 的 src 目录SOURCES列出必须编译的实现文件HEADERS至少包含 DockManager.h。注意 ADS 的源文件不止这几个实际接入时把 src 下所有 cpp 都加进去最省心漏加会导致链接期报未定义符号这种错误排查起来很费时间。3.2 最小可运行示例主窗口加三个面板下面是一个能直接跑的最小主窗口包含日志、工程树、属性三个面板支持拖拽和布局保存。#include QMainWindow #include QTextEdit #include QTreeWidget #include QSettings #include DockManager.h class MainWindow : public QMainWindow { public: MainWindow() { // 开启透明分割条拖动和焦点高亮 CDockManager::setConfigFlag(CDockManager::OpaqueSplitterResize, true); CDockManager::setConfigFlag(CDockManager::FocusHighlighting, true); dockManager new CDockManager(this); // 日志面板 auto* logDock new CDockWidget(日志); logDock-setWidget(new QTextEdit()); dockManager-addDockWidget(BottomDockWidgetArea, logDock); // 工程树面板 auto* treeDock new CDockWidget(工程); treeDock-setWidget(new QTreeWidget()); dockManager-addDockWidget(LeftDockWidgetArea, treeDock); // 属性面板叠在工程树同一区域 auto* propDock new CDockWidget(属性); propDock-setWidget(new QTreeWidget()); dockManager-addDockWidget(LeftDockWidgetArea, propDock); // 还原上次布局 QSettings settings(MyCompany, MyTool); QVariant layout settings.value(dockLayout); if (layout.isValid()) dockManager-restoreState(layout.toByteArray()); } ~MainWindow() { QSettings settings(MyCompany, MyTool); settings.setValue(dockLayout, dockManager-saveState()); } private: CDockManager* dockManager; };代码逻辑分四步先设全局配置标志再建管理器然后逐个创建面板并按方位加入最后还原布局。参数上BottomDockWidgetArea和LeftDockWidgetArea决定初始位置两个面板用同一方位会自动合并成标签页。析构里保存布局保证下次启动还原。注意CDockManager的父对象设为主窗口这样窗口销毁时管理器一并释放不会内存泄漏。3.3 编译运行与验证清单编译前确认 Qt 版本在 5.12 以上ADS 用了一些较新的信号槽语法。运行后按这个清单验证面板能否拖动到其他方位、能否拖出主窗口变浮窗、浮窗能否拖回吸附、关闭再打开布局是否还原、标签页切换是否正常。如果拖出浮窗后拖不回来多半是FloatingDockContainer相关源文件没编进去如果布局还原后面板消失检查面板名是否重复或 restoreState 调用时机是否早于面板创建。4. 避坑与排查ADS 接入时最容易翻车的五个点4.1 面板名重复导致布局还原错乱现象是还原布局后某个面板跑到别的区域或者两个面板互相顶替。原因是CDockWidget的名字被当作序列化唯一键重名时 restoreState 无法区分。解决是给每个面板起唯一名显示标题和内部名分开处理内部名用英文标识符标题才用中文。4.2 restoreState 调用早于面板创建现象是布局还原后少了几个面板或者浮动窗口没恢复。原因是 restoreState 按名字匹配已存在的 DockWidget调用时面板还没建出来就匹配不上。解决是把 restoreState 放到所有 addDockWidget 之后作为主窗口构造的最后一步。4.3 浮窗关闭后指针悬空现象是关闭浮动面板后程序崩溃。原因是浮窗关闭时内部对象被销毁但外部还持有旧指针。解决是监听CDockWidget的closeRequested信号或者用deleteLater配合 QPointer 管理生命周期别裸存指针。4.4 样式表覆盖导致拖拽区域失效现象是加了自定义 QSS 后面板拖不动了。原因是样式表把分割条或标题栏的鼠标事件区域盖住了。解决是给 ADS 的标题栏和分割条保留最小尺寸或者用CDockManager::setConfigFlag里的样式相关标志调整别用全局 QSS 一刀切。4.5 多显示器下浮窗位置异常现象是把面板拖到副屏后重启程序浮窗跑到主屏角落。原因是浮窗几何信息保存的是绝对坐标显示器配置变化后坐标失效。解决是还原后检查浮窗是否在可见屏幕范围内不在就重置到主窗口中心这个兜底逻辑我一般都会加上。5. 二次开发自定义标题栏、动态增删面板与布局预设5.1 自定义标题栏与按钮ADS 允许替换默认标题栏做法是继承CDockWidget或通过CDockManager的工厂接口注入自定义标题栏类。常见需求是加一个「锁定」按钮防止面板被拖走或者加「最大化区域」按钮。实现时重写标题栏的按钮创建逻辑把自定义 QAction 插进去再连到自己的槽函数。注意自定义标题栏要保留 ADS 需要的拖拽事件处理否则面板会拖不动。// 给面板加一个自定义动作按钮 QAction* lockAction new QAction(锁定, dockWidget); lockAction-setCheckable(true); connect(lockAction, QAction::toggled, [dockWidget](bool checked) { // 锁定后禁止拖动通过特性标志控制 dockWidget-setFeature(CDockWidget::DockWidgetMovable, !checked); }); dockWidget-setTitleBarActions({lockAction});setFeature控制面板的可移动、可关闭、可浮动等特性setTitleBarActions把动作按钮挂到标题栏。参数上DockWidgetMovable关掉后用户就不能拖这个面板了适合固定工具栏类面板。这个技巧在做专业工具时很实用能让界面既灵活又有约束。5.2 动态增删面板与布局预设运行时动态加面板用addDockWidget即可删面板用deleteLater并同步更新布局。布局预设则是把几套 saveState 的结果存成不同键用户一键切换「编辑模式」「调试模式」「预览模式」。实现时把每套布局的 QByteArray 存进配置文件切换时先 restoreState 再刷新。// 保存当前布局为预设 void savePreset(const QString name) { QSettings settings(MyCompany, MyTool); settings.setValue(preset/ name, dockManager-saveState()); } // 加载指定预设 void loadPreset(const QString name) { QSettings settings(MyCompany, MyTool); QVariant data settings.value(preset/ name); if (data.isValid()) dockManager-restoreState(data.toByteArray()); }这段代码把预设按名字存进 QSettings 的不同键加载时按名取回。参数上预设名要唯一建议用英文标识。实际项目里我会在预设切换后加一个「重置为默认」的兜底防止用户把布局调乱后找不回来。5.3 验证改造是否成功的三个方法改完布局逻辑后别只看界面顺不顺眼按这三个方法验证一是反复拖拽面板到各个方位再拖回看布局树是否稳定二是保存后重启程序看还原是否一致三是模拟多显示器切换看浮窗是否还在可见范围。我一般还会写一个简单的自动化脚本用 QTest 模拟拖拽事件跑一遍核心布局操作防止后续改动把布局逻辑改崩。从那以后我每次接 ADS 到新项目都强制先跑一遍「建面板、存布局、重启、还原」这条最小闭环确认没问题再往上堆业务面板。这个习惯帮我省了不少返工时间。希望帮到你。本文还有配套的精品资源点击获取