Qt表格多行表头实现：QHeaderView自绘与setSpan假表头方案

简介：这是一份基于Qt框架的QTableWidget多行表头完整示例工程，面向需要实现复杂表格表头的Qt初、中级开发者。资源通过单元格合并与自定义表头item的方式，演示了横向表头与纵向表头设置多行文本的可行方案，覆盖表头项创建、文本对齐、QHeaderView尺寸模式调整等关键细节。压缩包共6个文件，包括2个cpp源文件、1个h头文件、1个ui界面文件、1个pro工程文件和1个user配置文件，整体仅5KB，结构紧凑，方便直接打开工程对照学习。已有2646人学习下载，可见该需求具有普遍参考价值。通过阅读源码和实际运行示例，读者可以快速掌握QTableWidget自定义表头的实现思路，并直接移植到自己的项目中使用，有效节省摸索时间。 做了几年Qt桌面端，最怕听到“帮我在表格里加个多行表头”。业务方说得很轻松：“第一行‘产品信息’给我合并两列，下面再拆‘名称’和‘价格’，第二行‘日期’下面再套一层‘季度’。”刚开始我觉得这不是有手就行，结果一试QHeaderView才发现，Qt默认的列头就是一条直线，所有列名平平整整排在那，根本没有“树形分组”这种概念。为了搞定Qt表格多行表头/复杂表头，我前后试了模型造假表头、自绘QHeaderView，再对比第三方控件三种路线。这篇文章把每个方案的原理、代码、翻车点一次说清，适合刚接到复杂表头需求、想少走弯路的Qt开发者。

1. 为什么常规QHeaderView画不出“两行表头”

先搞清楚一个底层问题：QTableView里的表头不是数据模型的一部分，而是独立的QHeaderView控件。QHeaderView把水平方向看成“一排列节（section）”，每个节对应一个逻辑列索引，绘制时按节从左到右平铺。你通过headerData()返回的字符串，最终只是被当成某个节的文本画出来。QHeaderView本身根本不知道“这个节隶属于哪个分组”。

1.1 QHeaderView的单行绘制机制

QHeaderView内部最核心的方法是paintEvent，大致流程是：遍历当前可见的section，对每个section调用paintSection，在对应的矩形区域里填充背景、画文本、画边框。默认情况下，每个section只有一行文本，而且高度是统一的defaultSectionSize。

也就是说，如果你想在第一级表头里实现“产品信息”跨两列，QHeaderView做不到，因为一个节只对应一列，跨列意味着需要节与节之间产生关联关系，而这个概念在QHeaderView里不存在。哪怕你狠心在headerData里返回"产品信息\n名称"这种带换行的字符串，也只是一格内画两行竖排文本，不会产生“产品信息合并两列、名称单独占一列”的效果。

1.2 复杂表头的本质是一棵树

真正做一次需求后你会发现：多行表头本质上就是一棵表头树。顶层节点是“产品信息”“销售地区”这种分组，底层叶子节点才是真正对应每一列数据的“名称”“价格”“华北”“华东”。有些复杂报表会有三层甚至四层，比如“时间”下面套“年份”，年份下面再套“季度”。

QHeaderView的模型接口是一维的，无法表达树。所以实现复杂表头只有两条路：要么把树“压平”到数据模型的前几行里，让表格数据区自己绘制合并单元格，这就是“假表头法”；要么在绘制QHeaderView时自己遍历树并计算每个分组的矩形区域，这就是“自绘表头法”。两条路我都用生产代码验证过，下面分别展开。

2. 最容易上手的“假表头法”：让数据模型的前两行充当合并表头

如果你要赶一个内部工具、数据量不大，而且层级固定不变，假表头法是投入产出比最高的。思路一句话：隐藏默认的水平表头，把表头行塞进QStandardItemModel的前两行，用QTableView::setSpan合并跨列单元格，数据从第三行开始放。

2.1 隐藏默认表头，用setSpan构造两级标题

先建一个四列的模型，第一行放一级分组，第二行放二级列名，第三行开始放真实数据：

