Qt 高级开发 024：QSplitter分裂器布局精讲

[Bilibili 同步视频](#Bilibili 同步视频)
✨前言
[一、Qt 设计师可视化实现分裂器布局📐](#一、Qt 设计师可视化实现分裂器布局📐)
- [1. 项目初始化](#1. 项目初始化)
- [2. 添加基础控件并样式美化](#2. 添加基础控件并样式美化)
- [3. 竖直分裂器快速布局](#3. 竖直分裂器快速布局)
- [4. 嵌套水平分裂器实现左右布局](#4. 嵌套水平分裂器实现左右布局)
- [5. 边界适配防隐藏设置](#5. 边界适配防隐藏设置)
[二、纯代码手写 QSplitter 布局💻](#二、纯代码手写 QSplitter 布局💻)
- [1. 核心原理铺垫](#1. 核心原理铺垫)
- [2. 核心示例代码](#2. 核心示例代码)
- [3. 关键代码性能 & 属性解析🔍](#3. 关键代码性能 & 属性解析🔍)
[三、QSplitter 核心 API 拓展📚](#三、QSplitter 核心 API 拓展📚)
四、实际应用场景🌐
五、后续学习预告⏳
✨结语

Bilibili 同步视频

Qt 高级开发 024：QSplitter分裂器布局精讲

✨前言

在 Qt 桌面开发中，分裂器布局 QSplitter 是日常开发里超高频的布局方式，和普通垂直、水平布局有着本质区别。

像 PPT 左侧图标栏 + 右侧内容区、PDF 书签侧边栏 + 正文区、软件可拖拽分割的左右 / 上下面板，底层全靠Splitter 分裂器实现，支持鼠标自由拖拽分割边界、自适应窗口大小、嵌套组合布局，实用性拉满💫。

本文带你从零上手，两种实现方式全覆盖：Qt 设计师可视化拖拽布局 + 原生代码手写布局，附带原理解析、踩坑要点与核心 API 说明，新手也能轻松吃透～

一、Qt 设计师可视化实现分裂器布局📐

1. 项目初始化

打开 Qt Creator ，新建 Qt 项目，命名为splitter，基础窗口控件选用Widget作为底层父容器，依托 Qt 设计器 UI 界面完成可视化布局搭建。

2. 添加基础控件并样式美化

先在 UI 界面中添加两个 QWidget 控件，作为上下分割的基础面板；
为了直观区分控件边界与大小，通过样式表 QSS设置背景色，借助 RGB 色值填充底色；
复制样式属性给两个 Widget 分别赋值，快速完成视觉区分，避免控件重叠看不清边界。

3. 竖直分裂器快速布局

选中添加好的两个 QWidget 控件，在工具栏找到竖直分裂器（垂直 QSplitter） 图标并点击：

控件会自动纳入竖直分裂器管理，支持鼠标上下拖拽调整高度；
原生直接嵌套存在小缺陷：初始控件尺寸过小、手动拉伸不好控制比例。

💡优化小技巧：

可先给整体容器设置竖直布局，再嵌入分裂器控件，能有效约束控件初始比例，解决拖拽失控问题。

4. 嵌套水平分裂器实现左右布局

额外新增一个独立控件作为左侧侧边栏；
将左侧控件 与右侧竖直分裂器整体面板 ，组合添加到水平分裂器中；
在窗口空白处右键，给全局设置水平 / 竖直根布局，让整个界面随窗口自适应缩放。

5. 边界适配防隐藏设置

开发中极易出现拖拽过度导致面板完全隐藏的问题✅ 解决方案：

给左右上下面板设置最小宽度为 100px，限定收缩临界值，既保留拖拽灵活性，又不会出现控件消失、界面布局错乱的情况。

二、纯代码手写 QSplitter 布局💻

除了 UI 可视化拖拽，实际项目中更多场景需要纯代码动态创建分裂器布局，无需依赖 UI 设计文件，灵活性更强、适配性更高。

1. 核心原理铺垫

QSplitter 继承自 QWidget，本身就是标准控件，支持嵌套使用；
分为两大类型：水平分裂器 Qt::Horizontal 、竖直分裂器 Qt::Vertical；
自带addWidget()方法，可往分裂器中嵌套添加普通 Widget，甚至分裂器嵌套分裂器，实现复杂多区域分割。

2. 核心示例代码

cpp 复制代码

#include <QApplication>
#include <QWidget>
#include <QSplitter>
#include <QHBoxLayout>
#include <QFrame>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    QWidget w;
    w.resize(800, 500);

    // 1. 创建水平分裂器（整体左右分割）
    QSplitter *hSplitter = new QSplitter(Qt::Horizontal);

    // 左侧侧边栏窗口
    QWidget *leftWidget = new QWidget;
    leftWidget->setMinimumWidth(100);  // 最小宽度限制防隐藏
    leftWidget->setStyleSheet("background-color: rgb(54,54,54);");

    // 2. 创建竖直分裂器（右侧上下分割）
    QSplitter *vSplitter = new QSplitter(Qt::Vertical);
    
    // 右侧上下两个面板
    QWidget *topWidget = new QWidget;
    QWidget *bottomWidget = new QWidget;
    topWidget->setStyleSheet("background-color: rgb(200,200,200);");
    bottomWidget->setStyleSheet("background-color: rgb(150,150,150);");

    // 3. 往竖直分裂器添加上下面板
    vSplitter->addWidget(topWidget);
    vSplitter->addWidget(bottomWidget);

    // 4. 关键属性：拖拽实时生效配置
    vSplitter->setOpaqueResize(false);
    // false：鼠标松开后才刷新分割位置
    // true：拖拽过程中实时刷新界面

    // 5. 水平分裂器嵌套左侧面板 + 右侧竖直分裂器
    hSplitter->addWidget(leftWidget);
    hSplitter->addWidget(vSplitter);

    // 全局水平布局装载分裂器
    QHBoxLayout *mainLayout = new QHBoxLayout(&w);
    mainLayout->addWidget(hSplitter);
    mainLayout->setContentsMargins(0,0,0,0);

    w.show();
    return a.exec();
}

3. 关键代码性能 & 属性解析🔍

setOpaqueResize 核心配置
- 设为false：拖拽分割线时界面不实时变化，鼠标松开后才更新布局，低配置设备更流畅，减少刷新卡顿；
- 设为true：拖拽过程实时刷新面板大小，视觉体验更好，高配设备推荐开启。
最小尺寸限制 setMinimumWidth

强制限定面板最小宽度，从根源避免拖拽过度导致侧边栏、子面板被完全隐藏，是项目开发必加防护配置。
分裂器嵌套特性

QSplitter 作为 QWidget 子类，天然支持addWidget()嵌套，轻松实现左 - 右、上 - 下多级分割，满足复杂软件界面布局需求。

三、QSplitter 核心 API 拓展📚

研读 QSplitter 头文件可掌握更多实用接口，日常开发灵活调用：

insertWidget(int index, QWidget *widget)：按索引位置插入控件；
replaceWidget(int index, QWidget *widget)：替换指定位置的面板控件；
setSizes(const QList<int> &list)：自定义各面板初始尺寸比例；
count()：获取分裂器内子控件数量；
widget(int index)：按索引获取对应子控件。

这些 API 可动态控制分裂器布局、运行时增减面板，适配动态界面开发场景。

四、实际应用场景🌐

QSplitter 分裂器布局在各类软件中随处可见：

办公类：PPT/Word 左侧导航栏 + 右侧编辑区；
文档类：PDF 阅读器书签侧边栏 + 正文阅读区；
开发工具：Qt Creator、VS Code 左右工程目录 + 代码编辑区、上下日志输出区；
自研桌面软件：自定义可拖拽多窗口分割面板。

五、后续学习预告⏳

文中代码出现的setLayout布局挂载核心方法，其底层原理、布局与控件的嵌套逻辑、根布局设置的注意事项，将在下一节做深度拆解，帮大家彻底打通 Qt 布局体系逻辑～

✨结语

Qt QSplitter 分裂器布局可视化拖拽快速上手，纯代码灵活定制，掌握嵌套规则与核心属性配置，就能搞定绝大多数桌面软件的可拖拽分割界面，是 Qt 开发必备核心技能之一，建议动手实操一遍，加深理解～