QSplitter 是 Qt 里一个特别容易被忽略的组件，但这几年做桌面端工具，我几乎每个项目都离不开它。如果你需要在界面里提供"可拖拽分割区域"的能力——比如编辑器左右分栏、文件管理器树状目录加详情列表、参数面板的上下折叠——QSplitter 就是最正统的解法。这篇总结我把实际开发中踩过的坑、用顺手的模式、以及一些网上不太常提的小技巧全部整理出来，从基础用法到内存和性能细节都覆盖到，适合刚接触 Qt 的初学者，也适合那些已经写过 QSplitter 但想更深入了解它脾气的老手。
1. 先聊清楚：QSplitter 到底是干什么的
1.1 从真实需求说起
做桌面应用时，遇到的第一个"不满足于静态布局"的场景通常是：界面需要让用户自己调整区域大小。比如做一个代码编辑器，左边是文件树，右边是代码区域，用户想多看几行列代码，就得能拖拽中间的边界线。用 QLayout 的 QHBoxLayout 加 QVBoxLayout 能完成静态分配，但一旦用户拖动窗口整体大小，所有区域按固定比例收缩，体验非常生硬。
QSplitter 解决的就是这个"区域之间边界可拖动"的问题。它本质上是一个容器组件，把若干个子部件排成一行或一列，中间自动生成可拖动的分割条（handle），用户拖动分割条时，相邻子部件的尺寸会动态调整。这个拖拽过程完全由 Qt 内部处理，不需要你自己写鼠标事件，也不需要手动计算子部件几何尺寸。
1.2 为什么不用 QLayout 硬算
很多人第一次做可调分区的需求时，第一反应是"我自己监听鼠标事件，改 layout 的 stretch 不也能实现吗"。理论上可以，但代价非常大。你需要处理鼠标按下、移动、释放的完整状态机，需要维护每个子部件的尺寸比例，还要考虑最小尺寸约束、窗口 resize 时的联动、以及不同高 DPI 缩放下像素密度变化。这些边界情况加在一起，代码量轻松翻两三倍，还特别容易出现细微的交互 bug。
QSplitter 把这套东西完整封装了。它自己负责分割条的鼠标交互，负责子部件尺寸分配，负责与父级布局的配合。你要做的只是把子部件塞进去，设置好最小尺寸、初始尺寸、伸缩因子这三个参数，剩下的交给它。我后来写代码有个习惯：凡是涉及"若干区域需要用户手动调节尺寸"的需求，第一选择永远是 QSplitter，除非产品明确要的是完全自定义的交互形态。
1.3 最基本的三行代码
先来看一个最小可运行示例，把两个 QTextEdit 左右排列：
QSplitter *splitter = new QSplitter(Qt::Horizontal, this); QTextEdit *leftEditor = new QTextEdit("Left", splitter); QTextEdit *rightEditor = new QTextEdit("Right", splitter); splitter->setWindowTitle("Splitter"); splitter->resize(800, 600); splitter->show();这段代码就能生成一个 800x600 的窗口，中间有一条垂直分割线，用户可以直接拖动分割线改变左右两侧宽度。QSplitter 的构造函数第一个参数是方向：Qt::Horizontal 表示子部件横向排列、分割条是竖的；Qt::Vertical 表示子部件竖向排列、分割条是横的。
这个简单的例子背后有个容易忽略的点：左编辑器和右编辑器都直接将 splitter 作为 parent。这意味着 QSplitter 接管了它们的布局所有权，会按照内部规则自动排列。你不需要额外 new 布局器，也不需要调用 setGeometry。不过子部件之间的尺寸怎么分配，默认规则是所有子部件均分。现实项目中，很少有人希望两个区域永远五五开，所以马上要进入下一节的核心参数。
2. 核心 API 与参数选型，这些才是关键
2.1 初始尺寸到底听谁的
QSplitter 分配子部件尺寸时有一个优先级顺序，很多人一开始搞反了。完整的决策过程是这样的：先看子部件的最小尺寸约束（minimumSizeHint 与 minimumSize），再看初始分配时的比例权重（setStretchFactor），最后看有没有人为设置过初始尺寸（setSizes）。
setSizes 是最直观的接口，传入一个 QList ，每一项对应子部件的像素尺寸：
splitter->setSizes({300, 500});但这行代码的执行时机很关键。如果在 show 之前调用，splitter 会据此计算子部件的初始宽度；如果在 show 之后调用，它会立刻调整子部件并触发重排。两者行为基本一致，但有一个经典陷阱：setSizes 传入的是"建议值"，不是"强制值"。如果传入的值小于子部件的最小尺寸，QSplitter 会自动忽略这个值并改用最小尺寸。这就是为什么有些开发者发现 setSizes 调了等于没调——子部件内部有隐式的 minimumSizeHint，比如 QTextEdit 的默认内容行数会产生一个不小的最小宽度，你传 50，它直接给你顶到 256。
解决办法是在设置尺寸前，先显式设置子部件的 minimumSize 或者 maximumSize。更稳妥的做法是同时配合 setStretchFactor，而不是只依赖 setSizes 一个接口。
2.2 setStretchFactor 的真实语义
setStretchFactor(index, stretch) 这个接口在网上被很多人当"布局比例"来用，但实际上它的语义和 QLayout 的 stretch 完全不同。QLayout 里的 stretch 是控制"窗口放大时，空间按照什么比例分配"。QSplitter 里的 stretch 控制的是"当我尝试调整分割条或设置大小时，变化量如何在两边分配"。
举个例子，一个横向 QSplitter 里有两个子部件 A 和 B。你调用 splitter->setStretchFactor(0, 1)，再调用 splitter->setStretchFactor(1, 2)，表面上看是希望 A:B 按 1:2 分。真实的行为是：当整个 splitter 的可用宽度变化时，某个方向的尺寸增量会更多地分给 B，而不是分给 A。如果 splitter 本身尺寸不变，setStretchFactor 对现有布局没有任何影响。
这里我见过不少项目直接 setStretchFactor 后窗口形态很奇怪，原因就在此。真正要控制初始比例，应该用 setSizes 或者干脆在子部件上设置合理的 minimumSize，传导给 splitter 去计算。setStretchFactor 适合用在这种场景：窗口整体变大时，希望某个区域占用大部分新增空间，让另一个区域保持相对稳定。
2.3 子部件最小尺寸的约束逻辑
QSplitter 在计算子部件尺寸时永远遵循最小尺寸优先。这个是最底层的约束，不能被 setSizes 和 setStretchFactor 绕过。每个继承自 QWidget 的类都有 minimumSizeHint，QSplitter 默认会遵守它。比如一个 QListWidget 的 minimumSizeHint 可能是 120 宽 300 高，你哪怕 setSizes 里写了 50，最终也会被拉回 120。
想突破这个约束，就只能主动改子部件的 minimumSize：
leftEditor->setMinimumWidth(80);改成 80 之后，QSplitter 就能把左区域压缩到 80。这个特性在实现"折叠面板"时特别有用：把某个子部件的 minimumSize 设为 0，用户就能把区域拖到完全消失。实际使用中我还发现一个经验：不要在 splitter 内部放一个"最小尺寸非常夸张"的控件，比如内部放了长文本的 QLabel 或大表格，否则分割条拖到临界点时会非常硌手，而且这些内部尺寸变化会间接改变 splitter 的行为，导致布局突然跳动。对这类控件，最好在 setParent 到 splitter 后主动设置一个合理的最小尺寸，把控制权交还给布局。
3. 实操记录：做一个可拖拽分栏的编辑器框架
3.1 界面架构怎么设计
我的一个具体案例是做一个"笔记编辑器"，界面分三块：左侧是笔记列表，中间是编辑区，右侧是辅助信息面板。这个结构如果用嵌套 splitter 来做，比任何布局器方案都清晰：
主窗口 └── QSplitter(Horizontal) # 外层 ├── 笔记列表 QListWidget └── QSplitter(Vertical) # 内层，右侧区域 ├── 编辑区 QPlainTextEdit └── 辅助面板 QTextEdit（只读）外层横向分割，内部纵向分割，这样用户既能调左侧列表和右侧整体的宽度，又能独立调整右侧编辑区与辅助面板的高度。嵌套 splitter 是 QSplitter 最常见的进阶用法，看起来很复杂的界面，拆成几个 splitter 节点就好理解了。
设计时有一个决策需要说清楚：为什么辅助面板不放在外层 splitter 里当独立的第三列？如果三种区域的交互都是"左右拖拽"，确实可以三列平铺。但这样编辑区的高度就固定了，没法通过上下拖动来压缩辅助面板。嵌套之后，用户可以先把辅助面板整体压扁，再把它整个拉宽，灵活度完全不同。产品的用户中有人长期开着辅助面板，有人根本不用它，嵌套方案两边都照顾到了。
3.2 代码实现与关键参数配置
下面是这个笔记编辑器主体窗口的核心代码，我以 Qt 5.15 / Qt6 的 C++ 写法为主：
#include <QSplitter> #include <QListWidget> #include <QPlainTextEdit> #include <QTextEdit> #include <QSettings> class NoteWindow : public QWidget { public: NoteWindow(QWidget *parent = nullptr) : QWidget(parent) { // 外层横向 splitter m_outerSplitter = new QSplitter(Qt::Horizontal, this); // 左侧笔记列表 m_listWidget = new QListWidget(m_outerSplitter); m_listWidget->setMinimumWidth(120); m_listWidget->setMaximumWidth(400); // 右侧嵌套纵向 splitter m_innerSplitter = new QSplitter(Qt::Vertical, m_outerSplitter); m_editor = new QPlainTextEdit(m_innerSplitter); m_editor->setPlaceholderText("在这里记录你的想法..."); m_editor->setMinimumHeight(200); m_sidePanel = new QTextEdit(m_innerSplitter); m_sidePanel->setReadOnly(true); m_sidePanel->setMinimumHeight(80); // 初始尺寸分配：外层 [列表，右侧整体] = [200, 600] m_outerSplitter->setSizes({200, 600}); // 右侧区域【编辑区，面板】 = [400, 150] m_innerSplitter->setSizes({400, 150}); // 伸缩因子：窗口变大时，外层右侧多拿空间，内层编辑区多拿空间 m_outerSplitter->setStretchFactor(0, 0); m_outerSplitter->setStretchFactor(1, 1); m_innerSplitter->setStretchFactor(0, 1); m_innerSplitter->setStretchFactor(1, 0); QVBoxLayout *layout = new QVBoxLayout(this); layout->setContentsMargins(0, 0, 0, 0); layout->addWidget(m_outerSplitter); } private: QSplitter *m_outerSplitter; QSplitter *m_innerSplitter; QListWidget *m_listWidget; QPlainTextEdit *m_editor; QTextEdit *m_sidePanel; };这段代码里需要注意的细节我在实际开发中反复确认过，值得逐条说。
先看 setSizes 的数值。外层传的是 {200, 600}，但右侧是一个嵌套的 QSplitter，此时 splitter 计算子部件尺寸时会先向右侧整体索要 minimumSizeHint，右侧整体的 minimumSizeHint 是它内部两个子部件 minimumSizeHint 之和，所以 600 完全没问题。列表设了最大宽度 400，这限制了用户最多把列表拖到多宽，右侧永远保有至少一部分空间。
再看小尺寸限制。QPlainTextEdit 默认的 minimumSizeHint 会随内容变化，如果用户写了很长很长的英文行，编辑区的最小宽度会被拉得很大，影响分割条拖动。所以代码里没有设置 minimumWidth，只设置了 minimumHeight，让宽度交给外层 splitter 统一管理。这是一条实战经验：最小尺寸的设置要分清"精确控制"和"兜底保护"，不必每个子部件都设置完整的限制，重点限制那些尺寸失控会毁掉布局的部件。
3.3 保存和恢复分割条位置
QSplitter 的布局状态必须要做持久化，否则用户每次启动软件都要重新拖一遍，体验直接归零。Qt 提供的最直接方法是保存 splitter 的 QByteArray 状态：
// 保存 QSettings settings("MyCompany", "NoteApp"); settings.setValue("outerSplitterState", m_outerSplitter->saveState()); settings.setValue("innerSplitterState", m_innerSplitter->saveState()); // 恢复 QByteArray outerState = settings.value("outerSplitterState").toByteArray(); QByteArray innerState = settings.value("innerSplitterState").toByteArray(); if (!outerState.isEmpty()) { m_outerSplitter->restoreState(outerState); } if (!innerState.isEmpty()) { m_innerSplitter->restoreState(innerState); }saveState 返回的 QByteArray 里保存了分割条的位置、每个子部件的尺寸和伸缩因子。恢复时如果用户界面和保存时的结构一致，基本能精确还原。
这里有一个版本兼容问题的坑。saveState 的数据格式内部有一个版本号，restoreState 会检查它。如果应用升级后 QSplitter 子部件的数量或顺序发生变化，旧的分割状态可能恢复出错，表现为所有尺寸都乱了。稳妥的做法是给保存的状态前面加一个自己的版本标记：
QByteArray state = m_outerSplitter->saveState(); state.prepend("v1"); settings.setValue("outerSplitterState", state);恢复时先校验前缀，一旦版本不匹配就直接忽略旧状态，让用户按默认布局启动。这样可以避免升级后出现"布局乱七八糟"之类的问题。
还有一个细节很多人不知道：restoreState 之后，最好再调用一次 setSizes 强制刷新，因为某些平台下恢复状态不会触发子部件的重排。我的写法是恢复完加一句：
m_outerSplitter->setSizes({200, 600});这句会在 restoreState 的基础上再次校正，确保实际显示和期望一致。这个操作不会破坏 restoreState 的结果，因为 setSizes 处理的是建议值，而 restoreState 处理的是精确状态，两者叠加后的最终效果是"状态已恢复，且不会因为窗口最小尺寸导致不可见"。
4. 进阶玩法：从嵌套到程序化控制再到 QSS 定制
4.1 更自由的动态增删子部件
QSplitter 可以在运行时动态增删子部件，配合 QSplitterHandle 的拾取逻辑，可以做一个"可折叠侧边栏"。做法很简单：准备好一个隐藏的 QWidget，在需要时调用 insertWidget(index, widget) 插入，不需要时调用 widget->hide() 或者从 splitter 中移除并 hide。
我写过一个参数面板的展开折叠功能，核心逻辑就是用 hide/show 控制，而不是真的把子部件从 splitter 里删除。原因在于：insertWidget 会重新触发 splitter 的尺寸分配算法，闪烁感和跳动感比 hide/show 明显得多。hide 一个子部件后，splitter 会自动把它身边的区域让出来；showe时也会自动归还空间。这个机制对我来说是最流畅的。
但要注意：hide 一个子部件后，splitter 不会自动显示/隐藏对应的分割条。当面板隐藏时，目录区域和编辑区域中间可能留有残影分割条或一个无效间距。处理方法是结合 setHandleWidth(0) 做一个开关切换。我在项目里维护了一个"面板折叠状态"的布尔变量，折叠时把相关 handle 的全部宽度设为 0，展开时再恢复成默认值，手感和主流 IDE 的折叠行为非常接近。
4.2 程序化控制分割条位置
有些场景下，分割条的位置需要由代码控制，而不是用户手动拖拽。比如点击一个工具栏按钮，让某个区域占比变为 40% 或 60%。最简单的做法是给每个子部件设定相同的比例数，然后调用 setSizes。
但如果要做"平滑动画"，就得绕过 setSizes，自己在一段时间内逐步微调。这里有一个比较优雅的写法：
// 假设 splitter 两个子部件，目标比例为 3:7 // 当前宽 900，目标尺寸是 270 和 630 // 用 QPropertyAnimation 动画 handle 位置 QPropertyAnimation *animation = new QPropertyAnimation(m_handle, "pos"); animation->setStartValue(m_handle->pos()); animation->setEndValue(QPoint(targetX, m_handle->pos().y())); animation->setDuration(200); animation->start();不过直接 animate handle 会破坏 splitter 内部的尺寸分配一致性，动画过程中分割条移动和子部件尺寸不同步，很容易出现闪烁。我试过以后放弃了这条路线，改用定时器逐步调整尺寸：
const int steps = 20; for (int i = 1; i <= steps; ++i) { int leftSize = startLeft + (targetLeft - startLeft) * i / steps; splitter->setSizes({leftSize, totalWidth - leftSize}); QApplication::processEvents(); // 让界面及时刷新 }这段代码会产生一个 20 帧的渐进动画，效果足够平滑。为什么不用动画框架？因为 setSizes 的代价很低，它只需要重新布局，不涉及复杂渲染，20 帧完全能跑满。这个方案兼容性也最好，不依赖 Qt Quick。
4.3 QSplitter 的 QSS 样式定制
QSplitter 和它的 handle 都可以用 Qt 样式表定制。分割条默认效果在深色主题下非常丑，一条灰白色粗线会把整个界面的质感拉低。用 QSS 可以把它修得干净利落：
QSplitter::handle { background-color: #d0d0d0; width: 1px; height: 1px; } QSplitter::handle:hover { background-color: #4a90d9; } QSplitter::handle:vertical { border-top: 2px solid transparent; border-bottom: 2px solid transparent; } QSplitter::handle:horizontal { border-left: 2px solid transparent; border-right: 2px solid transparent; }这段样式把原本的粗条换成了 1px 细线，hover 时高亮成蓝灰色。这样"可拖拽"的视觉暗示反而更强了，因为细线让用户看清哪条边界可以拖动。
还有一些细节：设置 handle 的 margin 属性可以让拖拽热区变宽，但视觉保持细线。例如：
QSplitter::handle:horizontal { width: 4px; margin-left: -2px; margin-right: -2px; }这样实际可拖拽的宽度是 4px，视觉上还是一条细线。这种做法在触屏设备上尤其重要，因为手指需要更大的热区才能精准操作。
5. 常见问题与排查技巧实录
5.1 分割条拖不动，或者拖起来很"肉"
这一般是子部件的最小尺寸导致的。某个子部件的 minimumSizeHint 很大，或者人为设置了很大的 minimumSize，分割条拖动范围就被极限压缩了。排查方法非常简单：先临时把所有子部件的 setMinimumWidth/Height 设为 0，再看是否恢复正常。如果恢复正常，就一个个加回来，定位是哪个控件限制了范围。
另一种拖不动的情况是外层布局器把 splitter 的尺寸锁死了。假如你把 QSplitter 放在一个 QHBoxLayout 里，并且 layout 的 spacing 为 0，那么 splitter 自身的固定尺寸可能被外部约束，子部件尺寸再怎么调也不会变。解决思路是给 splitter 设置合理的 sizePolicy，让它能自由伸缩。
5.2 子部件被完全"吃掉"了
用户拖着拖着，某个区域变成一条细线甚至消失。多数情况是用户拖过了头，但区域的最小尺寸是 0，所以消失了。你当然可以在业务上允许消失（折叠面板的常规行为），但如果是误操作，用户下次打开时发现自己列表不见了，体验就很差。
推荐的做法是给不希望消失的子部件设置一个最小值，并且这个最小值在布局上要有实际意义，比如列表最小 150px。对于确实想折叠的面板，设置最小尺寸为 0，同时配合第一节面板的"折叠"动作，而不是让用户自由拖到消失。因为自由拖拽消失的操作路径不稳定，用户不知道怎么做才能还原。
5.3 窗口启动时闪烁一下，然后尺寸突然变化
这个问题经常出现在"先默认布局，再 restoreState"的时候。默认布局可能是宽 7:3，恢复成了 3:7，中间产生一个明显的跳动。如果软件每次启动都这样，用户会觉得自己上次的设置没有生效。
解决办法有两个。一是把 restoreState 的时机放在窗口第一次显示之前完成。可以在构造函数里执行 restoreState，然后调用 show 之前 setSizes 校准，这样尺寸不会闪烁。二是如果确实想先显示默认布局再恢复，就等到 showEvent 的第一次触发时再恢复，这个时机通常在首个帧渲染之后，不过需要做好事件循环的处理，否则可能看到先画面后跳变。我优先用第一种方案。
5.4 setSizes 的"软硬"性质导致的比例不对
在 3.2 节的代码中，我调用了 setSizes({300, 700})，但运行后左右比例并不对。前面已经解释过这是 minimumSizeHint 的干涉。我补充一个更细致的排查点：如果你调 setSizes 之前没有让 splitter 先获取到一个真实尺寸，那么子部件的尺寸计算会非常不准确。
QSplitter 的内部布局依赖自身的大小。在构造函数里就调用 setSizes 时，splitter 的 width 可能仍是默认的 100，这时候计算出的分配结果自然不会是"300px 对应 30%"。解决办法是先给 splitter 设置一个合理的基础尺寸（resize 或由父布局推导），再调用 setSizes。在 setSizes 里写"目标比例，而不是绝对像素值"会更稳妥。比如假设 splitter 最终会用 900px 宽，那我就写 setSizes({270, 630})；如果窗口尺寸可能触发宽度的变化，最好在 resizeEvent 里重新按比例调整，或者只依赖 setStretchFactor。
5.5 高 DPI 屏幕下的分割条过细
原来在 96 DPI 下 4px 的分割条在 2K 高分屏上看似只有 1.5px，伸出手指都按不准。除了前文 QSS 的 margin 技巧之外，还有一个方案：重写 QSplitterHandle 的 sizeHint 方法。继承 QSplitter 后，返回一个比默认更大的 handle 宽度：
class MySplitterHandle : public QSplitterHandle { public: explicit MySplitterHandle(Qt::Orientation orientation, QSplitter *parent) : QSplitterHandle(orientation, parent) {} QSize sizeHint() const override { int len = 8; return orientation() == Qt::Horizontal ? QSize(len, height()) : QSize(width(), len); } };然后重写 QSplitter 的子类工厂方法。这个方案比 QSS 的 margin 技巧更彻底，因为它是从布局系统层面决定分割条的实际宽度，不依赖样式表的近似计算。缺点是需要额外子类化和传递，工程复杂度高一点。如果只是桌面软件内部使用，我觉得用 QSS 的 margin 方案就够了，更简单。
6. 我踩过的坑和留给自己的操作清单
最近一次项目里，我因为没注意 QSplitter 的 stretch 与 QLayout 语义的差异，把整个右侧面板的伸缩因子写反了，窗口一拉大，辅助面板先膨胀起来，编辑区反而缩成一条线。排查了半小时才反应过来。后来总结出一条操作规范：在任何 QSplitter 相关代码里，一定要先写清楚"窗口变大大时，我希望哪个区域获得新增空间"，然后再决定 setStretchFactor 的参数。
还有一次是写参数面板折叠功能，我直接把子部件从 splitter 里 removeWidget 了，导致后面的 restoreState 崩溃。removeWidget 之后，子部件虽然还显示，但其父对象关系已经被打破，保存的状态里会记录一个已经不存在的索引，restoreState 时各种怪异行为就来了。后来统一改成了 hide/show，问题再也没有出现过。
最后分享一个实用技巧：开发调试 QSplitter 布局时，可以临时在每个子部件上设置背景色，最高效地观察各自的边界尺寸。我常用一行宏定义切换调试背景，比如：
#define DEBUG_SPLITTER_COLOR(widget, color) widget->setStyleSheet("background-color:" color ";")把列表设成淡红、编辑区设成淡绿、辅助面板设成淡蓝，布局问题一眼就能定位。正式发布前把这些调试色全部去掉。这个方法帮我节省了大量时间，尤其是嵌套 splitter 场景。
对我个人而言，QSplitter 是那种"越用越顺手"的组件：它解决的不仅是布局参数，而是整个交互层"用户控制空间"的问题。多花点心思把最小尺寸、伸缩因子、状态保存这三板斧练好，它就能从一个小控件变成整个桌面端产品体验中加分最多的部分。