QStandardItemModel* model = new QStandardItemModel(totalRows, 4, this); // 第一级表头 model->setItem(0, 0, new QStandardItem("产品信息")); model->setItem(0, 2, new QStandardItem("销售地区")); // 第二级表头 model->setItem(1, 0, new QStandardItem("名称")); model->setItem(1, 1, new QStandardItem("价格")); model->setItem(1, 2, new QStandardItem("华北")); model->setItem(1, 3, new QStandardItem("华东")); // 数据从第2行开始 for (int r = 2; r < totalRows; ++r) { for (int c = 0; c < 4; ++c) { model->setItem(r, c, new QStandardItem("")); } } ui->tableView->setModel(model); ui->tableView->horizontalHeader()->setVisible(false); ui->tableView->verticalHeader()->setVisible(false); // 合并第一行的一级分组 ui->tableView->setSpan(0, 0, 1, 2); // “产品信息”跨第0、1列 ui->tableView->setSpan(0, 2, 1, 2); // “销售地区”跨第2、3列

这里有几个必须注意的点：setSpan合并的是整个表格视图里的单元格区域，所以数据区的合并逻辑也会受影响。如果不想让数据区出现奇怪的跨列，尽量只在表头行使用setSpan。另外，模型里的每个位置都需要先setItem初始化，否则setSpan在部分样式下可能不生效，尤其当单元格为空指针时绘制会出问题。

2.2 冻结表头行：两个QTableView同步列宽

假表头法最大的坑是：表头行被塞进了数据模型，用户一滚动，表头就跟着数据跑了。做报表的人绝对接受不了这个。最常用的补救办法是拆成两个QTableView：上面一个只显示前两行表头，下面一个显示真实数据，两个视图共享同一个模型，互相用setRowHidden隐藏各自不需要的行。

// headerTableView 只显示前两行 for (int r = 2; r < model->rowCount(); ++r) { headerTableView->setRowHidden(r, true); } // dataTableView 隐藏前两行 headerTableView->setRowHidden(0, true); headerTableView->setRowHidden(1, true); // 同步列宽 connect(dataTableView->horizontalHeader(), &QHeaderView::sectionResized, headerTableView->horizontalHeader(), [=](int logical, int /*oldSize*/, int /*newSize*/) { headerTableView->horizontalHeader()->resizeSection(logical, dataTableView->horizontalHeader()->sectionSize(logical)); });

布局上，把headerTableView放在上边，高度固定为两行表头的高度；dataTableView放在下边，占据剩余空间。两个视图都隐藏垂直表头，这样视觉上就是一个完整的表格。

这个方案能跑通，但别高兴太早。共享模型会导致隐藏行状态和模型行列变化耦合严重。一旦你动态增删行，或者调用model->insertRow，两个视图的隐藏行状态很容易错乱，必须在增删后统一调用一个refreshHeaderHiddenRows()函数重新设置。排序功能也基本不能开，否则表头行会混进排序结果里。

2.3 假表头法的适用边界

我自己的经验是：这种方案适合列数固定、层级固定、交互简单的展示型报表。比如给管理层看的周报数据、后台配置表之类。如果表头层级经常变动，或者需要支持排序、行高可调、单元格合并，假表头法会在后期变成维护噩梦，那时就该考虑自绘方案了。

3. 进阶做法：继承QHeaderView重写绘制，把表头变成真正的“多行控件”

如果不想把表头塞进数据模型，那就反过来，让QHeaderView自己认识树结构。继承QHeaderView，重写paintEvent和sizeHint，在绘制时根据一棵“表头树”计算每个分组跨列后的矩形区域。这样表头是表头，数据模型是数据模型，互不污染。

3.1 先设计一个能描述多层分组的表头结构

绘制之前，先把表头定义成树。我通常用这么一个简单的结构体：

