报表这个东西凡是做过管理系统的都绕不开。我上一次接到的需求是给一套内部数据汇总程序加一个报表模块屏幕上看要能排序、筛选、高亮异常行打印出来要带页眉页脚和页码还要能一键导出 PDF 和表格文件给业务侧归档。最开始图省事直接拿 QTableWidget 堆两百来行数据的时候一切正常等真实数据灌到几万行、列数涨到三十多列、还要求跨页打印保持表头的时候卡顿、错位、打印断页全来了。后来推倒重做走的是 Qt 原生 Model/View 那套 MVC 架构自己写模型、自己写委托、自己算分页才把这套 QT 自定义报表控件开发从屏幕渲染到打印导出的完整链路跑通。这篇就把整个过程拆开讲为什么不用现成控件、模型层怎么写才不卡、表头合并和冻结列怎么处理、打印时毫米和像素怎么换算、分页算法怎么推、导出 PDF 和表格文件各自踩了什么坑。适合已经会用 Qt 画界面、但一碰到大数据量表格和打印就发怵的开发者也适合正在评估报表方案的技术负责人代码片段基本可以直接抄去改。1. 需求拆解与技术路线选型1.1 报表控件真正要解决的四个问题很多人一提报表控件脑子里第一反应是一个能显示表格的控件。这个理解偏差会把后面的设计带歪。实际项目里一个能用的报表控件至少要同时扛住四件事而且这四件事的技术诉求是互相冲突的。第一是数据规模。屏幕上的表格动辄几千上万行用户还要滚动、排序、筛选。如果每一行都对应一个真实的控件对象光是对象创建和布局计算就能把主线程吃满。第二是表现力。报表不是纯文本表格它有合并单元格、有多级表头、有按阈值变色的数值、有千分位和百分比格式化、有合计行加粗。第三是输出一致性。屏幕上看到的列宽比例、对齐方式、颜色标记打印到纸上或者导出成文件之后必须还在不能屏幕是一套、纸上是另一套。第四是可扩展。今天要 A4 纵向明天要 A3 横向后天要按部门分组小计这些变化不应该每次都要动核心渲染代码。把这四点摆在一起看就能明白为什么现成控件撑不住。QTableWidget 本质是用控件堆出来的表格它把数据和视图焊死在一起天生不适合大数据量而 QTableView 加自定义模型是数据与视图分离把复杂度转移到了模型层视图只负责取它当前可见的那几十行。这个分离是整套方案的地基后面所有的性能优化和打印复用都是从这儿长出来的。我在做技术选型的时候画过一张对照表把当时考虑过的四条路线摆在一起比了一遍最后选了第二条。这个对比过程值得展开说因为很多人卡在选型上选完了才发现方向错了返工成本极高。1.2 四条技术路线的横向对比路线实现方式优点致命短板适用场景控件堆叠QTableWidget 逐格 setItem上手最快 demo 半小时能出万行级必卡样式与数据耦合行数固定在百级以内的小工具模型视图QAbstractTableModel QTableView 自定义委托大数据量流畅屏幕与打印可共用同一份数据源需要自己实现排序、合并、分页绝大多数业务报表图元自绘QGraphicsView QGraphicsScene 全手绘排版自由度最高复杂图表混排友好交互逻辑选中、编辑、键盘导航全部自己写以图形为主、表格为辅的看板网页渲染内嵌网页组件渲染 HTML 表格前端生态成熟样式容易做得漂亮与原生程序的数据交互成本高打印控制权不在自己手里已有前端报表体系、只做展示这张表里最关键的一行判断是打印控制权。第三条和第四条路线在屏幕上都能做得很好看但一旦要求打印时表头每页重复、页码居中、页脚带导出时间控制权就必须在自己手里。图元自绘可以但要额外写一套打印渲染器网页渲染基本没戏只能依赖对方提供的打印接口参数调不动。所以最终方案是QAbstractTableModel 承载数据QTableView 负责屏幕呈现QStyledItemDelegate 负责单元格外观QPrinter QPainter 负责打印导出复用打印的绘制逻辑。这套组合的好处是打印和屏幕走同一份模型数据格式化的逻辑只写一次两边自动一致。注意不要为了打印好看而在视图层做额外的样式处理。样式一旦写进视图打印时就得再写一遍两边迟早会漂移。所有格式化统一收敛到模型的 Qt::DisplayRole 里视图和打印都只消费结果。1.3 分层结构与模块边界定了路线之后我把整个控件拆成五层每一层只依赖它下面那一层不允许跨层调用。这个约束听起来教条但在报表这种需求天天变的场景里它能救命。数据层是纯业务结构体一个 Row 就是一组单元格值加一个状态标记正常、预警、异常不继承任何 Qt 类不掺任何界面逻辑。这一层的好处是单元测试好写业务侧改字段不影响界面。模型层继承 QAbstractTableModel负责把 Row 数组翻译成 Qt 认识的角色数据。它是唯一知道第几列叫什么、用什么格式、怎么对齐的地方。视图层是 QTableView 加几个自定义表头组件只做三件事显示、滚动、把用户的排序筛选请求转发出去。委托层继承 QStyledItemDelegate处理那些模型表达不了的视觉效果比如进度条单元格、状态圆点、合并单元格的边框。输出层是打印和导出它不碰视图直接从模型取数据自己算页面坐标。这一层是整套设计里最费劲的部分也是最能体现功力差距的地方。分层之后有个直接好处需求变更时能迅速定位到该改哪一层。要加一列改数据结构和模型的列定义要改颜色规则改模型的 BackgroundRole要改打印页边距只动输出层的一个常量。我在项目中期经历过一次所有数值列改成右对齐、小数点统一两位的调整因为格式化的定义都集中在列定义结构体里改了一个循环就完事了没有满世界找 setAlignment。2. 模型层的设计细节与性能红线2.1 三个必须实现的虚函数与两个容易漏的QAbstractTableModel 是个抽象类不实现纯虚函数编译都过不去。真正需要动脑子的是 rowCount、columnCount、data 这三个以及两个经常被忘掉但会引发诡异问题的headerData 和 flags。class ReportModel : public QAbstractTableModel { Q_OBJECT public: enum Roles { RawValueRole Qt::UserRole 1, RowStateRole, SpanRole }; int rowCount(const QModelIndex parent QModelIndex()) const override { return parent.isValid() ? 0 : m_rows.size(); } int columnCount(const QModelIndex parent QModelIndex()) const override { return parent.isValid() ? 0 : m_columns.size(); } QVariant data(const QModelIndex idx, int role) const override; QVariant headerData(int section, Qt::Orientation o, int role) const override; Qt::ItemFlags flags(const QModelIndex idx) const override { if (!idx.isValid()) return Qt::NoItemFlags; return Qt::ItemIsEnabled | Qt::ItemIsSelectable; } };parent.isValid()那个判断千万别省。表格模型是扁平结构只要 parent 有效就说明有人把你当树模型在用此时必须返回 0否则会触发无限递归或者越界崩溃。我见过一个 bug 排查了大半天最后发现是有人套了两层代理模型外层把内层当树查询而内层没做这个判断直接数组越界。flags返回里如果没有 Qt::ItemIsEnabled单元格会显示成灰色点击没反应。如果返回了 Qt::ItemIsEditable 却没实现 setData用户双击进入编辑态后改完一回车数据就消失体验极差。报表控件一般是只读的老老实实给 Enabled 加 Selectable 就够了别手贱加 Editable。headerData处理的是行号和列标题。有个细节竖直表头行号默认显示 1、2、3 这种序号如果业务上需要显示第 N 行或者干脆隐藏都在这里控制。返回空 QVariant 表示没有表头文字但那一列的位置依然占着想要彻底移除得调verticalHeader()-setVisible(false)。2.2 用角色承载对齐、颜色与原始值data()是整个模型里调用最频繁的函数视图每刷新一次就会对每个可见单元格调好几个角色。它的实现质量直接决定滚动流畅度。QVariant ReportModel::data(const QModelIndex idx, int role) const { if (!idx.isValid() || idx.row() m_rows.size()) return {}; const Row row m_rows.at(idx.row()); const ColumnDef col m_columns.at(idx.column()); switch (role) { case Qt::DisplayRole: { const QVariant raw row.cells.value(idx.column()); return col.formatter ? col.formatter(raw) : raw; } case Qt::TextAlignmentRole: return int(col.align | Qt::AlignVCenter); case Qt::BackgroundRole: return row.state RowState::Error ? QBrush(QColor(255, 235, 235)) : row.state RowState::Warn ? QBrush(QColor(255, 248, 220)) : QVariant(); case Qt::ForegroundRole: return row.state RowState::Error ? QBrush(QColor(180, 30, 30)) : QVariant(); case RawValueRole: return row.cells.value(idx.column()); default: return {}; } }这里有几个必须讲清楚的点。第一DisplayRole返回的是格式化之后的字符串而RawValueRole返回原始值。为什么要留原始值因为排序和导出都要用。视图上显示1,234.50如果排序时拿这个字符串比会得到 999.00 1,234.50 这种荒谬结果。导出到文件时也一样业务侧要的是数字不是带千分位的文本。第二TextAlignmentRole必须返回 int 类型返回 Qt::Alignment 枚举在某些 Qt 版本上会被当成不认识的类型导致对齐失效。这个坑很隐蔽因为代码能编译、运行不报错就是对齐不对你会以为是样式表覆盖了。第三BackgroundRole返回 QVariant 而不是 QBrush 的空构造。返回一个默认构造的 QBrush画刷样式为 NoBrush和返回空 QVariant 在多数情况下效果一样但在某些平台上默认 QBrush 会被画成黑色非常难看。养成返回 QVariant() 的习惯。格式化函数我建议做成函数指针存在 ColumnDef 里而不是在 data() 里写一长串 if-else 判断列索引。前者加列时零成本后者每加一列就要动一次核心函数早晚出事。2.3 多级表头与单元格合并的实现取舍这两个需求几乎每个报表都会提而 Qt 原生一个都不支持。QHeaderView 只能显示一层标题QTableView::setSpan 能做合并但是静态的数据变了得手动重算。我试过三种方案最后是组合着用的。多级表头的第一种做法是自绘表头。继承 QHeaderView重写paintSection在 paint 里根据当前 section 的位置自己算层级矩形、画文字、画分隔线。这方案灵活度最高能做出任意层级的树状表头代价是要自己处理列宽变化、滚动偏移、点击命中的区域映射。我实际写下来大概两百多行难点在坐标换算sectionViewportPosition(section)给出的是相对于视口的位置画的时候要减去滚动量。第二种做法是把表头当成模型的第一行。在 data() 里判断 row() 0 时返回表头文字然后用 setSpan 把跨列的格子合并起来。这个方案实现快缺点是表头会跟着内容一起滚动需要额外固定住而且选中、复制这些交互要专门排除第一行逻辑上很脏。第三种是用一个独立的小 QTableView 只显示一行放在主表格正上方两个视图共享同一个横向滚动条和列宽。这个方案在项目里最常见因为实现简单、视觉效果好、维护成本低。我的做法是主表格的horizontalHeader()直接隐藏上面放一个高度固定的 QTableView列宽变化时用sectionResized信号同步过去。单元格合并用setSpan就够但必须记住一点span 信息不属于模型属于视图。数据重置之后 span 会全部丢失必须在modelReset或者数据刷新完成后重新计算一遍。我的一般做法是写一个rebuildSpans()函数遍历数据找出需要合并的连续区间先把旧的 clearSpans再逐个 setSpan。注意 setSpan 的顺序有讲究先设置跨列大的再设置小的或者干脆不重叠否则会出现合并区域互相覆盖、边缘绘制错乱。2.4 万行数据下的响应速度怎么保住性能这块我踩过的坑比写过的代码还多。总结下来就三条红线破了任何一条滚动就开始掉帧。第一条data() 里不许做重活。不要在这里查数据库、不要做字符串拼接循环、不要调用会分配大量内存的格式化函数。我见过有人在 data() 里对每个单元格调一次正则替换五万行三十列滚一下卡三秒。正确的做法是把格式化结果在数据装载时算好缓存起来data() 只做取值。第二条批量更新必须用 beginResetModel/endResetModel不要逐行 insertRows。逐行插入意味着每插一行都要发一次 rowsInserted 信号视图要重新布局一次。两千行就是两千次布局肉眼可见地卡。void ReportModel::setRows(QVectorRow rows) { beginResetModel(); m_rows std::move(rows); endResetModel(); }第三条行高列宽固定别开自动适应。resizeRowsToContents()和resizeColumnsToContents()会遍历所有行所有列计算理想尺寸十万个单元格算下来就是几秒钟。我一般在数据装载完成后只算一次把结果缓存进 QHeaderView之后切到 Fixed 模式。view-horizontalHeader()-setSectionResizeMode(QHeaderView::Fixed); view-verticalHeader()-setSectionResizeMode(QHeaderView::Fixed); view-verticalHeader()-setDefaultSectionSize(28); view-setWordWrap(false);setWordWrap(false)这一行容易被忽略但对性能影响很大。开着自动换行的时候视图要计算每个单元格的文字折行位置这个计算量跟文本长度成正比。报表通常列宽固定、文字截断加省略号就够了关掉换行能省下不少开销。排序这块还有个坑。用 QSortFilterProxyModel 直接代理默认走的是 DisplayRole 的字符串比较数字列会排错。解决办法是继承代理模型重写 lessThan用原始值比。bool NumberAwareProxyModel::lessThan(const QModelIndex l, const QModelIndex r) const { const QVariant lv l.data(RawValueRole); const QVariant rv r.data(RawValueRole); if (lv.isValid() rv.isValid() lv.userType() QMetaType::Double rv.userType() QMetaType::Double) return lv.toDouble() rv.toDouble(); return QSortFilterProxyModel::lessThan(l, r); }这里用userType()而不是老的type()因为后者在新版本里已经标记弃用编译会报警告。这种小细节迁移的时候特别烦建议一开始就写新接口。3. 视图与委托让表格长成报表的样子3.1 委托里做单元格渲染的边界在哪QStyledItemDelegate 能做的事情很多但我给自己定了个规矩委托只处理模型表达不了的视觉不处理数据逻辑。什么算表达不了进度条、状态圆点、带箭头的涨跌标识、合并单元格的内边框、单元格内的多行文本这些都需要拿到 QPainter 自己画模型给不了。而数字格式化、单位换算、颜色阈值判断这些都属于数据逻辑必须放模型。委托的核心是两个函数paint和sizeHint。void ReportDelegate::paint(QPainter *p, const QStyleOptionViewItem opt, const QModelIndex idx) const { QStyleOptionViewItem o(opt); initStyleOption(o, idx); const QVariant raw idx.data(RawValueRole); if (idx.data(CellTypeRole).toInt() CellType::Progress raw.isValid()) { p-save(); const QRect r o.rect.adjusted(4, 6, -4, -6); p-setRenderHint(QPainter::Antialiasing, true); // 底槽 p-setPen(Qt::NoPen); p-setBrush(QColor(0, 0, 0, 18)); p-drawRoundedRect(r, 3, 3); // 进度 const double ratio qBound(0.0, raw.toDouble(), 1.0); QRect fill r; fill.setWidth(int(r.width() * ratio)); p-setBrush(ratio 0.9 ? QColor(200, 60, 60) : QColor(52, 152, 219)); p-drawRoundedRect(fill, 3, 3); // 百分比文字 p-setPen(QColor(60, 60, 60)); p-drawText(o.rect, Qt::AlignCenter, QString::number(ratio * 100, f, 0) %); p-restore(); return; } QStyledItemDelegate::paint(p, o, idx); }这段代码里最容易被低估的是initStyleOption。它会从模型把文字、对齐、颜色、字体全部填充到 QStyleOptionViewItem 里省去你手动取的麻烦。忘了调它你会发现自绘的部分正常、默认绘制的那部分全都变成空白。p-save()和p-restore()成对出现是硬要求。曾经有一次我漏了 restore结果后面所有单元格的文字颜色全变成了红色排查了半天才想起来是画笔状态没还原。还有一个性能注意点setRenderHint(QPainter::Antialiasing)只对当前这次绘制有效每次 paint 都要重新设。但如果整张表都是进度条每次都开抗锯齿会有开销可以改成只在圆角矩形这个分支里开。sizeHint相对简单但对性能也有影响。如果所有行都返回同一个高度可以在视图层直接用setDefaultSectionSize固定让委托的 sizeHint 根本不被调用速度更快。3.2 冻结列与自适应列宽的实操冻结列是报表的高频需求尤其是第一列是编号或者名称的时候横向滚动过去就看不见了用户会骂人。新一些的 Qt 版本里 QTableView 提供了setFrozenColumnCount一行代码搞定。但如果项目用的版本比较老就得自己搭。我用的是双视图方案左右各一个 QTableView左边只显示前 N 列右边显示剩下的两个视图共享同一个模型左边关闭横向滚动条和竖直表头右边同步竖直滚动条。void syncScrollBars() { // 竖直滚动条双向同步 connect(m_left-verticalScrollBar(), QScrollBar::valueChanged, m_right-verticalScrollBar(), QScrollBar::setValue); connect(m_right-verticalScrollBar(), QScrollBar::valueChanged, m_left-verticalScrollBar(), QScrollBar::setValue); // 选中行同步 connect(m_left-selectionModel(), QItemSelectionModel::selectionChanged, this, [this] { m_right-selectionModel()-select( m_left-selectionModel()-selection(), QItemSelectionModel::ClearAndSelect | QItemSelectionModel::Rows); }); }双视图方案的坑在于左右两边的行高必须完全一致否则滚动到后面会错位。解决办法是给两边都设成 Fixed 模式并且用同一个 defaultSectionSize。另外左边视图的horizontalScrollBar()-setVisible(false)之后它的宽度会变化导致右边视图的布局跟着动需要在 resize 事件里重新调整两边的宽度比例。自适应列宽是另一块。用户拖拽列宽、双击分隔线自动适应、窗口 resize 时按比例分配这三件事要协调好否则会打架。我最终采用的是权重分配算法每个列定义里带一个权重值窗口宽度变化时按权重分。void distributeColumnWidths(QHeaderView *header, int totalWidth) { const int n header-count(); if (n 0) return; double sum 0; QVectordouble weights(n); for (int c 0; c n; c) { weights[c] columnWeight(c); // 每列预设权重最小 0.5 sum weights[c]; } int used 0; for (int c 0; c n - 1; c) { const int w qMax(50, int(totalWidth * weights[c] / sum)); header-resizeSection(c, w); used w; } // 最后一列吃掉所有舍入误差保证总宽精确等于可用宽度 header-resizeSection(n - 1, qMax(50, totalWidth - used)); }那个最后一列吃掉舍入误差的处理非常关键。整数除法的累积误差在列数多的时候能有十几个像素表现出来就是表格右边永远有一道白缝或者横向滚动条始终处于激活状态用户滚动一下发现右边还有些空白体验很怪。另外qMax(50, ...)这个下限也得有。窗口缩得很小的时候按权重算出来的宽度可能是负数直接传给 resizeSection 会有警告甚至崩溃。3.3 屏幕与打印的一致性怎么保证这是整套方案里我最看重的一点。很多报表做完之后的毛病是屏幕上一套配色、打印出来另一套屏幕上有斑马纹打印出来全白屏幕上列宽是 3:2:5打印出来挤成一坨。根因是渲染路径分裂了。屏幕走视图和委托打印走另一套手写逻辑两边各写各的格式化不一致是必然的。我的做法是抽出一个纯函数式的绘制单元输入是模型指针、列定义、当前矩形输出是画在 QPainter 上的内容。屏幕渲染时委托调用它打印时打印循环调用它。void ReportPainter::drawCell(QPainter *p, const QRect rect, const ReportModel *model, int row, int col, bool forPrint) const { const QModelIndex idx model-index(row, col); const QString text idx.data(Qt::DisplayRole).toString(); const int align idx.data(Qt::TextAlignmentRole).toInt(); // 斑马纹只在屏幕上画打印为了省墨不画 if (!forPrint row % 2 1) { p-fillRect(rect, QColor(248, 249, 251)); } // 背景色异常行高亮屏幕和打印都要 const QVariant bg idx.data(Qt::BackgroundRole); if (bg.isValid()) p-fillRect(rect, bg.valueQBrush()); // 文字 p-setPen(idx.data(Qt::ForegroundRole).valueQBrush().color()); p-drawText(rect.adjusted(6, 0, -6, 0), align | Qt::TextSingleLine, text); // 边框屏幕用浅灰打印用深灰否则打印机上浅灰会消失 p-setPen(forPrint ? QColor(150, 150, 150) : QColor(230, 230, 230)); p-drawLine(rect.bottomLeft(), rect.bottomRight()); }forPrint这个开关是我后来加的一开始想完全复用实际打印出来发现两个问题一是斑马纹的浅灰在激光打印机上根本印不出来白白浪费碳粉二是屏幕上的分隔线颜色230,230,230太浅纸上完全看不见表格结构散了。所以保留一个开关只在配色这个维度上分叉布局和文字内容严格共用。这个开关的粒度要控制好。如果分叉太多又回到了两套逻辑的老路。我的原则是凡是跟墨、纸、色彩还原相关的允许分叉凡是跟数据、格式、对齐、列宽相关的绝不允许分叉。4. 打印与导出的完整链路4.1 坐标系统换算毫米、像素与缩放打印这块第一道坎就是单位。业务方给的要求是A4 纵向上下左右边距各 15 毫米表格内容区宽度占满而 QPainter 默认工作在设备坐标系里单位是像素且这个像素是打印机的物理像素。A4 是 210 × 297 毫米如果按 1200 DPI 计算一毫米对应 1200 / 25.4 ≈ 47.24 像素整页就是 9921 × 14031 像素。所有尺寸都拿这个数量级去算代码里全是六位数改一个边距要重新算一遍根本没法维护。我的做法是在 QPainter 上套一层缩放把逻辑坐标重新定义成0.1 毫米一个单位。QPrinter printer(QPrinter::HighResolution); printer.setPageSize(QPageSize(QPageSize::A4)); printer.setPageOrientation(QPageLayout::Portrait); printer.setPageMargins(QMarginsF(15, 15, 15, 15), QPageLayout::Millimeter); printer.setColorMode(QPrinter::GrayScale); QPainter painter; if (!painter.begin(printer)) { qWarning() 打印机不可用; return; } // 逻辑坐标1 单位 0.1 毫米 constexpr double kUnitsPerMm 10.0; const double sx printer.logicalDpiX() / (25.4 * kUnitsPerMm); const double sy printer.logicalDpiY() / (25.4 * kUnitsPerMm); painter.scale(sx, sy);换完之后整个坐标系变得非常直观页面宽度 2100 单位高度 2970 单位页边距 150 单位可用内容宽度 1800 单位行高 60 单位就是 6 毫米。所有常量都是三位数肉眼看就能判断合不合理。这里有个细节要注意logicalDpiX()和logicalDpiY()在绝大多数打印机上是相等的但保险起见还是分开算。曾经遇到过一台老式打印机横向和纵向 DPI 不一致如果用一个值算打印出来整个表格会被拉伸行高看着没问题但宽度不对非常难查。还有一个坑是QPrinter::HighResolution和QPrinter::ScreenResolution的选择。HighResolution 会给出打印机的真实分辨率通常是 600 或 1200ScreenResolution 会给出屏幕的 96 左右。用 ScreenResolution 打印出来的文字会有明显的锯齿因为它把 96 DPI 的位图放大到了 1200 DPI 的纸上。除非是为了出草稿看排版否则一律用 HighResolution。4.2 分页算法逐行推演分页是整套打印逻辑的核心也是最容易出错的地方。核心思路其实简单从上往下逐行累加高度加不下了就换页。但细节上一堆坑。先明确几个常量。页面高度 2970 单位297 毫米上下边距各 150可用高度 2670。其中表头占 80页脚占 70那么正文可用高度是 2670 - 80 - 70 2520 单位。行高固定 60那么每页最多能放 2520 / 60 42 行。但实际不能写死 42。因为有的行会因为内容多而变高有的报表要插入小计行高度不固定。所以还是得逐行累加。struct PageLayout { int startRow; int endRow; int usedHeight; }; QVectorPageLayout paginate(const ReportModel *model, int contentHeight) { QVectorPageLayout pages; const int rows model-rowCount(); if (rows 0) return pages; int start 0; int used 0; for (int r 0; r rows; r) { const int h rowHeight(model, r); // 单行高度含小计行加高 // 关键如果这一行单独就超过一页必须强制放下否则死循环 if (h contentHeight) { if (used 0) { pages.append({start, r - 1, used}); start r; used 0; } pages.append({r, r, h}); start r 1; used 0; continue; } if (used h contentHeight) { pages.append({start, r - 1, used}); start r; used 0; } used h; } if (used 0) pages.append({start, rows - 1, used}); return pages; }这段代码里最容易被忽略的是那个h contentHeight的分支。如果某一行比如一个带了大量备注文字的合并行自身高度就超过了正文区高度不加这个判断的话used h contentHeight永远成立每次都会开新页但一行都没放进去最后无限循环程序直接假死。我在测试阶段用一条两米长的备注文字把这个 bug 触发过主线程卡死只能强杀。另一个细节是页尾的孤行控制。如果某页的最后一行恰好是一个分组的第一行而它的兄弟行都在下一页打印出来会很别扭。业务上要求不高的话可以不管要求高的话得在分页之后做一次回扫检查每页末尾行是否属于一个跨页的分组如果是把整个分组挪到下一页。这个逻辑我实现过大概是分页之后再做一轮调整复杂度不低项目里最终没上因为业务侧说能看就行。分页算完之后绘制循环就清晰了int pageNo 0; for (const PageLayout page : pages) { if (pageNo 0) printer.newPage(); pageNo; drawPageHeader(painter, pageNo, pages.size()); int y pageTopMargin headerHeight; for (int r page.startRow; r page.endRow; r) { int x pageLeftMargin; for (int c 0; c model-columnCount(); c) { const int w columnWidth(c); drawCell(painter, QRect(x, y, w, rowHeight(model, r)), model, r, c, true); x w; } y rowHeight(model, r); } drawPageFooter(painter, pageNo); }列宽的分配跟屏幕上用的是同一个权重算法只是总宽度换成了纸面可用宽度 1800 单位。这样屏幕上看到的比例关系和纸上完全一致。我在前面 3.2 节写的那段distributeColumnWidths稍微改一下就能直接复用把 QHeaderView 换成纯数组计算。4.3 页眉页脚与页码的绘制时机页眉页脚看着简单实际有两个坑。第一个是绘制时机。新手常见的写法是先把所有内容画完再统一回去画页脚。这个在 PDF 输出上可能没问题但在真实打印机上一旦调用newPage()上一页的内容就已经被 flush 到设备了你再也回不去了。所以页脚必须在当前页绘制结束前画完。第二个是内容溢出覆盖。如果正文区的高度算错了最后一行压到了页脚区域页脚文字会跟表格内容叠在一起糊成一团。我的处理办法是给页眉页脚各留出固定的高度预算正文区的高度严格等于总高度减去这两块从算法层面杜绝重叠。绘制顺序就是上面代码里的页眉 → 正文 → 页脚都在同一页的生命周期内完成。void drawPageHeader(QPainter *p, const QString title, const QString subtitle, int pageWidth) { QFont f p-font(); f.setPointSizeF(11); f.setBold(true); p-setFont(f); p-drawText(QRect(0, 40, pageWidth, 60), Qt::AlignHCenter | Qt::AlignVCenter, title); f.setPointSizeF(8); f.setBold(false); p-setFont(f); p-setPen(QColor(110, 110, 110)); p-drawText(QRect(0, 100, pageWidth, 40), Qt::AlignHCenter | Qt::AlignVCenter, subtitle); }字体这块要特别注意中文。QPainter 默认字体在不同系统上差异很大打印中文可能出现方框或者缺字。稳妥的做法是显式指定一个确定存在的字体族并且在导出 PDF 时确认字体被嵌入。设置f.setFamily()之后建议再调一次QFontInfo(f).family()检查实际匹配到的字体如果匹配失败了会返回一个后备字体名能提前发现。页码的格式也有讲究。第 N 页 / 共 M 页这种格式需要先知道总页数所以必须先把分页算完再开始绘制不能边画边数。这也是为什么我把 paginate 单独拆成一个函数先算出完整的页数组再去绘制。4.4 PDF、CSV 与电子表格的导出差异导出这块不同格式的坑完全不一样分开说。PDF最简单因为 QPrinter 直接设置输出格式就行。printer.setOutputFormat(QPrinter::PdfFormat); printer.setOutputFileName(filePath);打印的整套逻辑一行不用改。唯一的注意事项是中文案例里提到的字体嵌入。Qt 在生成 PDF 时默认会嵌入字体子集但如果你指定了一个系统上不存在的字体它会回退到默认字体而默认字体在某些环境下不带中文字形导出来就是一片空白。我遇到过一次屏幕预览正常导出的 PDF 打开全是空白查了半天是字体回退导致的。CSV表面简单实际全是陷阱。第一是编码直接用 UTF-8 写文件用办公软件打开会乱码必须加 BOM 头。第二是分隔符逗号在数值的千分位表示里会出现如果导出的是格式化后的1,234.50用逗号分隔就会把一列拆成两列。所以导出 CSV 时一律用原始值不用 DisplayRole。QFile f(filePath); if (!f.open(QIODevice::WriteOnly | QIODevice::Text)) return; // UTF-8 BOM缺了这仨字节办公软件打开就是乱码 f.write(\xEF\xBB\xBF); QTextStream out(f); out.setCodec(UTF-8); for (int c 0; c model-columnCount(); c) { if (c) out ,; out escapeCsv(model-headerData(c, Qt::Horizontal).toString()); } out \n; for (int r 0; r model-rowCount(); r) { for (int c 0; c model-columnCount(); c) { if (c) out ,; const QVariant raw model-index(r, c).data(RawValueRole); out escapeCsv(raw.toString()); } out \n; }escapeCsv要做的是如果字段里包含逗号、双引号或者换行就把整个字段用双引号包起来并把内部的双引号翻倍。这个规则看着简单漏了就会导致表格错列而且错得很隐蔽——打开文件看着还行往下翻几行数据全错位了。电子表格文件xlsx麻烦在于没有官方库。两条路一是通过 COM 自动化调用本机装好的办公软件好处是格式支持全坏处是依赖本机环境、速度慢、进程容易残留二是引第三方库直接写文件好处是快、无依赖坏处是要多引一个依赖且 API 风格跟 Qt 差别大。我选的是后者。用的时候注意两点一是数字单元格要写数值类型而不是字符串否则导出的文件里单元格左上角带个绿三角用户想求和的时候发现公式不起作用二是大文件导出要考虑内存几万行一次性构建对象树会吃掉几百兆得考虑分批写或者用流式 API。5. 踩过的坑与排查速查表5.1 五类高频问题的定位思路类型一滚动卡顿。定位方法很直接在 data() 里加一个静态计数器滚一次看它被调了多少次。正常情况下滚动一屏应该是可见行数乘列数乘角色数比如 40 × 15 × 4 2400 次左右。如果这个数上了十万说明发生了什么让视图反复全量刷新的事情最常见的是在 data() 里调了会触发 modelReset 的操作或者 selectionModel 的信号处理里做了重活。类型二打印内容错位。表现是列宽跟屏幕对不上、行高不一致、最后一页多出空白页。先查两件事一是屏幕的 distributeColumnWidths 和打印的列宽计算是不是用了同一套权重二是分页函数返回的页数组里有没有used 0的空页。多出空白页十有八九是分页循环最后多 append 了一次。类型三导出文件打不开或者内容乱码。CSV 先查 BOMxlsx 先查文件是否完整写入没 close 就返回了。PDF 查字体是否嵌入最简单的验证方法是用阅读器打开看文档属性里的字体列表如果显示的是未嵌入就要改字体设置。类型四表头与内容错位。这个几乎只出现在冻结列的双视图方案里。检查两点两边视图的 defaultSectionSize 是否一致、两边的 horizontalHeader 高度是否一致。表头高度不一致的话第一行的垂直位置就差了几个像素滚动到后面累积起来就很明显。类型五程序退出时报错或者卡住。报表模块涉及大量 QObject 连接视图、模型、代理、委托之间的生命周期关系要理清。我的处理原则是模型的父对象设成主窗口视图和委托的父对象也设成主窗口三者的析构顺序由 Qt 的父子关系保证。代理模型必须设父对象否则容易忘记 delete。另外打印用的 QPrinter 如果是栈对象必须保证 QPainter::end() 在它析构之前调用否则会崩溃这在异常路径里特别容易漏。5.2 常见问题速查表现象最可能的原因快速定位手段处理方式万行数据滚动掉帧data() 里做了格式化/查询在 data() 里加调用计数格式化前置缓存data() 只取值数字列排序错乱代理按 DisplayRole 字符串比较点一下表头看排序结果自定义 lessThan 用原始值比较表头与内容左右错一位冻结列双视图列宽不同步对比两侧 sectionSize监听 sectionResized 同步打印多出空白页分页循环末尾多 append打印页数组大小判断 used 0 再 append某行内容超高导致死循环单行高度超过正文区高度打印日志逐行输出高度加 h contentHeight 强制单页分支打印中文变方框或空白字体未指定或未嵌入查看 PDF 字体属性显式指定字体族并确认嵌入CSV 打开乱码缺 UTF-8 BOM十六进制看文件头写入 EF BB BFCSV 数据整体错列字段含逗号未转义搜文件里的逗号数量加引号包裹与双引号转义单元格双击后数据消失flags 返回了可编辑但没实现 setData检查 flags 返回值只读场景移除 ItemIsEditable退出时崩溃QPainter 在 QPrinter 之后析构看崩溃栈保证先 end() 再析构表里最后一条我想再补一句。QPrinter 是 QPaintDeviceQPainter 在它上面 begin 之后如果 painter 的生命周期超过了 printerpainter 析构时会往一个已经销毁的设备上写数据直接段错误。我一般的写法是把 painter 声明在 printer 之前利用栈的逆序析构保证 painter 先亡或者在函数出口显式调用painter.end()。打印函数里如果有多个 return 分支很容易漏掉 end用 RAII 包一层更稳。5.3 几个不太正经但很有用的经验经验一打印预览用一个假的 QPaintDevice。不要每改一次页边距就真打一张纸。QPrinter 设成 PdfFormat 输出到临时目录再用程序内的查看器打开迭代速度能快十倍。更极致的做法是继承 QPaintDevice 做一个纯内存的模拟设备只统计每个绘制指令落到了哪个坐标用来自动化验证分页是否正确。经验二给分页结果加一个可视化的调试开关。我在开发阶段加过一个宏开启之后每一页的外框、页眉区、正文区、页脚区各画一个彩色的半透明矩形一眼就能看出哪里超界了。上线前把这个宏关掉。这个技巧在任何涉及版面计算的地方都好使。经验三行高不要用 sizeHint 一遍遍算。如果行高是固定的直接在视图上设 defaultSectionSize如果行高依赖内容在数据装载的时候一次性算好存进模型别指望委托每次去算。委托的 sizeHint 会被高频调用任何在里面做字符串测量的实现都是性能杀手。经验四导出大文件时给出进度反馈。几万行导出 xlsx 可能要好几秒这期间界面完全卡死用户以为程序挂了会疯狂点击。正确做法是把导出放到工作线程主线程显示一个进度对话框并且允许取消。注意导出过程不能直接操作模型要在工作线程里先把数据快照出来否则会跟主线程的模型访问冲突。最后再分享一个小技巧。这套报表控件的代码量最后到了六千多行我一个人维护有点吃力后来做了一件事把列定义、样式规则、打印参数全部抽成一份配置文件我用的就是 JSON界面和打印两头都从这份配置读。好处是业务侧提这一列改成红色、宽度加倍、打印时不显示我不用改代码改配置重新加载就行。缺点是配置的校验要做好写错了要给出明确的错误提示不能静默失败。这个设计后来在另一个项目里直接复用省了大量的重复开发。如果你手上的报表需求还在频繁变动建议一开始就把这层配置化考虑进去比事后重构划算得多。
报表这个东西凡是做过管理系统的都绕不开。我上一次接到的需求是给一套内部数据汇总程序加一个报表模块屏幕上看要能排序、筛选、高亮异常行打印出来要带页眉页脚和页码还要能一键导出 PDF 和表格文件给业务侧归档。最开始图省事直接拿 QTableWidget 堆两百来行数据的时候一切正常等真实数据灌到几万行、列数涨到三十多列、还要求跨页打印保持表头的时候卡顿、错位、打印断页全来了。后来推倒重做走的是 Qt 原生 Model/View 那套 MVC 架构自己写模型、自己写委托、自己算分页才把这套 QT 自定义报表控件开发从屏幕渲染到打印导出的完整链路跑通。这篇就把整个过程拆开讲为什么不用现成控件、模型层怎么写才不卡、表头合并和冻结列怎么处理、打印时毫米和像素怎么换算、分页算法怎么推、导出 PDF 和表格文件各自踩了什么坑。适合已经会用 Qt 画界面、但一碰到大数据量表格和打印就发怵的开发者也适合正在评估报表方案的技术负责人代码片段基本可以直接抄去改。1. 需求拆解与技术路线选型1.1 报表控件真正要解决的四个问题很多人一提报表控件脑子里第一反应是一个能显示表格的控件。这个理解偏差会把后面的设计带歪。实际项目里一个能用的报表控件至少要同时扛住四件事而且这四件事的技术诉求是互相冲突的。第一是数据规模。屏幕上的表格动辄几千上万行用户还要滚动、排序、筛选。如果每一行都对应一个真实的控件对象光是对象创建和布局计算就能把主线程吃满。第二是表现力。报表不是纯文本表格它有合并单元格、有多级表头、有按阈值变色的数值、有千分位和百分比格式化、有合计行加粗。第三是输出一致性。屏幕上看到的列宽比例、对齐方式、颜色标记打印到纸上或者导出成文件之后必须还在不能屏幕是一套、纸上是另一套。第四是可扩展。今天要 A4 纵向明天要 A3 横向后天要按部门分组小计这些变化不应该每次都要动核心渲染代码。把这四点摆在一起看就能明白为什么现成控件撑不住。QTableWidget 本质是用控件堆出来的表格它把数据和视图焊死在一起天生不适合大数据量而 QTableView 加自定义模型是数据与视图分离把复杂度转移到了模型层视图只负责取它当前可见的那几十行。这个分离是整套方案的地基后面所有的性能优化和打印复用都是从这儿长出来的。我在做技术选型的时候画过一张对照表把当时考虑过的四条路线摆在一起比了一遍最后选了第二条。这个对比过程值得展开说因为很多人卡在选型上选完了才发现方向错了返工成本极高。1.2 四条技术路线的横向对比路线实现方式优点致命短板适用场景控件堆叠QTableWidget 逐格 setItem上手最快 demo 半小时能出万行级必卡样式与数据耦合行数固定在百级以内的小工具模型视图QAbstractTableModel QTableView 自定义委托大数据量流畅屏幕与打印可共用同一份数据源需要自己实现排序、合并、分页绝大多数业务报表图元自绘QGraphicsView QGraphicsScene 全手绘排版自由度最高复杂图表混排友好交互逻辑选中、编辑、键盘导航全部自己写以图形为主、表格为辅的看板网页渲染内嵌网页组件渲染 HTML 表格前端生态成熟样式容易做得漂亮与原生程序的数据交互成本高打印控制权不在自己手里已有前端报表体系、只做展示这张表里最关键的一行判断是打印控制权。第三条和第四条路线在屏幕上都能做得很好看但一旦要求打印时表头每页重复、页码居中、页脚带导出时间控制权就必须在自己手里。图元自绘可以但要额外写一套打印渲染器网页渲染基本没戏只能依赖对方提供的打印接口参数调不动。所以最终方案是QAbstractTableModel 承载数据QTableView 负责屏幕呈现QStyledItemDelegate 负责单元格外观QPrinter QPainter 负责打印导出复用打印的绘制逻辑。这套组合的好处是打印和屏幕走同一份模型数据格式化的逻辑只写一次两边自动一致。注意不要为了打印好看而在视图层做额外的样式处理。样式一旦写进视图打印时就得再写一遍两边迟早会漂移。所有格式化统一收敛到模型的 Qt::DisplayRole 里视图和打印都只消费结果。1.3 分层结构与模块边界定了路线之后我把整个控件拆成五层每一层只依赖它下面那一层不允许跨层调用。这个约束听起来教条但在报表这种需求天天变的场景里它能救命。数据层是纯业务结构体一个 Row 就是一组单元格值加一个状态标记正常、预警、异常不继承任何 Qt 类不掺任何界面逻辑。这一层的好处是单元测试好写业务侧改字段不影响界面。模型层继承 QAbstractTableModel负责把 Row 数组翻译成 Qt 认识的角色数据。它是唯一知道第几列叫什么、用什么格式、怎么对齐的地方。视图层是 QTableView 加几个自定义表头组件只做三件事显示、滚动、把用户的排序筛选请求转发出去。委托层继承 QStyledItemDelegate处理那些模型表达不了的视觉效果比如进度条单元格、状态圆点、合并单元格的边框。输出层是打印和导出它不碰视图直接从模型取数据自己算页面坐标。这一层是整套设计里最费劲的部分也是最能体现功力差距的地方。分层之后有个直接好处需求变更时能迅速定位到该改哪一层。要加一列改数据结构和模型的列定义要改颜色规则改模型的 BackgroundRole要改打印页边距只动输出层的一个常量。我在项目中期经历过一次所有数值列改成右对齐、小数点统一两位的调整因为格式化的定义都集中在列定义结构体里改了一个循环就完事了没有满世界找 setAlignment。2. 模型层的设计细节与性能红线2.1 三个必须实现的虚函数与两个容易漏的QAbstractTableModel 是个抽象类不实现纯虚函数编译都过不去。真正需要动脑子的是 rowCount、columnCount、data 这三个以及两个经常被忘掉但会引发诡异问题的headerData 和 flags。class ReportModel : public QAbstractTableModel { Q_OBJECT public: enum Roles { RawValueRole Qt::UserRole 1, RowStateRole, SpanRole }; int rowCount(const QModelIndex parent QModelIndex()) const override { return parent.isValid() ? 0 : m_rows.size(); } int columnCount(const QModelIndex parent QModelIndex()) const override { return parent.isValid() ? 0 : m_columns.size(); } QVariant data(const QModelIndex idx, int role) const override; QVariant headerData(int section, Qt::Orientation o, int role) const override; Qt::ItemFlags flags(const QModelIndex idx) const override { if (!idx.isValid()) return Qt::NoItemFlags; return Qt::ItemIsEnabled | Qt::ItemIsSelectable; } };parent.isValid()那个判断千万别省。表格模型是扁平结构只要 parent 有效就说明有人把你当树模型在用此时必须返回 0否则会触发无限递归或者越界崩溃。我见过一个 bug 排查了大半天最后发现是有人套了两层代理模型外层把内层当树查询而内层没做这个判断直接数组越界。flags返回里如果没有 Qt::ItemIsEnabled单元格会显示成灰色点击没反应。如果返回了 Qt::ItemIsEditable 却没实现 setData用户双击进入编辑态后改完一回车数据就消失体验极差。报表控件一般是只读的老老实实给 Enabled 加 Selectable 就够了别手贱加 Editable。headerData处理的是行号和列标题。有个细节竖直表头行号默认显示 1、2、3 这种序号如果业务上需要显示第 N 行或者干脆隐藏都在这里控制。返回空 QVariant 表示没有表头文字但那一列的位置依然占着想要彻底移除得调verticalHeader()-setVisible(false)。2.2 用角色承载对齐、颜色与原始值data()是整个模型里调用最频繁的函数视图每刷新一次就会对每个可见单元格调好几个角色。它的实现质量直接决定滚动流畅度。QVariant ReportModel::data(const QModelIndex idx, int role) const { if (!idx.isValid() || idx.row() m_rows.size()) return {}; const Row row m_rows.at(idx.row()); const ColumnDef col m_columns.at(idx.column()); switch (role) { case Qt::DisplayRole: { const QVariant raw row.cells.value(idx.column()); return col.formatter ? col.formatter(raw) : raw; } case Qt::TextAlignmentRole: return int(col.align | Qt::AlignVCenter); case Qt::BackgroundRole: return row.state RowState::Error ? QBrush(QColor(255, 235, 235)) : row.state RowState::Warn ? QBrush(QColor(255, 248, 220)) : QVariant(); case Qt::ForegroundRole: return row.state RowState::Error ? QBrush(QColor(180, 30, 30)) : QVariant(); case RawValueRole: return row.cells.value(idx.column()); default: return {}; } }这里有几个必须讲清楚的点。第一DisplayRole返回的是格式化之后的字符串而RawValueRole返回原始值。为什么要留原始值因为排序和导出都要用。视图上显示1,234.50如果排序时拿这个字符串比会得到 999.00 1,234.50 这种荒谬结果。导出到文件时也一样业务侧要的是数字不是带千分位的文本。第二TextAlignmentRole必须返回 int 类型返回 Qt::Alignment 枚举在某些 Qt 版本上会被当成不认识的类型导致对齐失效。这个坑很隐蔽因为代码能编译、运行不报错就是对齐不对你会以为是样式表覆盖了。第三BackgroundRole返回 QVariant 而不是 QBrush 的空构造。返回一个默认构造的 QBrush画刷样式为 NoBrush和返回空 QVariant 在多数情况下效果一样但在某些平台上默认 QBrush 会被画成黑色非常难看。养成返回 QVariant() 的习惯。格式化函数我建议做成函数指针存在 ColumnDef 里而不是在 data() 里写一长串 if-else 判断列索引。前者加列时零成本后者每加一列就要动一次核心函数早晚出事。2.3 多级表头与单元格合并的实现取舍这两个需求几乎每个报表都会提而 Qt 原生一个都不支持。QHeaderView 只能显示一层标题QTableView::setSpan 能做合并但是静态的数据变了得手动重算。我试过三种方案最后是组合着用的。多级表头的第一种做法是自绘表头。继承 QHeaderView重写paintSection在 paint 里根据当前 section 的位置自己算层级矩形、画文字、画分隔线。这方案灵活度最高能做出任意层级的树状表头代价是要自己处理列宽变化、滚动偏移、点击命中的区域映射。我实际写下来大概两百多行难点在坐标换算sectionViewportPosition(section)给出的是相对于视口的位置画的时候要减去滚动量。第二种做法是把表头当成模型的第一行。在 data() 里判断 row() 0 时返回表头文字然后用 setSpan 把跨列的格子合并起来。这个方案实现快缺点是表头会跟着内容一起滚动需要额外固定住而且选中、复制这些交互要专门排除第一行逻辑上很脏。第三种是用一个独立的小 QTableView 只显示一行放在主表格正上方两个视图共享同一个横向滚动条和列宽。这个方案在项目里最常见因为实现简单、视觉效果好、维护成本低。我的做法是主表格的horizontalHeader()直接隐藏上面放一个高度固定的 QTableView列宽变化时用sectionResized信号同步过去。单元格合并用setSpan就够但必须记住一点span 信息不属于模型属于视图。数据重置之后 span 会全部丢失必须在modelReset或者数据刷新完成后重新计算一遍。我的一般做法是写一个rebuildSpans()函数遍历数据找出需要合并的连续区间先把旧的 clearSpans再逐个 setSpan。注意 setSpan 的顺序有讲究先设置跨列大的再设置小的或者干脆不重叠否则会出现合并区域互相覆盖、边缘绘制错乱。2.4 万行数据下的响应速度怎么保住性能这块我踩过的坑比写过的代码还多。总结下来就三条红线破了任何一条滚动就开始掉帧。第一条data() 里不许做重活。不要在这里查数据库、不要做字符串拼接循环、不要调用会分配大量内存的格式化函数。我见过有人在 data() 里对每个单元格调一次正则替换五万行三十列滚一下卡三秒。正确的做法是把格式化结果在数据装载时算好缓存起来data() 只做取值。第二条批量更新必须用 beginResetModel/endResetModel不要逐行 insertRows。逐行插入意味着每插一行都要发一次 rowsInserted 信号视图要重新布局一次。两千行就是两千次布局肉眼可见地卡。void ReportModel::setRows(QVectorRow rows) { beginResetModel(); m_rows std::move(rows); endResetModel(); }第三条行高列宽固定别开自动适应。resizeRowsToContents()和resizeColumnsToContents()会遍历所有行所有列计算理想尺寸十万个单元格算下来就是几秒钟。我一般在数据装载完成后只算一次把结果缓存进 QHeaderView之后切到 Fixed 模式。view-horizontalHeader()-setSectionResizeMode(QHeaderView::Fixed); view-verticalHeader()-setSectionResizeMode(QHeaderView::Fixed); view-verticalHeader()-setDefaultSectionSize(28); view-setWordWrap(false);setWordWrap(false)这一行容易被忽略但对性能影响很大。开着自动换行的时候视图要计算每个单元格的文字折行位置这个计算量跟文本长度成正比。报表通常列宽固定、文字截断加省略号就够了关掉换行能省下不少开销。排序这块还有个坑。用 QSortFilterProxyModel 直接代理默认走的是 DisplayRole 的字符串比较数字列会排错。解决办法是继承代理模型重写 lessThan用原始值比。bool NumberAwareProxyModel::lessThan(const QModelIndex l, const QModelIndex r) const { const QVariant lv l.data(RawValueRole); const QVariant rv r.data(RawValueRole); if (lv.isValid() rv.isValid() lv.userType() QMetaType::Double rv.userType() QMetaType::Double) return lv.toDouble() rv.toDouble(); return QSortFilterProxyModel::lessThan(l, r); }这里用userType()而不是老的type()因为后者在新版本里已经标记弃用编译会报警告。这种小细节迁移的时候特别烦建议一开始就写新接口。3. 视图与委托让表格长成报表的样子3.1 委托里做单元格渲染的边界在哪QStyledItemDelegate 能做的事情很多但我给自己定了个规矩委托只处理模型表达不了的视觉不处理数据逻辑。什么算表达不了进度条、状态圆点、带箭头的涨跌标识、合并单元格的内边框、单元格内的多行文本这些都需要拿到 QPainter 自己画模型给不了。而数字格式化、单位换算、颜色阈值判断这些都属于数据逻辑必须放模型。委托的核心是两个函数paint和sizeHint。void ReportDelegate::paint(QPainter *p, const QStyleOptionViewItem opt, const QModelIndex idx) const { QStyleOptionViewItem o(opt); initStyleOption(o, idx); const QVariant raw idx.data(RawValueRole); if (idx.data(CellTypeRole).toInt() CellType::Progress raw.isValid()) { p-save(); const QRect r o.rect.adjusted(4, 6, -4, -6); p-setRenderHint(QPainter::Antialiasing, true); // 底槽 p-setPen(Qt::NoPen); p-setBrush(QColor(0, 0, 0, 18)); p-drawRoundedRect(r, 3, 3); // 进度 const double ratio qBound(0.0, raw.toDouble(), 1.0); QRect fill r; fill.setWidth(int(r.width() * ratio)); p-setBrush(ratio 0.9 ? QColor(200, 60, 60) : QColor(52, 152, 219)); p-drawRoundedRect(fill, 3, 3); // 百分比文字 p-setPen(QColor(60, 60, 60)); p-drawText(o.rect, Qt::AlignCenter, QString::number(ratio * 100, f, 0) %); p-restore(); return; } QStyledItemDelegate::paint(p, o, idx); }这段代码里最容易被低估的是initStyleOption。它会从模型把文字、对齐、颜色、字体全部填充到 QStyleOptionViewItem 里省去你手动取的麻烦。忘了调它你会发现自绘的部分正常、默认绘制的那部分全都变成空白。p-save()和p-restore()成对出现是硬要求。曾经有一次我漏了 restore结果后面所有单元格的文字颜色全变成了红色排查了半天才想起来是画笔状态没还原。还有一个性能注意点setRenderHint(QPainter::Antialiasing)只对当前这次绘制有效每次 paint 都要重新设。但如果整张表都是进度条每次都开抗锯齿会有开销可以改成只在圆角矩形这个分支里开。sizeHint相对简单但对性能也有影响。如果所有行都返回同一个高度可以在视图层直接用setDefaultSectionSize固定让委托的 sizeHint 根本不被调用速度更快。3.2 冻结列与自适应列宽的实操冻结列是报表的高频需求尤其是第一列是编号或者名称的时候横向滚动过去就看不见了用户会骂人。新一些的 Qt 版本里 QTableView 提供了setFrozenColumnCount一行代码搞定。但如果项目用的版本比较老就得自己搭。我用的是双视图方案左右各一个 QTableView左边只显示前 N 列右边显示剩下的两个视图共享同一个模型左边关闭横向滚动条和竖直表头右边同步竖直滚动条。void syncScrollBars() { // 竖直滚动条双向同步 connect(m_left-verticalScrollBar(), QScrollBar::valueChanged, m_right-verticalScrollBar(), QScrollBar::setValue); connect(m_right-verticalScrollBar(), QScrollBar::valueChanged, m_left-verticalScrollBar(), QScrollBar::setValue); // 选中行同步 connect(m_left-selectionModel(), QItemSelectionModel::selectionChanged, this, [this] { m_right-selectionModel()-select( m_left-selectionModel()-selection(), QItemSelectionModel::ClearAndSelect | QItemSelectionModel::Rows); }); }双视图方案的坑在于左右两边的行高必须完全一致否则滚动到后面会错位。解决办法是给两边都设成 Fixed 模式并且用同一个 defaultSectionSize。另外左边视图的horizontalScrollBar()-setVisible(false)之后它的宽度会变化导致右边视图的布局跟着动需要在 resize 事件里重新调整两边的宽度比例。自适应列宽是另一块。用户拖拽列宽、双击分隔线自动适应、窗口 resize 时按比例分配这三件事要协调好否则会打架。我最终采用的是权重分配算法每个列定义里带一个权重值窗口宽度变化时按权重分。void distributeColumnWidths(QHeaderView *header, int totalWidth) { const int n header-count(); if (n 0) return; double sum 0; QVectordouble weights(n); for (int c 0; c n; c) { weights[c] columnWeight(c); // 每列预设权重最小 0.5 sum weights[c]; } int used 0; for (int c 0; c n - 1; c) { const int w qMax(50, int(totalWidth * weights[c] / sum)); header-resizeSection(c, w); used w; } // 最后一列吃掉所有舍入误差保证总宽精确等于可用宽度 header-resizeSection(n - 1, qMax(50, totalWidth - used)); }那个最后一列吃掉舍入误差的处理非常关键。整数除法的累积误差在列数多的时候能有十几个像素表现出来就是表格右边永远有一道白缝或者横向滚动条始终处于激活状态用户滚动一下发现右边还有些空白体验很怪。另外qMax(50, ...)这个下限也得有。窗口缩得很小的时候按权重算出来的宽度可能是负数直接传给 resizeSection 会有警告甚至崩溃。3.3 屏幕与打印的一致性怎么保证这是整套方案里我最看重的一点。很多报表做完之后的毛病是屏幕上一套配色、打印出来另一套屏幕上有斑马纹打印出来全白屏幕上列宽是 3:2:5打印出来挤成一坨。根因是渲染路径分裂了。屏幕走视图和委托打印走另一套手写逻辑两边各写各的格式化不一致是必然的。我的做法是抽出一个纯函数式的绘制单元输入是模型指针、列定义、当前矩形输出是画在 QPainter 上的内容。屏幕渲染时委托调用它打印时打印循环调用它。void ReportPainter::drawCell(QPainter *p, const QRect rect, const ReportModel *model, int row, int col, bool forPrint) const { const QModelIndex idx model-index(row, col); const QString text idx.data(Qt::DisplayRole).toString(); const int align idx.data(Qt::TextAlignmentRole).toInt(); // 斑马纹只在屏幕上画打印为了省墨不画 if (!forPrint row % 2 1) { p-fillRect(rect, QColor(248, 249, 251)); } // 背景色异常行高亮屏幕和打印都要 const QVariant bg idx.data(Qt::BackgroundRole); if (bg.isValid()) p-fillRect(rect, bg.valueQBrush()); // 文字 p-setPen(idx.data(Qt::ForegroundRole).valueQBrush().color()); p-drawText(rect.adjusted(6, 0, -6, 0), align | Qt::TextSingleLine, text); // 边框屏幕用浅灰打印用深灰否则打印机上浅灰会消失 p-setPen(forPrint ? QColor(150, 150, 150) : QColor(230, 230, 230)); p-drawLine(rect.bottomLeft(), rect.bottomRight()); }forPrint这个开关是我后来加的一开始想完全复用实际打印出来发现两个问题一是斑马纹的浅灰在激光打印机上根本印不出来白白浪费碳粉二是屏幕上的分隔线颜色230,230,230太浅纸上完全看不见表格结构散了。所以保留一个开关只在配色这个维度上分叉布局和文字内容严格共用。这个开关的粒度要控制好。如果分叉太多又回到了两套逻辑的老路。我的原则是凡是跟墨、纸、色彩还原相关的允许分叉凡是跟数据、格式、对齐、列宽相关的绝不允许分叉。4. 打印与导出的完整链路4.1 坐标系统换算毫米、像素与缩放打印这块第一道坎就是单位。业务方给的要求是A4 纵向上下左右边距各 15 毫米表格内容区宽度占满而 QPainter 默认工作在设备坐标系里单位是像素且这个像素是打印机的物理像素。A4 是 210 × 297 毫米如果按 1200 DPI 计算一毫米对应 1200 / 25.4 ≈ 47.24 像素整页就是 9921 × 14031 像素。所有尺寸都拿这个数量级去算代码里全是六位数改一个边距要重新算一遍根本没法维护。我的做法是在 QPainter 上套一层缩放把逻辑坐标重新定义成0.1 毫米一个单位。QPrinter printer(QPrinter::HighResolution); printer.setPageSize(QPageSize(QPageSize::A4)); printer.setPageOrientation(QPageLayout::Portrait); printer.setPageMargins(QMarginsF(15, 15, 15, 15), QPageLayout::Millimeter); printer.setColorMode(QPrinter::GrayScale); QPainter painter; if (!painter.begin(printer)) { qWarning() 打印机不可用; return; } // 逻辑坐标1 单位 0.1 毫米 constexpr double kUnitsPerMm 10.0; const double sx printer.logicalDpiX() / (25.4 * kUnitsPerMm); const double sy printer.logicalDpiY() / (25.4 * kUnitsPerMm); painter.scale(sx, sy);换完之后整个坐标系变得非常直观页面宽度 2100 单位高度 2970 单位页边距 150 单位可用内容宽度 1800 单位行高 60 单位就是 6 毫米。所有常量都是三位数肉眼看就能判断合不合理。这里有个细节要注意logicalDpiX()和logicalDpiY()在绝大多数打印机上是相等的但保险起见还是分开算。曾经遇到过一台老式打印机横向和纵向 DPI 不一致如果用一个值算打印出来整个表格会被拉伸行高看着没问题但宽度不对非常难查。还有一个坑是QPrinter::HighResolution和QPrinter::ScreenResolution的选择。HighResolution 会给出打印机的真实分辨率通常是 600 或 1200ScreenResolution 会给出屏幕的 96 左右。用 ScreenResolution 打印出来的文字会有明显的锯齿因为它把 96 DPI 的位图放大到了 1200 DPI 的纸上。除非是为了出草稿看排版否则一律用 HighResolution。4.2 分页算法逐行推演分页是整套打印逻辑的核心也是最容易出错的地方。核心思路其实简单从上往下逐行累加高度加不下了就换页。但细节上一堆坑。先明确几个常量。页面高度 2970 单位297 毫米上下边距各 150可用高度 2670。其中表头占 80页脚占 70那么正文可用高度是 2670 - 80 - 70 2520 单位。行高固定 60那么每页最多能放 2520 / 60 42 行。但实际不能写死 42。因为有的行会因为内容多而变高有的报表要插入小计行高度不固定。所以还是得逐行累加。struct PageLayout { int startRow; int endRow; int usedHeight; }; QVectorPageLayout paginate(const ReportModel *model, int contentHeight) { QVectorPageLayout pages; const int rows model-rowCount(); if (rows 0) return pages; int start 0; int used 0; for (int r 0; r rows; r) { const int h rowHeight(model, r); // 单行高度含小计行加高 // 关键如果这一行单独就超过一页必须强制放下否则死循环 if (h contentHeight) { if (used 0) { pages.append({start, r - 1, used}); start r; used 0; } pages.append({r, r, h}); start r 1; used 0; continue; } if (used h contentHeight) { pages.append({start, r - 1, used}); start r; used 0; } used h; } if (used 0) pages.append({start, rows - 1, used}); return pages; }这段代码里最容易被忽略的是那个h contentHeight的分支。如果某一行比如一个带了大量备注文字的合并行自身高度就超过了正文区高度不加这个判断的话used h contentHeight永远成立每次都会开新页但一行都没放进去最后无限循环程序直接假死。我在测试阶段用一条两米长的备注文字把这个 bug 触发过主线程卡死只能强杀。另一个细节是页尾的孤行控制。如果某页的最后一行恰好是一个分组的第一行而它的兄弟行都在下一页打印出来会很别扭。业务上要求不高的话可以不管要求高的话得在分页之后做一次回扫检查每页末尾行是否属于一个跨页的分组如果是把整个分组挪到下一页。这个逻辑我实现过大概是分页之后再做一轮调整复杂度不低项目里最终没上因为业务侧说能看就行。分页算完之后绘制循环就清晰了int pageNo 0; for (const PageLayout page : pages) { if (pageNo 0) printer.newPage(); pageNo; drawPageHeader(painter, pageNo, pages.size()); int y pageTopMargin headerHeight; for (int r page.startRow; r page.endRow; r) { int x pageLeftMargin; for (int c 0; c model-columnCount(); c) { const int w columnWidth(c); drawCell(painter, QRect(x, y, w, rowHeight(model, r)), model, r, c, true); x w; } y rowHeight(model, r); } drawPageFooter(painter, pageNo); }列宽的分配跟屏幕上用的是同一个权重算法只是总宽度换成了纸面可用宽度 1800 单位。这样屏幕上看到的比例关系和纸上完全一致。我在前面 3.2 节写的那段distributeColumnWidths稍微改一下就能直接复用把 QHeaderView 换成纯数组计算。4.3 页眉页脚与页码的绘制时机页眉页脚看着简单实际有两个坑。第一个是绘制时机。新手常见的写法是先把所有内容画完再统一回去画页脚。这个在 PDF 输出上可能没问题但在真实打印机上一旦调用newPage()上一页的内容就已经被 flush 到设备了你再也回不去了。所以页脚必须在当前页绘制结束前画完。第二个是内容溢出覆盖。如果正文区的高度算错了最后一行压到了页脚区域页脚文字会跟表格内容叠在一起糊成一团。我的处理办法是给页眉页脚各留出固定的高度预算正文区的高度严格等于总高度减去这两块从算法层面杜绝重叠。绘制顺序就是上面代码里的页眉 → 正文 → 页脚都在同一页的生命周期内完成。void drawPageHeader(QPainter *p, const QString title, const QString subtitle, int pageWidth) { QFont f p-font(); f.setPointSizeF(11); f.setBold(true); p-setFont(f); p-drawText(QRect(0, 40, pageWidth, 60), Qt::AlignHCenter | Qt::AlignVCenter, title); f.setPointSizeF(8); f.setBold(false); p-setFont(f); p-setPen(QColor(110, 110, 110)); p-drawText(QRect(0, 100, pageWidth, 40), Qt::AlignHCenter | Qt::AlignVCenter, subtitle); }字体这块要特别注意中文。QPainter 默认字体在不同系统上差异很大打印中文可能出现方框或者缺字。稳妥的做法是显式指定一个确定存在的字体族并且在导出 PDF 时确认字体被嵌入。设置f.setFamily()之后建议再调一次QFontInfo(f).family()检查实际匹配到的字体如果匹配失败了会返回一个后备字体名能提前发现。页码的格式也有讲究。第 N 页 / 共 M 页这种格式需要先知道总页数所以必须先把分页算完再开始绘制不能边画边数。这也是为什么我把 paginate 单独拆成一个函数先算出完整的页数组再去绘制。4.4 PDF、CSV 与电子表格的导出差异导出这块不同格式的坑完全不一样分开说。PDF最简单因为 QPrinter 直接设置输出格式就行。printer.setOutputFormat(QPrinter::PdfFormat); printer.setOutputFileName(filePath);打印的整套逻辑一行不用改。唯一的注意事项是中文案例里提到的字体嵌入。Qt 在生成 PDF 时默认会嵌入字体子集但如果你指定了一个系统上不存在的字体它会回退到默认字体而默认字体在某些环境下不带中文字形导出来就是一片空白。我遇到过一次屏幕预览正常导出的 PDF 打开全是空白查了半天是字体回退导致的。CSV表面简单实际全是陷阱。第一是编码直接用 UTF-8 写文件用办公软件打开会乱码必须加 BOM 头。第二是分隔符逗号在数值的千分位表示里会出现如果导出的是格式化后的1,234.50用逗号分隔就会把一列拆成两列。所以导出 CSV 时一律用原始值不用 DisplayRole。QFile f(filePath); if (!f.open(QIODevice::WriteOnly | QIODevice::Text)) return; // UTF-8 BOM缺了这仨字节办公软件打开就是乱码 f.write(\xEF\xBB\xBF); QTextStream out(f); out.setCodec(UTF-8); for (int c 0; c model-columnCount(); c) { if (c) out ,; out escapeCsv(model-headerData(c, Qt::Horizontal).toString()); } out \n; for (int r 0; r model-rowCount(); r) { for (int c 0; c model-columnCount(); c) { if (c) out ,; const QVariant raw model-index(r, c).data(RawValueRole); out escapeCsv(raw.toString()); } out \n; }escapeCsv要做的是如果字段里包含逗号、双引号或者换行就把整个字段用双引号包起来并把内部的双引号翻倍。这个规则看着简单漏了就会导致表格错列而且错得很隐蔽——打开文件看着还行往下翻几行数据全错位了。电子表格文件xlsx麻烦在于没有官方库。两条路一是通过 COM 自动化调用本机装好的办公软件好处是格式支持全坏处是依赖本机环境、速度慢、进程容易残留二是引第三方库直接写文件好处是快、无依赖坏处是要多引一个依赖且 API 风格跟 Qt 差别大。我选的是后者。用的时候注意两点一是数字单元格要写数值类型而不是字符串否则导出的文件里单元格左上角带个绿三角用户想求和的时候发现公式不起作用二是大文件导出要考虑内存几万行一次性构建对象树会吃掉几百兆得考虑分批写或者用流式 API。5. 踩过的坑与排查速查表5.1 五类高频问题的定位思路类型一滚动卡顿。定位方法很直接在 data() 里加一个静态计数器滚一次看它被调了多少次。正常情况下滚动一屏应该是可见行数乘列数乘角色数比如 40 × 15 × 4 2400 次左右。如果这个数上了十万说明发生了什么让视图反复全量刷新的事情最常见的是在 data() 里调了会触发 modelReset 的操作或者 selectionModel 的信号处理里做了重活。类型二打印内容错位。表现是列宽跟屏幕对不上、行高不一致、最后一页多出空白页。先查两件事一是屏幕的 distributeColumnWidths 和打印的列宽计算是不是用了同一套权重二是分页函数返回的页数组里有没有used 0的空页。多出空白页十有八九是分页循环最后多 append 了一次。类型三导出文件打不开或者内容乱码。CSV 先查 BOMxlsx 先查文件是否完整写入没 close 就返回了。PDF 查字体是否嵌入最简单的验证方法是用阅读器打开看文档属性里的字体列表如果显示的是未嵌入就要改字体设置。类型四表头与内容错位。这个几乎只出现在冻结列的双视图方案里。检查两点两边视图的 defaultSectionSize 是否一致、两边的 horizontalHeader 高度是否一致。表头高度不一致的话第一行的垂直位置就差了几个像素滚动到后面累积起来就很明显。类型五程序退出时报错或者卡住。报表模块涉及大量 QObject 连接视图、模型、代理、委托之间的生命周期关系要理清。我的处理原则是模型的父对象设成主窗口视图和委托的父对象也设成主窗口三者的析构顺序由 Qt 的父子关系保证。代理模型必须设父对象否则容易忘记 delete。另外打印用的 QPrinter 如果是栈对象必须保证 QPainter::end() 在它析构之前调用否则会崩溃这在异常路径里特别容易漏。5.2 常见问题速查表现象最可能的原因快速定位手段处理方式万行数据滚动掉帧data() 里做了格式化/查询在 data() 里加调用计数格式化前置缓存data() 只取值数字列排序错乱代理按 DisplayRole 字符串比较点一下表头看排序结果自定义 lessThan 用原始值比较表头与内容左右错一位冻结列双视图列宽不同步对比两侧 sectionSize监听 sectionResized 同步打印多出空白页分页循环末尾多 append打印页数组大小判断 used 0 再 append某行内容超高导致死循环单行高度超过正文区高度打印日志逐行输出高度加 h contentHeight 强制单页分支打印中文变方框或空白字体未指定或未嵌入查看 PDF 字体属性显式指定字体族并确认嵌入CSV 打开乱码缺 UTF-8 BOM十六进制看文件头写入 EF BB BFCSV 数据整体错列字段含逗号未转义搜文件里的逗号数量加引号包裹与双引号转义单元格双击后数据消失flags 返回了可编辑但没实现 setData检查 flags 返回值只读场景移除 ItemIsEditable退出时崩溃QPainter 在 QPrinter 之后析构看崩溃栈保证先 end() 再析构表里最后一条我想再补一句。QPrinter 是 QPaintDeviceQPainter 在它上面 begin 之后如果 painter 的生命周期超过了 printerpainter 析构时会往一个已经销毁的设备上写数据直接段错误。我一般的写法是把 painter 声明在 printer 之前利用栈的逆序析构保证 painter 先亡或者在函数出口显式调用painter.end()。打印函数里如果有多个 return 分支很容易漏掉 end用 RAII 包一层更稳。5.3 几个不太正经但很有用的经验经验一打印预览用一个假的 QPaintDevice。不要每改一次页边距就真打一张纸。QPrinter 设成 PdfFormat 输出到临时目录再用程序内的查看器打开迭代速度能快十倍。更极致的做法是继承 QPaintDevice 做一个纯内存的模拟设备只统计每个绘制指令落到了哪个坐标用来自动化验证分页是否正确。经验二给分页结果加一个可视化的调试开关。我在开发阶段加过一个宏开启之后每一页的外框、页眉区、正文区、页脚区各画一个彩色的半透明矩形一眼就能看出哪里超界了。上线前把这个宏关掉。这个技巧在任何涉及版面计算的地方都好使。经验三行高不要用 sizeHint 一遍遍算。如果行高是固定的直接在视图上设 defaultSectionSize如果行高依赖内容在数据装载的时候一次性算好存进模型别指望委托每次去算。委托的 sizeHint 会被高频调用任何在里面做字符串测量的实现都是性能杀手。经验四导出大文件时给出进度反馈。几万行导出 xlsx 可能要好几秒这期间界面完全卡死用户以为程序挂了会疯狂点击。正确做法是把导出放到工作线程主线程显示一个进度对话框并且允许取消。注意导出过程不能直接操作模型要在工作线程里先把数据快照出来否则会跟主线程的模型访问冲突。最后再分享一个小技巧。这套报表控件的代码量最后到了六千多行我一个人维护有点吃力后来做了一件事把列定义、样式规则、打印参数全部抽成一份配置文件我用的就是 JSON界面和打印两头都从这份配置读。好处是业务侧提这一列改成红色、宽度加倍、打印时不显示我不用改代码改配置重新加载就行。缺点是配置的校验要做好写错了要给出明确的错误提示不能静默失败。这个设计后来在另一个项目里直接复用省了大量的重复开发。如果你手上的报表需求还在频繁变动建议一开始就把这层配置化考虑进去比事后重构划算得多。
