简介：面向需要处理复杂表格结构的Qt开发者，讲解如何基于QTableView与QAbstractItemModel实现多级表头。资源包共12个文件，以cpp、h源码为主，附带ui、pro工程文件，说明作者通过继承QHeaderView并重写paintSection、sectionSizeFromContents等关键方法，完成多级表头的绘制与尺寸计算，同时给出按键槽函数中刷新表头的注意事项与排错思路，便于读者直接对照工程理解实现细节。包体压缩后约17KB，轻量易用，适合有一定Qt基础、希望扩展表格控件的学习者参考。已有840人学习下载，示例工程结构完整，涵盖自定义表头类、模型关联、界面文件及编译配置，可快速导入Qt Creator验证效果。 QT的多级表头需求，我在今年接手的报表项目里算是彻底踩了一遍。产品经理丢过来一张Excel截图，第一行是“基本信息”“成绩数据”“操作”，第二行才展开“姓名”“性别”“语文”“数学”“编辑/删除”这些具体字段。这单子有十几列，而且后续字段还要动态加。我当时第一反应是用QTableView自带的QHeaderView改一改，结果翻了半天文档发现，QHeaderView只支持一维section，根本不提供parent-child结构。所以如何在QTableView上做出多级表头，就成了必须自己解决的问题。如果你也在为本地的统计报表、后台管理界面或工业上位机里的数据表格发愁，这篇文章的思路可以直接参考。
1. 项目背景与方案选型
1.1 多级表头挑起的“伪需求”与真实痛点
多级表头看起来只是把表头多画了一行，实际牵扯到三个层面的问题：数据结构、界面绘制、交互同步。如果你用Excel做表头，合并单元格就行；但在QT里，QTableView的列表头是线性的，列索引、列宽、滚动偏移全都围绕一维section展开，强行给表头叠加层级，会遇到三个绕不开的难点。
第一是列映射。一级表头的“成绩数据”横跨“语文”“数学”两列，那么点击一级表头区域时需要计算它覆盖了哪些列，并且这个映射要跟着字段增删动态变化。第二是绘制同步。一级表头要跟二级表头一起滚动，但QTableView的horizontalHeader会和viewport共用滚动条，如果你额外加一个表头控件，就得自己补齐滚动偏移和列宽变化。第三是视觉一致性。多级表头的分组块要有边框、有背景、有居中的文字，还要跟表格自身的QSS风格对上，否则一眼看去就是两块拼接的界面，非常掉价。
想清楚这些，就会明白多级表头不是简单的“在QTableView上面放几行QWidget”，而是一套从模型层到视图层的联动设计。
1.2 三种主流实现路线对比
在动手之前，我把社区里常见的做法整理了一遍，大致有三条路线，各有取舍。
| 实现方案 | 核心思路 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|---|
| 自绘QHeaderView | 继承QHeaderView，重写paintSection，把多个逻辑列画成一个分组块 | 不用额外控件，视觉和交互都贴近原生 | 实现复杂，左侧冻结列、排序指示器、resize命中区域都要自己处理 | 表头结构稳定、样式定制要求高 |
| 表格头部行+setSpan | 在表格数据区顶部预留几行，用setSpan合并单元格模拟多级表头 | 实现简单，复用现有单元格绘制 | 表头会跟随数据滚动，需要额外锁定滚动范围，数据与表头边界模糊 | 一次性报表、数据结构简单 |
| 复合表头方案 | 一级分组表头用独立QWidget绘制，二级表头继续用QTableView的horizontalHeader | 逻辑清晰，模型映射可计算，动态字段容易扩展 | 需要自己同步滚动和列宽 | 动态字段、可维护性要求高的项目 |
我做了一个对比表之后选了第三条：一级分组表头用自定义Widget，二级表头继续用QTableView原生表头。理由是这种方案把“分组关系”从绘制代码里抽出来了，数据模型驱动界面显示，后续就算字段从十几列增加到几十列，也只需要改配置，不必动绘制逻辑。
2. 数据结构与模型层：让分组关系成为可计算的依据
2.1 用HeaderGroup描述多级表头的映射关系
既然要动态维护字段，第一步就是把表头结构定义成数据，而不是把列头字符串写死在代码里。我在项目中定义了两个结构体，一个描述一级分组，一个描述一级分组下的二级列。
HeaderGroup里存分组名称和子列名称列表，childIndex是为了在建树的时候校验字段顺序而加的，实际列索引通过对子列遍历自动计算。
struct HeaderChild { QString name; // 二级列表头名称 int childIndex; // 子列在group中的序号 }; struct HeaderGroup { QString name; // 一级表头分组名称 QList<HeaderChild> children; // 该分组下的所有二级列 };这样，模型的列索引就有了两个维度的映射关系：全局列索引从0到columnCount()-1，一级分组则按照children的先后顺序把连续的列切分成若干区间。比如“基本信息”占第0列，“成绩数据”占第1到第2列，“操作”占第3列，每一列都能通过遍历HeaderGroup数组反查到它属于哪个分组、在分组内是第几个子列。
2.2 在QAbstractTableModel里处理两级表头
模型层是这一步的关键。我在自定义的TableModel里增加了一个headerGroups成员，并提供setHeaderGroups接口，让外部把配置好的分组信息注入进来。
class TableModel : public QAbstractTableModel { Q_OBJECT public: void setHeaderGroups(const QList<HeaderGroup>& groups) { beginResetModel(); m_groups = groups; m_columnCount = 0; for (const auto& group : m_groups) { m_columnCount += group.children.size(); } endResetModel(); } int columnCount(const QModelIndex& parent = QModelIndex()) const override { Q_UNUSED(parent); return m_columnCount; } QVariant headerData(int section, Qt::Orientation orientation, int role) const override { if (orientation == Qt::Horizontal && role == Qt::DisplayRole) { for (const auto& group : m_groups) { for (int i = 0; i < group.children.size(); ++i) { if (section < group.children.size()) { // ... 这里按全局列索引匹配 } } } } return QVariant(); } // data() 与其他模型方法省略 private: QList<HeaderGroup> m_groups; int m_columnCount = 0; };headerData的标准写法不建议写在遍历里判断section，更好的办法是先把HeaderGroup拍平成一张“列索引->列名”的映射表，这样headerData的查找复杂度是O(1)。项目里我是维护了一个QHash<int, QString> m_headerDisplay，在setHeaderGroups时同步生成，后续增删字段只改一次结构即可。
2.3 列宽管理：一级分组宽度自动求和
多级表头的列宽问题经常被忽略。一级表头的分组块宽度不是固定值，它应该是子列宽度的总和。比如“成绩数据”下面有两列，这两列一个宽120一个宽80，那“成绩数据”这个分组的宽度就应该是200。如果在代码里写死分组宽度，用户一旦拖动列宽，一级表头就会跟二级表头脱节。
所以我在GroupHeaderWidget里保留了一个groupWidths列表，每次horizontalHeader发出sectionResized信号时，遍历所有HeaderGroup，把每个分组对应的子列宽度相加，再统一刷新分组绘制。这段逻辑放到了主界面的初始化函数里，下面第3章会给出代码。
3. 界面层实现：浮动分组表头与原生表头的组合
3.1 自定义一级表头控件GroupHeaderWidget
一级表头我选择直接自绘，不堆QLabel，原因很现实：字段一变，QLabel数量就变，布局也要跟着重建，代码会迅速变成一团浆糊。而用QPainter绘制，只需要遍历HeaderGroup列表，根据groupWidths准确画出每个分组块即可。
class GroupHeaderWidget : public QWidget { Q_OBJECT public: void setGroups(const QList<HeaderGroup>& groups) { m_groups = groups; updateGeometry(); update(); } void setGroupWidths(const QList<int>& widths) { m_groupWidths = widths; update(); } void setOffset(int offset) { if (m_offset != offset) { m_offset = offset; update(); } } protected: void paintEvent(QPaintEvent*) override { QPainter painter(this); painter.fillRect(rect(), palette().base()); int x = -m_offset; for (int i = 0; i < m_groups.size(); ++i) { int w = (i < m_groupWidths.size()) ? m_groupWidths[i] : 100; QRect groupRect(x, 0, w, height()); // 绘制分组背景、边框与文字 painter.fillRect(groupRect, QColor(245, 245, 245)); painter.setPen(QPen(QColor(180, 180, 180))); painter.drawRect(groupRect.adjusted(0, 0, -1, -1)); painter.drawText(groupRect, Qt::AlignCenter, m_groups[i].name); x += w; } } private: QList<HeaderGroup> m_groups; QList<int> m_groupWidths; int m_offset = 0; };自绘的好处是一眼看得出分组边界，鼠标交互如果需要点击、拖拽，也可以在mousePressEvent和mouseMoveEvent里补逻辑。纯展示场景下，这个代码量已经非常可控。
这里有个容易踩的坑：paintEvent里坐标系是从0开始的，但表格滚动时，一级表头的内容需要向左平移。所以我把m_offset设计成滚动条value的相反数，滚动条往右拉，offset是正数，绘制时x从-offset开始，视觉上分组块就是往左挪的。这个方向逻辑务必测试到位。
3.2 面板悬停：一级表头放哪、二级表头多高
GroupHeaderWidget画好之后，需要摆到一个合适的位置。我的做法是垂直布局：上面放GroupHeaderWidget，下面放QTableView，两级表头看起来是连在一起的。为了让两行表头在视觉上区分开，我给GroupHeaderWidget设了固定高度28，二级表头水平表头高度设24。
m_groupHeader->setFixedHeight(28); m_table->horizontalHeader()->setFixedHeight(24); m_table->verticalHeader()->setVisible(false); m_table->setFrameShape(QFrame::NoFrame);隐藏垂直表头是因为如果我显示行号，一级表头就要在左边给行号列留出同样宽度的空间，否则分组块与列头错位。对于纯数据报表场景，隐藏行号通常不影响阅读，还能省去一个对齐难题。
布局示例：
auto* layout = new QVBoxLayout(centralWidget()); layout->setContentsMargins(0, 0, 0, 0); layout->setSpacing(0); layout->addWidget(m_groupHeader); layout->addWidget(m_table);如果项目里必须保留行号列，那就在水平布局里给GroupHeaderWidget左侧手动留出verticalHeader()->width()的宽度，并监听verticalHeader宽度变化实时调整。这个属于进阶需求，我放在第4章的扩展里展开。
3.3 水平滚动同步与列宽实时刷新
界面已经拼出来了，接下来是联动。QTableView的水平滚动条是唯一的滚动源，表格滚动时二级表头会跟着滚动，一级表头内容也必须同步平移。实现方式就是连接水平滚动条的valueChanged信号，把偏移交给GroupHeaderWidget。
connect(m_table->horizontalScrollBar(), &QScrollBar::valueChanged, this, [this](int value) { m_groupHeader->setOffset(value); });列宽同步则需要连接horizontalHeader::sectionResized信号。注意这个信号在鼠标拖动和代码修改列宽时都会触发，正好满足需求。
connect(m_table->horizontalHeader(), &QHeaderView::sectionResized, this, [this](int logicalIndex, int, int) { Q_UNUSED(logicalIndex); QList<int> widths; const auto& groups = m_model->headerGroups(); for (const auto& group : groups) { int total = 0; // 按group.children顺序累加table中对应列的宽度 // 需要先根据当前HeaderGroup计算出列索引 for (int i = 0; i < group.children.size(); ++i) { int column = currentColumnOfGroup(group, i); // 从模型取实际列索引 total += m_table->columnWidth(column); } widths.append(total); } m_groupHeader->setGroupWidths(widths); });这里有个小细节：HeaderGroup里的children顺序是固定不变的，但模型里的实际列索引在字段增删后会变，所以最好在模型里提供一个“按分组查列索引”的辅助方法，而不是在界面层去猜。推荐做法是先让模型维护一张groupIndex和全局列索引的映射，界面层只负责调用计算宽度的接口。
初始化时，手动调用一次列宽刷新逻辑，确保程序启动后一级表头没有残留的默认宽度。
4. 扩展与避坑：冻结列、动态字段与性能优化
4.1 前几列冻结后的表头对齐策略
报表场景里经常需要冻结前几列，比如“姓名”和“工号”在横滚时不能消失。QTableView原生冻结列需要重写paintEvent或使用双QTableView方案，一旦引入冻结，一级表头也要跟着拆成左右两块：左侧是冻结分组，右侧是滚动分组。
我用过相对稳妥的办法是把整个表格区域拆成左右两个QTableView，左边负责冻结列，右边负责滚动列，两个表同步垂直滚动。此时GroupHeaderWidget也分成左右两个实例，左边的离屏绘制固定列宽，右边的跟随右侧表格的滚动偏移平移。两侧之间用一条分隔线隔开，视觉上像Excel的冻结窗格。
这个方案代码量不小，核心难点是水平滚动时右侧表头不能带动左侧。我建议先把不冻结的基础版本跑起来，再根据项目需求决定要不要引入冻结。
4.2 动态修改表头结构：数据模型驱动的注意事项
我的需求是字段可以动态增删，这意味着HeaderGroup列表在运行时是变量，不是编译期常量。修改表头结构时的顺序不能乱：先改模型结构，再刷新视图列宽，最后刷新分组绘制。
正确顺序是：
- 调用
model->setHeaderGroups(newGroups)，内部走beginResetModel()/endResetModel()，让QTableView感知到列变化。 - 从模型拿到最新的
headerGroups()，同步给GroupHeaderWidget::setGroups。 - 手动触发一次列宽刷新，让一级表头的分组宽度与表格列宽对齐。
- 注意在resetModel期间不要持有旧的
QModelIndex，否则访问到已失效的索引，轻则界面错乱，重则崩溃。
如果字段变化很频繁，建议只在业务确认后的瞬间做一次重建，不要在循环里多次调用setHeaderGroups。QTableView的reset过程开销不小，连续点击按钮切换表头结构时可能会出现肉眼可见的闪烁。
4.3 大数据量下的渲染优化与常见错误排查
多级表头本身不复杂，但我会遇到一些奇怪的组合问题，这里整理成一张速查表。
| 表现 | 原因 | 处理方式 |
|---|---|---|
| 一级表头分组块位置整体偏移 | QTableView边框宽度或垂直表头宽度没对齐 | 给表格设NoFrame，隐藏垂直表头，或用setContentsMargins手动补偿 |
| 拖动列宽后一级表头宽度不同步 | sectionResized信号没接或groupId映射错误 | 检查信号连接，确认列宽累加使用的列索引来自模型映射 |
| 水平滚动时一级表头反向 | offset正负算反了 | 检查paintEvent中x的起始值，滚动条value增大应让绘制起点左移 |
| 分组块文字不清楚 | 绘制顺序颜色或边框遮挡 | 先画背景，再画边框，最后画文字；避免文字区域被边框覆盖 |
| 多级表头闪烁 | 每次update触发整个paintEvent，而分组数量多 | 仅在groupWidths或offset真正变化时调用update，可加局部脏区标记 |
数据量层面，如果TableView的列数有几十上百，建议开启QTableView的uniformRowHeights属性，并且给model实现canFetchMore/fetchMore做分页加载。多级表头的额外开销主要在GroupHeaderWidget的paintEvent里，分组的绘制是轻量级的，不会成为性能瓶颈，真正压力还是在数据模型和单元格绘制。
另外，一级表头的高度不要设太低。文本在28像素高度内居中没问题，但如果字号调到14px以上，还是建议把高度做到32左右，否则中文字体容易裁掉。
我在实际项目里踩过最深的坑就是“看代码时觉得三级结构很清晰，运行时发现一级表头跟列头永远差半个像素”。后来意识到，QTableView自身有边框、垂直表头有宽度，这些都要在处理表头对齐时统一考虑。后来我把所有与表头对齐相关的尺寸都集中到构造函数的初始化里，每次修改都通过调试输出确认，才彻底解决了错位问题。多级表头这个需求，说到底不是复杂的技术难题，而是一整套关于“映射、同步、绘制”的工程设计，你只要先把数据结构和联动关系理清楚，后面用我的这套路子复刻一遍，基本不会有大问题。
本文还有配套的精品资源，点击获取