struct HeaderNode { QString title; int columnSpan = 1; // 横跨几列 QColor background; // 分组底色 QVector<HeaderNode> children; // 子节点 int firstColumn = 0; // 该节点覆盖的起始逻辑列 };

树构建完成后，递归给每个节点算出firstColumn和columnSpan。叶子节点的firstColumn对应真实的QHeaderView逻辑列索引，比如“产品信息”的firstColumn=0, columnSpan=2，“名称”的firstColumn=0, columnSpan=1，“价格”的firstColumn=1, columnSpan=1。后续绘制和点击映射都靠这套索引。

3.2 重写paintEvent，按层级画分组矩形

绘制逻辑的核心是：把每个表头节点的跨列范围换算成像素矩形。QHeaderView提供了两个好用的接口：sectionViewportPosition(int logicalIndex)返回某个逻辑列到视口左边的距离，sectionSize(int logicalIndex)返回该列宽度。于是“产品信息”跨两列的矩形范围就是：

int x1 = sectionViewportPosition(node.firstColumn); int x2 = sectionViewportPosition(node.firstColumn + node.columnSpan - 1) + sectionSize(node.firstColumn + node.columnSpan - 1); QRect nodeRect(x1, 0, x2 - x1, m_headerHeight / 2);

在paintEvent里递归遍历树，第一层节点画在表头区域的上半部分，第二层节点画在下半部分。如果有第三层，可以继续把高度三等分：

void MultiRowHeaderView::paintEvent(QPaintEvent* event) { QPainter painter(viewport()); painter.fillRect(rect(), palette().window()); for (const HeaderNode& node : m_topNodes) { paintNode(&painter, node, 0, 0); } // 最后画网格线 painter.setPen(palette().mid().color()); painter.drawLine(0, m_headerHeight - 1, width(), m_headerHeight - 1); }

实际工程里，我还会把绘制的矩形坐标缓存到QHash<const HeaderNode*, QRect>里。这样鼠标点击、tooltip、列宽变化后的局部重绘，都可以直接查缓存，不用每次递归算一遍。

3.3 表头高度、列宽变化、点击区域的处理

QHeaderView默认高度是单行的，必须重写sizeHint返回多行高度：

QSize MultiRowHeaderView::sizeHint() const { return QSize(QHeaderView::sizeHint().width(), m_headerHeight); }

并且要在构造或setHeaderTree时调用setFixedHeight(m_headerHeight)，否则视图不会给QHeaderView分配额外空间。

列宽变化后，跨列矩形位置会变，要统一刷新。最省事的方式是监听sectionResized信号后调用viewport()->update()。注意不要在每个section的resize事件里直接逐段更新，那样代码会写得非常乱，而且容易漏掉跨列节点。

点击区域也要自己算。默认QHeaderView会把点击事件按单个section识别，但我们想要的是一整块分组矩形。简单做法是重写mousePressEvent，遍历缓存的节点矩形，判断点击坐标落在哪个HeaderNode上，然后发出自定义信号。这样排序、过滤、弹出菜单都可以绑定到分组节点，而不是底层列。

3.4 和排序、筛选、代理模型配合时注意列映射

一旦用了QSortFilterProxyModel，QHeaderView里的逻辑列索引是代理模型列的索引，而不是源模型列的索引。所以表头树必须建立在代理模型列上，或者在setModel后重建树结构。否则排序会导致表头分组和高亮列错位。

我遇到过最典型的场景：用户点击“价格”列排序，QHeaderView里会自动高亮当前section，但因为表头树是按源模型列建的，高亮线画到了别的列上。解决方法是把表头树的构建和model->columnCount解耦，新增一个rebuildFromModel()函数，在setModel后调用。

4. 最容易翻车的四个地方：真实踩坑记录

代码写完只是开始，真正让我掉头发的是下面这四个问题。每一个都是从实际项目里抠出来的，放这里当预警。

4.1 假表头法里setSpan和列宽自动调整冲突

用假表头法的时候，我习惯双击列头边框来快速调整列宽，结果发现setSpan合并过的区域，双击往往无法正确触达每个子列。原因是QTableView的resizeColumnToContents默认只取第一行内容宽度，而第一行是“产品信息”这种合并单元格，宽度计算被带偏。

解决方案很直接：关闭表头自动调整，或者单独给每个子列的宽度写死。如果实在需要自适应，就自己遍历数据区，根据实际内容的最大宽度去resizeColumnToContents，但一定要把第二行的列名宽度也算进去，避免“名称”文字比数据宽导致显示不全。

4.2 排序功能把表头行和真实数据搅在一起

假表头法里，如果你直接调用tableView->setSortingEnabled(true)，模型的前两行表头也会参与排序。数据一乱，表头行被排到中间，整个表格直接报废。

我建议的方式是：不用QTableView自带的排序，改为QSortFilterProxyModel，并且重写lessThan，先判断行号是否小于表头行数，如果是就直接返回原顺序；这样表头永远固定在顶部。如果你连这个都嫌麻烦，那就直接关闭排序，在表头点击时发出信号，自己控制数据模型排序。

4.3 自绘QHeaderView没考虑高分屏缩放的DPI问题

自绘方案踩过最隐蔽的坑是DPI缩放。在1080p屏幕下一切正常，换成2K屏，表格表头的文字位置全乱，分组矩形和文字严重错位。问题根源是绘制时用了旧式QFontMetrics，而整个程序没有开启高DPI缩放，或者在main函数里调用QApplication::setAttribute(Qt::AA_EnableHighDpiScaling)的时机不对。

配置好高DPI之后，代码里所有坐标和尺寸都要使用真实的设备像素，而不是逻辑像素。简单做法是绘制时统一走QPainter并依赖QPainter的坐标系统，不要自己用devicePixelRatio手动乘除法，否则容易出重复缩放的bug。

4.4 列拖拽导致自绘表头的视觉错乱

QHeaderView默认允许通过拖动整列来调整列顺序。但自绘表头里，分组矩形是基于逻辑列索引计算的，拖拽改变的是视觉列位置，两者一旦错位，表头分组框和下方数据列就对不上了。

如果你不需要调整列顺序，直接headerView->setSectionsMovable(false)最省事。如果业务上确实要允许用户移动列，就必须在sectionMoved信号里重新计算表头树的firstColumn，并在重绘前刷新所有缓存矩形。我在一个项目里因为这个问题来回改了三版，最后结论是：复杂表头场景下尽量关闭列移动，成本收益比太低。

5. 最终选型建议与一个可复用的表头数据结构

两个方案都聊完了，说一下我现在的选型标准。假表头法适合快速交付、表头层级固定、不需要复杂交互的情况；自绘QHeaderView适合长期维护、列数多、层级经常调整的情况。如果项目预算允许，也可以看第三方控件，但第三方引入的集成成本和学习成本并不低，必须衡量清楚。

5.1 假表头法与自绘法对比

从我的实践看，如果这个表格只是报表展示，不参与编辑，假表头法完全够用。如果未来半年内大概率会加第三级表头、行选择联动、跨列编辑这类需求，那就别犹豫，直接自绘。

5.2 用JSON定义表头树，让代码只处理树不写死列

为了对付“业务方今天加一列、明天改个分组”这种需求，我后期把所有表头都做成了配置驱动。前端写一个嵌套JSON，运行时解析成上面的HeaderNode树，绘制层和事件层只管树结构，完全不用改代码：

[ { "title": "产品信息", "children": [ { "title": "名称", "columnIndex": 0 }, { "title": "价格", "columnIndex": 1 } ] }, { "title": "销售地区", "children": [ { "title": "华北", "columnIndex": 2 }, { "title": "华东", "columnIndex": 3 } ] } ]

解析函数很直白：递归遍历JSON，给每个节点的子节点分配columnIndex，最后把相同级别的节点放在同一行。这样加一列，只需要在配置里加一个子节点，代码基本不动。

5.3 个人经验总结

最后分享一个设计习惯：无论选哪种方案，尽量把表头结构做成独立类或独立配置，不要散落在tableView初始化代码里。我在实际项目里把表头树和样式表绑定后，多级表头需求基本都能稳定交付。而我自己现在优先选自绘方案，因为假表头法虽然前期省事，但后期维护时，每一处关于“表头行被排序”“滚动后表头消失”的bug修复，都在消耗那点省下来的时间。说到底，复杂表头不是一个画字问题，而是一个数据结构问题。先把树建好，绘制只是顺手的事。

本文还有配套的精品资源，点击获取