简介Qt Advanced Docking System 是一套面向 Qt/C 开发者的高级窗口停靠框架旨在实现类似 Visual Studio 的灵活停靠布局。它取消了传统中央小部件限制支持任意边缘停靠、浮动窗内停靠、选项卡分组拖动以及透视图快速切换可嵌入主窗口或独立窗口适合需要构建 IDE、编辑器或复杂工具面板的桌面应用项目。资源包为 zip 压缩格式体积约 8.03 MB包含完整的源代码与配套说明可直接集成到 Qt5/Qt6 工程中使用。目前已有 2728 人学习下载社区活跃度良好。读者可从中获取核心类库、示例工程和配置方法借此快速搭建可定制、可扩展的多窗口工作区大幅减少底层停靠逻辑的开发成本。1. Qt Advanced Docking SystemQt 5 里做可拖拽停靠布局的进阶答案如果你写过 Qt 桌面工具大概率被 QDockWidget 的拖拽布局折磨过窗口多了布局要靠 setCorner 去拼恢复布局又经常错位。Qt Advanced Docking System 是一套基于 C/Qt5 的高级扩展坞方案常被叫做 docking-library核心是把主窗口里的 Dock 区域交给一个统一管理器去调度拖拽、拆分、浮动、标签化都能自动处理。它不是 QDockWidget 的简单换皮而是一套独立布局引擎。适合需要 IDE 式多窗口界面、需要布局状态能保存能恢复的 Qt 项目。下面我从对象关系、工程接入、常见踩坑依次拆开。2. 先把对象关系理顺DockManager、DockWidget 与 DockArea 的协作2.1 主窗口替换CDockManager 是总调度不是 QMainWindow 的替代品第一次把这套 docking-framework 拉进工程时我犯过一个典型错误以为它只是把 QDockWidget 加强于是继续用 QMainWindow只在角落里塞了一个 CDockManager。结果布局出来和中轴撕裂一样拖拽提示也不对。后来把主窗口基类换成 CDockManager 才正常。在我的使用习惯里这一步不要直接改老代码而是先开一个空白工程验证。一个最小替换像这样#include DockManager.h #include DockWidget.h #include QTextEdit class MainWindow : public CDockManager { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); };这段代码有几个关键点。首先是Q_OBJECTCDockManager 内部大量依赖信号槽去通知区域变化子类没有这个宏moc 不会生成对应元对象后续你写自定义关闭行为的 connect 会静默失效。其次是继承 CDockManager 之后窗口的菜单栏、状态栏、工具栏能力依然保留因为它本身是一个 QMainWindow 派生对象。不要把CDockManager和QMainWindow同时 new 出来否则 dock 的层级关系会变得不可控这是很多人接手时最想当然的用法。参数层面你通常在构造函数里会先做两件事设置配置标志再加载上次布局。配置标志按需打开比如聚焦高亮、标签拖拽范围这些在不同版本里的枚举名略有差异但入口都是CDockManager::setConfigFlag。我会在后面的避坑章节单独讲聚焦高亮这个开关这里先知道它有这个配置入口就行。另外替换主窗口类后centralWidget的语义也变了。原来你用setCentralWidget塞一个编辑器现在编辑器也要包进 CDockWidget 再放进去。这是这套高级扩展坞和 QDockWidget 最大的区别它不承认裸的 QWidget 停靠只承认 CDockWidget 这个停靠单元。想明白这一点后面所有布局操作都会顺很多。2.2 挂载内容CDockWidget 是唯一被认可的停靠单元我把 CDockWidget 理解成一个“带灵魂的壳”。壳外面是标题栏、拖拽把手、关闭按钮壳里面是你真正的业务 widget。写代码时所有要参与 dock 的面板都要先套这个壳。auto *dockFile new CDockWidget(tr(文件)); dockFile-setObjectName(FileDock); dockFile-setWidget(new QTextEdit(this)); dockFile-setIcon(QIcon(:/icons/file.svg)); addDockWidget(CDockManager::LeftDockWidgetArea, dockFile, QSize(260, 400));这里三个步骤顺序不要乱。第一步new CDockWidget(tr(文件))只创建标题第二步setObjectName(FileDock)是给布局持久化用的身份标识第三步setWidget才把真正的业务界面放进壳里。最后addDockWidget指定它在主窗口的初始停靠位置。很多人第一次接这个库时会问为什么不能直接把 QTextEdit 传给addDockWidget因为库内部需要根据 CDockWidget 的标题、图标、特性位来决定拖拽时的阴影反馈和右键菜单行为。裸 QWidget 没有这些信息硬传也只会在控制台打一条资源警告然后什么都不发生。这是我当时排查了很久的玄学问题后来把每个面板都套壳之后警告消失拖拽也立刻正常。第三个参数QSize(260, 400)是初始尺寸但它不是硬约束。用户拖拽边界后这个尺寸会被布局系统覆盖。如果你需要限制最小尺寸应该在内部 widget 上写setMinimumSize而不是在 CDockWidget 上做文章。这个区别很容易被忽略也是我后来看别人代码时经常看到的一个误用。2.3 布局自动生成DockArea 是动态容器不用你手动拼拆分条我原先用 QDockWidget 时想实现左侧文件栏 中央编辑区 底部日志这种布局至少要先手动 setCorner再控制哪边占多少比例。在这套 docking-library 里你只要连续 add 三个 CDockWidget。auto *dockEdit new CDockWidget(tr(编辑器)); dockEdit-setObjectName(EditorDock); dockEdit-setWidget(editor); auto *dockFile new CDockWidget(tr(文件)); dockFile-setObjectName(FileDock); dockFile-setWidget(fileTree); auto *dockLog new CDockWidget(tr(输出)); dockLog-setObjectName(LogDock); dockLog-setWidget(logView); addDockWidget(CDockManager::CenterDockWidgetArea, dockEdit); addDockWidget(CDockManager::LeftDockWidgetArea, dockFile, QSize(260, 400)); addDockWidget(CDockManager::BottomDockWidgetArea, dockLog, QSize(700, 160));内部布局规则是新 Dock 放进已经有 Dock 的一侧时不强制拆分而是可能变成标签页放进另外一侧时会自动创建新的 DockArea并且动态调整整个容器的拆分比例。你不需要手动 new CDockAreaWidget也不要去计算当前有几列几行。稍后当用户拖动标题栏把某个面板拉出去DockArea 会自动收缩放回来的位置不同生成的布局也不同——这些都由库自己去维护。底层的逻辑我没必要全展开但你得记住一个判断标准当你想用程序控制布局时找 CDockManager 的方法当你只想知道某个面板当前被放在哪一区域时才去查 CDockAreaWidget 的指针。顶层控制一律从上往下不要从子控件往上反推。很多布局状态恢复出问题就是因为有人反向依赖了 DockArea 指针。这里我放一张自己整理的对应关系原生 QDockWidget 和这套高级扩展坞的差异基本一眼能看明白对比项QDockWidget 原方案Advanced Docking 方案停靠单元QDockWidget / QWidget 混合必须 CDockWidget主窗口QMainWindowCDockManager区域容器QDockWidget 自带区域DockAreaWidget 动态生成多面板重叠需手动 tabifyDockWidget拖到同一区域自动成标签布局保存saveState/restoreState 较为粗糙saveState 配合 objectName 恢复浮动窗口靠 QDockWidget 原生独立浮层可继续嵌套这张表不是理论对比而是我实际迁移一个小型工具后的体感总结。第一次迁移最花时间的不是写代码而是搞清楚哪些东西还能用原来的概念去理解哪些必须彻底换掉。建议你也列一张这样的表改到一半时拿出来对照能少踩很多坑。3. 接进工程与 Demo 对照CMake 引入、样式资源、首跑验证3.1 目录结构与三块内容拿到代码包后我一般先不做任何编译而是把目录结构过一遍。这份资源通常分成三块目录内容我一般拿它做什么src库源码与头文件只读不改顶多加自己的主题 QSSdemo可运行的示例程序建立直觉看拖拽和状态恢复的真实手感styles图标和样式表切换 VS 风格 / 浅色深色CMakeLists.txt构建入口通过 add_subdirectory 集成编译前我强烈建议先看一遍 CMakeLists 里的 option很多分支默认会打开示例编译会影响你的首次构建时间。如果你只是把它当第三方库用示例可以先关掉等主程序能跑起来再单独编译 demo 用来对比。3.2 CMake 接入方式优先 add_subdirectory而不是手动编静态库我见过不少同行把这套库单独拿出来编成 .a 或 .lib再手动往工程里塞头文件路径。这种办法不是不行但当你需要调试库内部行为时断点经常跳不到源码上非常痛苦。更推荐的做法是直接作为子目录加进主工程。set(ADS_BUILD_EXAMPLES ON CACHE BOOL FORCE) add_subdirectory(3rdparty/Qt-Advanced-Docking-System) target_include_directories(your_app PRIVATE 3rdparty/Qt-Advanced-Docking-System/src ) target_link_libraries(your_app PRIVATE qtadvanceddocking )这里要解释两个参数。ADS_BUILD_EXAMPLES的值以你手里仓库实际提供的 CMake 选项为准不同分支可能叫BUILD_EXAMPLES你可以先打开一次看输出里有没有 example target 再决定。qtadvanceddocking这个 target 名也不是我拍脑袋写的而是这套库在不同分支下最常用的名字如果你那份代码里编译出来叫qtdocking就改成对应名字。判断方式很简单CMake 配置完成后在 build 目录里搜一下生成的库文件名。add_subdirectory 的好处是源码和主工程共用同一份 Qt 模块配置不会出现库用 Qt5Widgets、主工程用 Qt5Gui 导致 moc 元对象冲突的情况。如果你的主工程对 Qt 版本有特殊编译宏比如QT_NO_KEYWORDS库源码会跟着一起编译反而能提早暴露兼容性问题。qmake 工程也有对应接法常见做法是把 src 目录下的 .cpp 和 .h 全部加进 .pro然后确保QT widgets。有些分支会附带 .pri 文件直接 include 进来更快。我个人的建议是能用 CMake 就用 CMakeqmake 接这种方式在跨平台路径处理上容易漏文件一旦漏了编译时只会看到一个莫名其妙的“未定义 vtable” 错误排查成本不低。3.3 样式与图标没有 QSSDock 标题栏会很朴素默认状态下的 Dock 标题栏能用但视觉上非常朴素标签页之间的间隔、关闭按钮的 hover 反馈都不明显。代码包里大多会带一套主题样式直接在 main 函数里加载#include QApplication #include QFile int main(int argc, char *argv[]) { QApplication app(argc, argv); QFile styleFile(:/styles/ads.css); if (styleFile.open(QIODevice::ReadOnly)) { app.setStyleSheet(styleFile.readAll()); } MainWindow w; w.show(); return app.exec(); }这段代码的逻辑很简单把样式表从 qrc 资源里读出来整体设置到 QApplication。样式表一旦设置在 app 上Dock 的标题栏、标签页、分割线都会跟着变。你要注意的不是读取本身而是资源路径必须和你 qrc 文件里的前缀一致。我习惯把样式表放在单独 qrc 文件里而不是和图片混在一起这样修改时不用重新构建整套资源系统。图标这块也不要忽略。每个 CDockWidget 最好都setIcon一次否则标签页左侧会显得很空深色主题下尤其明显。图标路径统一放进 qrcrelease 后不会出现找不到文件的问题。3.4 先跑 Demo 再动手我建议的验证路径在写自己的业务代码之前我会先按下面这个顺序把 demo 跑一遍。这个过程花不了多少时间但能帮你提前分清库的正常行为和项目代码的问题。编译 demo。确认你的 Qt 版本能正确编过整个库这一步过了库本身没大问题。拖动标签到主窗口四边观察阴影高亮是否出现在方位箭头内。这个反馈是库的核心体验。把一个 Dock 拖成浮动窗口再把另一个 Dock 拖进浮动窗口。验证嵌套停靠是否正常。右键 Dock 标题栏看“关闭”“最大化”“浮动”等菜单项是否齐全。关闭程序再打开确认上次布局恢复成功Dock 没有跑到屏幕外。这套流程走完你心里基本有底了。后面写自己的界面时如果出现拖拽错位或布局丢面板第一时间就会怀疑是自己的业务 widget 不兼容而不是去翻库的 bug。4. 避坑向排雷布局状态、焦点、样式这几个坑我替你踩过了这套库整体稳定但真的出问题时非常隐蔽。我整理了几条自己反复翻车的记录每条都按“现象、原因、解决”梳理你可以直接对着检查。4.1 保存恢复后布局一片空白objectName 不稳定是元凶现象程序关闭前保存布局状态重开后主窗口一切正常但所有 Dock 面板全都不见了控制台没有任何报错。原因布局状态里记录的是每个 CDockWidget 的 objectName恢复时靠字符串匹配来找面板。很多面板为了临时显示用了默认 objectName比如qt_dockwidget或者多个面板共用同一个名字。恢复时管理器找不到匹配对象直接跳过这个面板。这里是我常用的保存恢复方式QSettings settings(某公司, 某应用); void saveLayout() { settings.setValue(layout, saveState(1)); } void restoreLayout() { restoreState(settings.value(layout).toByteArray(), 1); }解决给每个 CDockWidget 设置全局唯一的setObjectName并且保证在整个生命周期里都不变。不要在运行时根据用户语言环境去生成 objectName比如不要写成FileDock_ locale一旦界面语言切换布局就再也恢复不回来了。版本参数 1 只是用来标识状态格式当库升级后应该递增版本号避免旧状态被错误解析。4.2 点击 Dock 内容区键盘事件还是给了主窗口焦点策略被忽略现象面板里的 QLineEdit 可以点击但快捷键、方向键都没反应焦点似乎一直停留在主窗口。原因这套扩展坞有自己的焦点管理CDockWidget 第一次显示时焦点不一定转移到内容 widget。如果内部 widget 的focusPolicy是默认值点击后只拿到鼠标焦点没有键盘焦点。解决对需要键盘输入的面板在初始化时显式设置dockFile-widget()-setFocusPolicy(Qt::StrongFocus);同时建议打开焦点高亮配置让库知道当前活跃的 Dock 是哪一个CDockManager::setConfigFlag(CDockManager::FocusHighlighting, true);设置完这两处后点击面板内部输入框键盘事件才会正常进入。注意不要把这个强焦点设在 CDockWidget 外壳上否则高亮跑到了标题栏内容区依然不吃键盘事件。4.3 关闭按钮禁用不掉用了原生 QDockWidget 的习惯接口现象调用setFeatures(QDockWidget::DockWidgetClosable)后Dock 标题栏的关闭按钮还是亮着点击也能关掉面板。原因CDockWidget 虽然继承自 QDockWidget但标题栏按钮是库自己绘制的原生 features 对按钮的开关控制不完整必须按库的 feature 位去设置。解决改用 CDockWidget 自己的接口auto *dock new CDockWidget(输出); dock-setFeature(CDockWidget::DockWidgetClosable, false);逻辑很简单第一个参数是功能位第二个参数是开关状态。把 Closable 设为 false关闭按钮会变灰且不可点。同理想让某个面板不能浮动或不能拖动就分别处理DockWidgetFloatable和DockWidgetMovable。这个接口和原生 QDockWidget 非常像但名字不同我每次移植代码都会习惯性写错现在都是写完后立刻搜一遍代码里的setFeatures确保没有漏改。4.4 高分屏拖拽错位启动参数没统一现象高分屏上把 Dock 拖出来阴影指示位置和实际落下位置偏移明显接近屏幕边缘时更严重。原因Qt5 在高分屏下需要统一的设备像素比缩放策略。如果 main 函数在 QApplication 创建后才设置高分屏属性或者代码里对坐标又手动乘了一次 DPI 倍数浮层窗口会双重缩放。解决在创建 QApplication 之前先把全局属性设定好QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps); QApplication app(argc, argv);Qt6 里这两个属性默认启用不用重复设置。重点约束是设置之后业务代码里不要再根据屏幕物理分辨率手动缩放字体和坐标否则库内部计算拖拽落点时会被你额外的手工缩放干扰。这属于典型的“两边都对了放在一起就错了”的问题。4.5 自定义 CDockWidget 子类漏写 Q_OBJECT信号槽静默失效现象自己写了一个继承 CDockWidget 的子类里面加了信号和槽编译完全通过但运行时信号触发后槽函数不执行也没有任何报错。原因子类只要声明了 signals 或 slots就必须包含 Q_OBJECT 宏。漏掉后moc 不会为该类生成元对象connect 执行时在运行时根本找不到对应的方法地址。因为是动态连接失败Qt 不会在控制台打出红色告警。解决在子类类体内补上Q_OBJECT然后强制重新生成 moc 文件。用 IDE 增量编译时经常出现头文件改了但 moc 没重跑的情况所以改动后最好 clean 再 build。我之前卡在过这个问题上整整一个下午最后发现只是少了一个宏后来每次新建 Dock 类都先在类体第一行写上 Q_OBJECT。这些坑的共同特点是不报错只会现象级翻车。所以我把这一章定位成避坑向排雷它不是理论清单而是我实际趟过之后留下的检查表。5. 从能用走向好用利用布局预设做可切换的用户界面这套布局系统如果只用在单窗口还发挥不出它真正的价值。我自己的某个工具项目把界面按工作流拆成了三套预设写代码、调样式、查日志。预设的本质是给整套 Dock 布局拍照并命名需要时一键切换不用手动保存恢复。// 保存当前布局为一个命名预设 CDockManager::addPerspective(code); // 一键切到某个预设 CDockManager::openPerspective(code); // 删除不再需要的预设 CDockManager::removePerspective(old);这里三个方法共同构成一个完整的用户预设能力。addPerspective记录的是当前整个 Dock 区域的拓扑结构而不是内部 widget 的业务状态openPerspective会按预设重建区域布局把不属于该预设的面板隐藏把属于的面板恢复到对应位置。所以预设名要设计得稳定一点不要今天叫“code”明天改成“coding”否则用户存下来的偏好会全部失配。在 UI 上我的做法是在菜单栏加一个“界面布局”入口下面列出所有预设名。用户切换预设后把当前预设名写进 QSettings应用启动时先读这个字段再 openPerspective。还有一个小技巧不要把预设状态和主布局状态混在一个 QByteArray 里保存否则任意一次的拖拽调整都会同时改写预设用户想回到刚才那个“干净布局”就再也回不去了。把它们分开存主布局负责默认值预设负责用户当前选择。从那以后我每次接带复杂 Dock 的 C/Qt5 项目都会先把这套系统的配置项整体过一遍再动手写业务面板。这个习惯帮我挡掉了不少布局上的返工也让后来的维护者更容易看懂界面状态为什么是这个样子。希望帮到你。本文还有配套的精品资源点击获取