简介这是Qt Advanced Docking SystemQt高级扩展坞系统的完整源码资源面向希望构建类似Visual Studio等IDE风格可停靠界面的Qt开发者适合具备C与Qt基础、需要实现复杂窗口布局管理的中高级用户。包内为核心库源码及配套工程文件可帮助理解停靠区域、浮动窗口、分组拖拽与透视切换等机制并支持在Qt5/Qt6环境中集成使用。资源共包含若干源代码与配置类文件压缩包大小约8.03MB结构紧凑便于直接查阅关键实现。目前已有2700余人学习下载是研究高级窗口停靠方案时较具参考价值的开源项目。通过阅读源码读者可掌握无中央小部件的自由停靠思路、浮窗内停靠逻辑及完整布局快速切换等设计细节也可将其作为扩展自定义停靠功能的起点。 做一个 Qt 桌面工具设计多面板布局时我最初是很依赖 QDockWidget 的觉得能拖出来、能停靠、能保存状态已经够用。直到做一款带代码编辑、变量监视、渲染预览的调试器时我才发现这套官方方案在复杂布局面前有多吃力。后来在 GitHub 上翻到 Qt-Advanced-Docking-System下文简称 ADS才算真正把多面板体验做到 IDE 级别。这篇文章就从我的真实接入视角出发讲清楚这个高级扩展坞系统解决了什么问题、核心设计如何理解、怎么在 30 分钟内集成进项目以及那些文档里不会写的坑。1. 为什么项目用上 ADSQDockWidget 的边界与诉求1.1 官方停靠组件的三个不够用先说结论不是 QDockWidget 不能用是它只适合简单停靠的场景。我踩过的具体限制主要有三条。第一QDockWidget 只能停靠到 QMainWindow 的四条边中央区域永远是剩余空间不是一个可以参与停靠管理的 DockArea。这就导致你做不出中央一个编辑器区域左侧文件树右侧属性面板底部输出这种标准 IDE 布局中中央区域内部还能再堆叠标签页的效果。你当然可以往 setCentralWidget 里塞 QSplitter 和 QTabWidget但这些组件和 QDockWidget 的拖拽、浮动、状态持久化完全是两套体系拼在一起非常别扭。第二QMainWindow 的 splitDockWidget 虽然能把同一个方向拆成多个停靠区但拆分后的布局很难被用户自己重新组织。比如用户想把变量面板拖到代码面板的右侧变成左右并排视图QDockWidget 的拖拽逻辑经常只允许整体移动不能精确指定插入到某个区域内部的上方、下方、左侧、右侧。对非技术用户来说这种拖拽体验是反直觉的对技术用户来说它也不如 JetBrains 系工具那样自由。第三状态持久化不完整。QDockWidget 配合 QMainWindow::saveState 能记录基本浮停状态但恢复到一半如果某个 widget 还没创建或者布局里有浮动窗口恢复结果常常错位。而且它没有布局版本号的概念应用升级后旧布局文件直接失效的情况很常见。在我的项目里用户最反感的就是每次升版都要重新摆一次窗口。1.2 ADS 解决的是哪一类问题ADS 的核心思路是把停靠系统从 QMainWindow 中彻底独立出来。你可以把 CDockManager 当成一个全新的停靠容器所有面板、编辑器、预览区都是里面的 DockWidget它们可以在任意方向拆分、堆叠、浮动、自动隐藏并且整套布局可以序列化保存也能在不同 DPI 和窗口尺寸下尽量保持相对结构。这个库在 GitHub 上维护周期很长支持 C11 和 Qt5/Qt6许可证是 LGPLv2.1 加商业授权所以无论是开源工具还是商业软件接入成本都相对可控。ADS 解决的是一类非常典型的需求当你的应用开始出现多面板、多标签、可自由重组布局的需求时与其自己从零写一套拖拽算法不如直接站在成熟方案上做功能裁剪。我当时的判断很简单与其花两周调 QDockWidget 的边缘 case不如花两天把 ADS 接进来再花半天做定制。事实证明这个判断是划算的。2. 核心设计拆解容器、区域、DockWidget 如何协作2.1 四个核心类先记名字ADS 的类命名很直白但第一次看容易混淆。我按从大到小的顺序梳理CDockManager整个停靠系统的顶层管理者是一个 QWidget。你通常在 QMainWindow 里 new 一个 CDockManager然后setCentralWidget(m_DockManager)。所有拖拽、拆分、浮停的逻辑都由它统一调度。CDockContainerWidget停靠系统的根容器内部装的是 CDockAreaWidget 和用于拆分的 CDockSplitter。CDockManager 内部其实就持有一个最外围的容器。CDockAreaWidget一个带标签栏的区域负责管理多个 CDockWidget 的堆叠显示。你可以把它理解为一组标签页的外壳。CDockWidget对实际内容 QWidget 的包装提供标题栏、关闭按钮、浮动按钮、自动隐藏按钮。你写业务面板时真正往里面塞的是它。这几个类的关系可以粗暴类比成CDockContainerWidget 是一个大房间CDockAreaWidget 是房间里的一扇扇窗每扇窗里面可以叠多张玻璃CDockWidget而 CDockManager 是管理整个房间布局和窗户位置的总控台。2.2 添加与重组的基本动作往 ADS 里加面板核心 API 就一句话ads::CDockWidget *panel new ads::CDockWidget(面板标题); panel-setObjectName(myPanel); panel-setWidget(new QTreeWidget); m_DockManager-addDockWidget(ads::LeftDockWidgetArea, panel);setObjectName这一步不是可有可无的ADS 的布局保存与恢复严重依赖 objectName 来定位每个 dock widget。不设置会导致后面 restoreState 时找不到对应组件。当你想让两个面板在同一个区域里变成标签页关系只需要对同一个 DockWidgetArea 再次 addDockWidget。默认行为是和一个已有区域合并成多标签。当用户拖拽一个标签离开原区域ADS 会动态创建新的 CDockAreaWidget 或 CFloatingDockContainer整个过程自动完成。你不需要写任何拖拽事件处理代码——这和我最初用 QDockWidget 时的体验是完全不同的我只需要关心哪些面板可以浮动、哪些可以关闭、哪些必须固定。2.3 所有权与生命周期一次说清ADS 有一个很容易被忽略的规则你 new 出来的 CDockWidget 一旦交给 CDockManager所有权就归停了靠系统管理绝对不要手动 delete。如果设置里带上了DockWidgetDeleteOnClosefeature面板关闭时 ADS 会直接销毁这个 CDockWidget。这个特性对临时窗口很合适但对主界面常驻面板非常危险——用户关掉面板后再从视图菜单点开会发现对应对象已经没了。我的习惯是所有主界面面板都不开启DockWidgetDeleteOnClose只把临时预览窗口设成这个 feature。关闭后的面板只是隐藏toggleView(true)可以再次唤出。3. 30 分钟集成从零搭一个带编辑器和面板的骨架3.1 用 CMake 接入 ADS 源码我推荐直接以源码或子模块方式集成而不是强行装系统库。在 CMake 里写add_subdirectory(ads) target_link_libraries(your_app PRIVATE ads)ADS 开箱即用它自己会带入依赖。如果你想用共享库编译选项里会有 ADS_BUILD_SHARED 之类开关静态和动态都能跑。我对大多数项目都偏好静态集成这样部署时不用额外带一堆 DLL。3.2 最小骨架代码下面这段是我实际项目的最小原型你可以直接抄来验证#include QMainWindow #include QTreeWidget #include QTextEdit #include DockManager.h #include DockWidget.h class MainWindow : public QMainWindow { public: MainWindow(QWidget *parent nullptr) : QMainWindow(parent) { m_DockManager new ads::CDockManager(this); setCentralWidget(m_DockManager); // 左侧文件树 ads::CDockWidget *filePanel new ads::CDockWidget(文件树); filePanel-setObjectName(fileTreePanel); auto *tree new QTreeWidget; tree-setHeaderLabel(项目文件); filePanel-setWidget(tree); m_DockManager-addDockWidget(ads::LeftDockWidgetArea, filePanel); // 底部输出 ads::CDockWidget *outputPanel new ads::CDockWidget(输出); outputPanel-setObjectName(outputPanel); auto *output new QTextEdit; output-setReadOnly(true); outputPanel-setWidget(output); m_DockManager-addDockWidget(ads::BottomDockWidgetArea, outputPanel); // 中央编辑器区 ads::CDockWidget *editorPanel new ads::CDockWidget(编辑器); editorPanel-setObjectName(editorPanel); auto *editor new QTextEdit; editorPanel-setWidget(editor); m_DockManager-addDockWidget(ads::CenterDockWidgetArea, editorPanel); } private: ads::CDockManager *m_DockManager nullptr; };跑起来之后你会看到左侧文件树、底部输出、中央编辑器三个区域。此时中央虽然只有一个编辑器但它已经是 ADS 的 DockArea 了后续再往中心区 add 第二个面板会自动变成标签页。3.3 给它加一个视图菜单多面板应用除了界面本身还需要一个能控制面板显隐的菜单。ADS 提供了toggleView(bool)可以直接接到 QAction 上auto *act viewMenu-addAction(文件树); connect(act, QAction::triggered, filePanel, ads::CDockWidget::toggleView);这里有个细节toggleView的语义是如果当前隐藏则显示如果当前显示则隐藏正好和菜单勾选状态联动。你还可以用isVisible()去同步菜单的 checkable 状态就不用在业务代码里到处判断面板可见性了。集成到这个程度一套基础 IDE 布局已经成型。剩下的事情就是让用户改过的布局能存下来。4. 动态布局与状态持久化别让用户每次重摆窗口4.1 saveState / restoreState 的正确姿势ADS 能把整个布局打包成一个 QByteArray存到 QSettings 或数据库里都行。基本用法const int LAYOUT_VERSION 3; void saveLayout() { QSettings settings(MyCompany, MyTool); settings.setValue(layout_version, LAYOUT_VERSION); settings.setValue(main_window_geometry, saveGeometry()); settings.setValue(dock_layout, m_DockManager-saveState(LAYOUT_VERSION)); } void restoreLayout() { QSettings settings(MyCompany, MyTool); if (settings.value(layout_version).toInt() ! LAYOUT_VERSION) { // 版本不一致说明布局结构可能变了直接使用默认布局 return; } restoreGeometry(settings.value(main_window_geometry).toByteArray()); m_DockManager-restoreState(settings.value(dock_layout).toByteArray(), LAYOUT_VERSION); }saveState接受的版本号非常有用。当你在新版本里增加了面板、删除了某个区域布局数据结构和旧版不兼容时版本号不一致就可以直接放弃旧布局而不是让 restoreState 硬去匹配一段结构已经对不上的数据。经验是只要修改了 DockWidget 的 objectName、增删过面板类型或改变了停靠区域结构就把版本号加一。4.2 恢复布局后那些面板去哪儿了恢复布局有一个前提一定要在先把所有 CDockWidget 创建完成并 addDockWidget 之后再调用 restoreState。如果先恢复后创建ADS 找不到 objectName 对应的 dock widget布局匹配会失败或产生残留区域。正确的顺序是创建主窗口和 CDockManager注册所有菜单、动作创建全部面板并 addDockWidget读取 QSettings 并 restoreState最后显示主窗口如果放在步骤 5 之后 restore某些情况下浮动窗口的位置、分栏比例已经发生了闪烁体验不好。我在实测中的感受是先恢复、再 show是最稳的。4.3 自动隐藏把面板收进侧边栏ADS 较新版本支持自动隐藏功能。调用很简单filePanel-setAutoHide(true);设置后面板不再占据一个常驻区域而是折叠到屏幕边缘的自动隐藏标签里鼠标悬停时滑出离开后缩回。这个能力在窄屏、多面板场景下非常实用。不过自动隐藏在不同版本里的行为差异比较大有的版本还要求预先开启配置标志建议先跑一次官方示例确认你安装版本的行为。我个人只在属性面板这类低频使用但需要随时可查的面板上启用自动隐藏高频面板仍然保持常驻。5. 踩坑记录拖拽、焦点链与样式表的实测复盘5.1 坑一拖拽后的残留空隙用 ADS 拖拽时如果用户把某个区域里的最后一个 DockWidget 拖走ADS 理论上会自动清理空区域。但我实测发现在某些组合操作下比如先自动隐藏再拖出又拖回去的路径会留下一个高度为几像素的空隙或空白容器。排查下来问题往往不是 ADS 本身坏了而是我在布局变化后立刻保存了状态。ADS 保存布局时会把当前容器的拆分比例也写进去如果那一刻容器里还有空的 QSplitter 占位保存的状态里就带了一个幽灵区域下次恢复时它又出现了。处理办法有两个要么在保存布局前先调用一次CDockManager::removeDockWidget()把待销毁的区域清干净要么在恢复到一半时主动检查容器里是否有空区域有就调用区域内方法关闭。更省事的方案是保存和恢复布局的入口都放在主窗口 show 事件之后给 ADS 留出足够的布局修正时机。5.2 坑二浮动窗口关闭时内容被直接销毁这是我最开始踩得最疼的一个坑。用户点掉一个浮动面板的关闭按钮过一会再从视图菜单打开发现面板内容变成了空白。排查半天根因就是我在创建面板时顺手 set 了DockWidgetDeleteOnClosefeature。ADS 在关闭浮动容器时会判断每个 DockWidget 是否带 DeleteOnClose 标记如果有就直接 delete。这个行为对临时弹出的查找结果窗口是合理的但对主面板就是灾难。我的建议是除非面板真的是一次性的临时页否则永远别设这个 feature。如果一定要设请在显示面板的菜单触发逻辑里重新 new 一个新面板并把它重新 addDockWidget。5.3 坑三全局样式表把 ADS 渲染搞花了ADS 自身有一套精心设计的样式表用来绘制标签栏、标题按钮、浮动窗口边框。如果你在 main.cpp 里给整个应用设置了一套全局 QSS而且选择器写得很宽比如直接设置QWidget { background: #333; }那么 ADS 内部控件的样式会受影响出现图标错位、按钮背景异常、拖拽预览闪黑块等问题。正确做法是把全局样式限制在业务控件范围不要对停靠系统内部组件做无差别覆盖。如果要做深色主题最好的方式是以 ADS 自带的样式表为基础复制一份出来改色值再通过样式表机制设给 CDockManager。另外在高 DPI 显示器上拖拽预览偶尔会有像素偏移这通常是系统缩放和 QSS 中固定像素值共同作用的结果建议所有边距、图标尺寸都用 QStyle 提供的 metrics 或相对单位。5.4 坑四高 DPI 与布局恢复的默契Qt5 时代很多 ADS 使用者在双屏不同缩放比的场景下会碰到恢复后的布局分栏比例异常。比如在 100% 缩放的屏幕上保存换到 150% 缩放的屏幕上恢复面板宽度可能变得很怪。这个问题不完全是 ADS 的锅而是你自己应用是否开启高 DPI 感知的问题。Qt5 里需要在 main 函数最早处调用QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);Qt6 默认启用但如果你用了自定义的 QSurfaceFormat 或某些 OpenGL 相关组件最好还是显式确认一下。ADS 在保存布局时记录的是逻辑尺寸只要应用自身完成了高 DPI 适配恢复基本不会出大问题。6. 选型判断什么时候该用 ADS什么时候原生就够6.1 两张方案对比维度QDockWidgetQt-Advanced-Docking-System边缘停靠支持支持且更灵活中央区域作为可停靠区不支持支持自由拆分、重组布局弱需配合 QSplitter强拖拽直接生成标签页堆叠支持支持自动隐藏到侧边无支持布局持久化有限完善带版本控制拖拽体验精细化一般好可定制集成成本零成本原生自带需要引入第三方库许可证LGPLLGPLv2.1 或商业授权6.2 我的选型建议如果你的应用界面只有两三个固定面板比如左侧列表、右侧详情、顶部工具栏而且用户基本不需要自定义布局那用 QDockWidget 完全够了。加一个 QSplitter 做右侧拆分比引入整套 ADS 体系更轻、更可控。但只要你开始追求现代 IDE 的交互体验——多标签编辑器、面板可以自由浮动到第二块屏幕、布局可保存成多套方案、侧边自动隐藏——ADS 就是当前 Qt 生态里最成熟的答案。它把拖拽、拆分、布局序列化这些脏活都做了你只需要聚焦业务面板本身。另一个判断角度是维护成本。ADS 的 API 相对稳定GitHub 上有完整示例和讨论区。相比你自己在 QDockWidget 上堆补丁长期维护一个业务项目时ADS 的投入产出比明显更高。我在项目里还额外在面板右上角加了自定义操作按钮ADS 的接口对这类定制也友好不会逼你去 hack 内部控件树。最后说一句部署用 windeployqt 打包时除了 Qt 自带 DLL记得把 ADS 编译出来的动态库一起放进去或者干脆像我一样静态编译省心很多。如果静态链接CMake 里设置好ADS_STATIC之类标志后整包部署只需要一个可执行文件加资源文件对用户来说体验也更好。本文还有配套的精品资源点击获取