简介这份资源面向具备一定 Qt 基础的桌面应用开发者聚焦窗口管理与停靠布局这一常见但实现成本较高的需求提供基于开源 Qt-Advanced-Docking-System 的完整示例工程。它可帮助读者理解可停靠窗口、多区域布局、弹出式窗口、布局保存与恢复、内嵌与悬浮切换、拖动调整大小等核心能力的落地方式适用于需要构建多文档界面或复杂工具面板的软件项目。压缩包共 68 个文件约 253KB以 21 个 h 头文件与 21 个 cpp 源文件为主体另含 11 个 svg 图标、4 个 css 样式表、2 个 ui 界面文件、2 个 pro 工程文件及 qrc、cmake、pri、dll、exe 等配套内容覆盖库源码、示例程序与构建配置。目前已有 572 人学习下载。读者可从中获得可直接编译运行的 demo 工程参考 DockManager、DockAreaWidget、FloatingDockContainer 等模块的组织方式并借助样式表与图标资源快速搭建符合自身项目风格的停靠系统。1. 从一堆散乱 QDockWidget 到可拖拽停靠系统Qt-Advanced-Docking-System 到底解决什么问题用原生QDockWidget做过中大型桌面端的人大概率都经历过同一个崩溃瞬间用户把面板拖到主窗口边缘松手后布局错乱浮动窗口关掉再打开位置全丢多显示器下拖出去直接卡死。这不是你代码写得烂是 Qt 原生停靠机制在复杂场景下本身就撑不住。Qt-Advanced-Docking-System下称 ADS就是冲着这些痛点来的它把「停靠」抽象成一套可序列化的布局树支持任意方向的嵌套分割、标签页合并、浮动窗口、跨屏拖拽还能把整个布局存成二进制或 XML下次启动原样恢复。适合谁做 IDE、工控组态、音视频剪辑、数据分析面板这类「多面板 可自定义工作区」的桌面软件团队。这篇不聊虚的从集成、布局构建、参数调优到踩坑按能复现的路径走一遍。2. 把 ADS 接进现有 Qt 工程三种集成方式与选型理由2.1 为什么优先选源码内嵌而不是包管理器ADS 的集成方式常见有三种系统包管理器安装、CMake 的FetchContent拉取、源码直接内嵌到工程子目录。我一般推荐第三种原因很实际。第一ADS 的 API 在不同大版本间有过破坏性调整包管理器给你的版本未必和你的 Qt 版本匹配出问题很难定位。第二内嵌源码后你可以直接断点进它的布局计算逻辑排查「拖拽后尺寸跳变」这类玄学问题时能省掉大量猜的时间。第三很多团队要出离线构建包内嵌不依赖网络。内嵌的目录结构建议这样组织把 ADS 放在third_party下和你的业务代码隔离your_project/ ├── CMakeLists.txt ├── src/ │ └── mainwindow.cpp └── third_party/ └── ads/ ├── CMakeLists.txt ├── src/ └── include/顶层CMakeLists.txt里用add_subdirectory引入注意 ADS 自己会导出 target别重复定义cmake_minimum_required(VERSION 3.16) project(DockDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) find_package(Qt6 REQUIRED COMPONENTS Widgets) # 把 ADS 作为子目录引入它会导出 ads::qtadvanceddocking 这个 target add_subdirectory(third_party/ads) add_executable(DockDemo src/mainwindow.cpp) target_link_libraries(DockDemo PRIVATE Qt6::Widgets ads::qtadvanceddocking # 链接 ADS 导出的目标 )这里的关键参数是CMAKE_AUTOMOCADS 里有大量Q_OBJECT类漏开会导致链接期一堆 undefined reference报错信息还不会直接指向 moc新手容易在这里卡半天。CMAKE_CXX_STANDARD至少 17ADS 较新版本用了结构化绑定和std::optional。2.2 最小可运行示例一个主窗口加两个停靠面板集成完先别急着堆功能跑通最小闭环。核心类是CDockManager它是整个停靠系统的根必须作为主窗口的成员且只创建一次。下面这段是能直接编译运行的最小骨架#include QMainWindow #include QLabel #include DockManager.h #include DockWidget.h class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget* parent nullptr) : QMainWindow(parent) { // 1. 创建停靠管理器绑定到当前主窗口 ads::CDockManager::setConfigFlag(ads::CDockManager::OpaqueSplitterResize, true); ads::CDockManager::setConfigFlag(ads::CDockManager::FocusHighlighting, true); m_dockManager new ads::CDockManager(this); // 2. 创建第一个停靠面板内容用一个 QLabel 占位 auto* labelA new QLabel(面板 A 的内容); labelA-setAlignment(Qt::AlignCenter); ads::CDockWidget* dockA new ads::CDockWidget(面板 A); dockA-setWidget(labelA); // 3. 创建第二个面板 auto* labelB new QLabel(面板 B 的内容); labelB-setAlignment(Qt::AlignCenter); ads::CDockWidget* dockB new ads::CDockWidget(面板 B); dockB-setWidget(labelB); // 4. 把 A 加到左侧B 以标签页形式叠加到 A 上 m_dockManager-addDockWidget(ads::LeftDockWidgetArea, dockA); m_dockManager-addDockWidgetTabToArea(dockB, dockA-dockAreaWidget()); setCentralWidget(new QWidget); // 中央留空或放你的主编辑区 resize(1200, 800); } private: ads::CDockManager* m_dockManager nullptr; };逻辑说明setConfigFlag必须在CDockManager构造之前调用因为部分标志在构造时就被读取并固化构造后再设无效——这是最常见的翻车点之一。addDockWidget的第二个参数是区域枚举addDockWidgetTabToArea则是把新面板作为标签页并入已有区域两者语义不同别混用。参数说明OpaqueSplitterResize打开后拖动分割条实时重绘关闭则是松手才重绘前者体验好但面板内容复杂时可能掉帧FocusHighlighting让当前聚焦面板有视觉高亮多面板场景强烈建议开。2.3 布局持久化saveState 与 restoreState 的正确配对停靠系统做出来用户第一件事就是问「我调好的布局下次还在吗」。ADS 提供saveState()返回QByteArrayrestoreState()接收它。存到QSettings是最省事的做法void MainWindow::closeEvent(QCloseEvent* event) { QSettings settings(MyOrg, DockDemo); // 保存整个停靠布局包含浮动窗口位置、标签页顺序、分割比例 settings.setValue(dockLayout, m_dockManager-saveState()); QMainWindow::closeEvent(event); } void MainWindow::readSettings() { QSettings settings(MyOrg, DockDemo); QByteArray state settings.value(dockLayout).toByteArray(); if (!state.isEmpty()) { // 恢复失败会返回 false此时应回退到默认布局 if (!m_dockManager-restoreState(state)) { buildDefaultLayout(); } } else { buildDefaultLayout(); } }逻辑说明restoreState依赖面板的objectName来匹配所以每个CDockWidget创建后必须调用setObjectName(唯一名)否则恢复时找不到对应面板布局会静默错乱。这个坑非常隐蔽因为不报错只是位置不对。参数说明saveState可以带一个版本号参数用于布局结构升级时做兼容判断。如果你后续增删了面板旧布局恢复时缺失的面板不会自动出现需要在恢复后手动检查并补建。3. 高级停靠行为嵌套分割、浮动窗口与跨区域拖拽的实现细节3.1 用 addDockWidget 构建嵌套分割布局真实软件的面板层级往往不止左右上下四块而是「左侧上下分、右侧再左右分」这种嵌套结构。ADS 的做法是先建区域再往区域里塞面板通过addDockWidget的相对定位参数实现嵌套// 左侧先放一个面板作为锚点 m_dockManager-addDockWidget(ads::LeftDockWidgetArea, dockA); // 在 A 的下方再分割出一个区域放 C m_dockManager-addDockWidget(ads::BottomDockWidgetArea, dockC, dockA-dockAreaWidget()); // 右侧放 B再在 B 的右侧分割出 D m_dockManager-addDockWidget(ads::RightDockWidgetArea, dockB); m_dockManager-addDockWidget(ads::RightDockWidgetArea, dockD, dockB-dockAreaWidget());逻辑说明第三个参数是「参照区域」传了它新面板就相对这个区域定位而不是相对整个主窗口。这是实现嵌套的关键不传参照就只能做一层分割。参数说明区域枚举有LeftDockWidgetArea、RightDockWidgetArea、TopDockWidgetArea、BottomDockWidgetArea、CenterDockWidgetArea。CenterDockWidgetArea会把面板叠到中央区域适合做「主视图 可切换工具面板」的结构。3.2 浮动窗口与多显示器setFloating 与 allowedAreas浮动窗口是 ADS 相对原生控件提升最明显的地方。把一个面板设为浮动ads::CDockWidget* dockE new ads::CDockWidget(浮动面板); dockE-setWidget(new QLabel(我可以被拖到任意屏幕)); dockE-setObjectName(dockE); // 限制该面板只能停靠在左右两侧不允许上下 dockE-setAllowedAreas(ads::LeftDockWidgetArea | ads::RightDockWidgetArea); m_dockManager-addDockWidget(ads::RightDockWidgetArea, dockE); // 立即转为浮动窗口 dockE-setFloating();逻辑说明setAllowedAreas是约束用户拖拽范围的硬性限制做「某些面板不允许停到顶部」这类产品规则时用它比事后拦截拖拽事件干净得多。参数说明setFloating()无参调用会让窗口浮到默认位置也可以传QRect指定几何。多显示器场景下浮动窗口的坐标是全局屏幕坐标跨屏拖拽由 ADS 内部处理但要注意高 DPI 缩放下不同屏幕缩放比不一致时窗口尺寸可能跳变这是 Qt 层面的老问题不是 ADS 独有。3.3 标签页与关闭按钮的细粒度控制面板多了以后标签页行为需要精细控制。ADS 允许你决定面板是否可关闭、关闭后是否销毁、标签是否可拖出ads::CDockWidget* dockF new ads::CDockWidget(不可关闭面板); dockF-setWidget(new QLabel(我没有关闭按钮)); dockF-setFeature(ads::CDockWidget::DockWidgetClosable, false); // 去掉关闭按钮 dockF-setFeature(ads::CDockWidget::DockWidgetFloatable, true); // 允许浮动 dockF-setFeature(ads::CDockWidget::DockWidgetMovable, true); // 允许移动 dockF-setFeature(ads::CDockWidget::DockWidgetPinnable, false); // 去掉固定按钮逻辑说明setFeature是位标志逐个设置即可不要用setFeatures一次性覆盖否则容易把默认开启的特性误关。参数说明DockWidgetClosable关掉后用户无法通过 UI 关闭但代码仍可closeDockWidget()。DockWidgetPinnable控制那个「图钉」按钮做固定工作区时建议关掉减少用户误操作。4. 避坑与排查ADS 落地时最容易翻车的五个点4.1 面板恢复后位置全乱objectName 缺失现象保存布局后重启面板位置和保存时完全不一样甚至有的面板消失。原因restoreState靠objectName匹配面板没设objectName的CDockWidget无法被正确识别。解决每个CDockWidget创建后立即setObjectName且保证全局唯一建议用常量字符串集中管理避免手写拼错。4.2 拖拽时界面卡顿OpaqueSplitterResize 的代价现象面板里放了表格或图表后拖动分割条明显掉帧。原因OpaqueSplitterResize开启时每次鼠标移动都触发重绘内容复杂时开销大。解决内容重的面板场景下关掉该标志改为松手重绘或者给面板内容做延迟渲染拖动期间只画占位。4.3 关闭面板后内存泄漏默认不销毁现象反复开关面板内存持续上涨。原因CDockWidget默认关闭时只是隐藏不销毁。解决调用setFeature(ads::CDockWidget::DockWidgetDeleteOnClose, true)或在关闭信号里手动deleteLater()。注意销毁后如果布局还要恢复得重新创建面板。4.4 多显示器高 DPI 下浮动窗口尺寸跳变现象把浮动面板从 100% 缩放的屏幕拖到 150% 的屏幕窗口突然变大或变小。原因Qt 的高 DPI 缩放策略与窗口几何计算在不同屏幕间切换时的已知行为。解决在应用启动前设置合适的Qt::HighDpiScaleFactorRoundingPolicy并避免在浮动窗口里硬编码像素尺寸改用布局和相对尺寸。4.5 恢复布局时崩溃restoreState 在面板未创建前调用现象程序启动直接崩在restoreState。原因在CDockWidget还没全部创建时就调用了恢复。解决确保所有面板先创建并设好objectName最后再调restoreState。顺序错了ADS 内部拿不到对应面板指针空指针解引用就崩了。5. 进阶技巧用布局预设做「工作区切换」与验证方法做到这一步基础停靠已经稳了。真正拉开体验差距的是「工作区预设」——用户一键在「编辑模式」「调试模式」「预览模式」之间切换每个模式对应一套面板布局。实现思路是预先存多份QByteArray切换时先清空当前布局再恢复目标布局。// 保存当前布局为一个命名预设 void MainWindow::saveWorkspace(const QString name) { QSettings settings(MyOrg, DockDemo); settings.setValue(workspace/ name, m_dockManager-saveState()); } // 切换到指定预设 bool MainWindow::loadWorkspace(const QString name) { QSettings settings(MyOrg, DockDemo); QByteArray state settings.value(workspace/ name).toByteArray(); if (state.isEmpty()) return false; // 关键先关闭所有浮动窗口并清空避免旧布局残留 for (ads::CDockWidget* dock : m_dockManager-dockWidgetsMap()) { dock-toggleView(false); } return m_dockManager-restoreState(state); }逻辑说明切换预设前必须处理旧布局否则新旧面板会叠加。toggleView(false)是隐藏而非销毁保留面板实例恢复时能快速重建。dockWidgetsMap()返回所有已注册面板遍历时注意不要在循环里删除元素。参数说明预设名建议用枚举转字符串避免用户输入非法字符导致QSettings键名异常。如果预设对应的面板在当前版本已被移除restoreState会返回 false此时应提示用户并回退默认布局。验证方法上我习惯做三件事一是写一个自动化脚本反复执行「保存布局 → 重启 → 恢复 → 比对面板几何」的循环跑几十次看是否有随机错位二是在多显示器环境下手动拖拽所有面板到每个屏幕边缘观察是否有窗口丢失三是模拟低分辨率如 1366×768下打开全部面板确认没有面板被挤到不可见区域。这三步能覆盖绝大多数布局类 bug。最后说个血泪经验ADS 的布局状态和你的业务状态是两回事别把「面板是否可见」当成业务开关来用。我见过有项目把「某面板关闭」直接等同于「某功能禁用」结果用户恢复布局时功能莫名其妙被关。布局归布局业务归业务中间加一层显式的状态同步能省掉大量售后问题。希望帮到你。本文还有配套的精品资源点击获取