QtRPT:一个把＂报表模板＂做成 XML 的 C++ 打印库

做 Qt 桌面项目，早晚有一天你会遇到这句需求：

"这个单据要能打印，最好还能导出 PDF，客户还要能自己改模板。"

到这一步，很多人的选择是打开 QPainter，开始手写 drawText、算坐标、调页边距。第一个月还挺爽，第三个月来个"A4 改成 Letter"、"再加一列"，你就知道什么叫用代码堆排版了。

有没有现成的？有，而且不少。但大多要么闭源收费，要么重到要装一整个报表服务器。

今天介绍一个轻的：QtRPT。

它就干一件事——把报表排版抽成一个 XML 模板，程序只负责喂数据。

一、QtRPT 是个啥

一句话：用 C++ / Qt 写的报表打印引擎，配套一个可视化设计器。

项目由两部分组成，官方文档说得很清楚：

所以工作流是：用设计器拖出模板，存成.xml，程序里加载这个 XML 灌数据。

几个基本事实：

• 作者 Aleksey Osipov，主站 SourceForge（sourceforge.net/projects/qtrpt），官网 qtrpt.sourceforge.io
• 版本线：1.x → 2.x → 3.x（SourceForge 上 QtRptProject 3.1.1 是 2025-06，3.2.0 二进制是 2025-10），还在更新
• 许可：Apache 2.0（早期是 LGPL，作者主动改的，为的是允许静态链接）
• 跨平台：Windows / Linux / macOS，纯 Qt 代码
• 输出：打印机、PDF、HTML、XLSX

金句：报表框架的价值不在"能不能画"，而在"改需求的时候谁在熬夜"。

二、核心心智模型：XML + 带区（Band）

QtRPT 没发明新概念，它用的是报表行业用了三十年的Band 模型（FastReport、Crystal Reports 都是这套）。

一个 band 就是"一条横向的区域"，数据来一条，就循环画一遍。

XML 骨架简单到可以背下来：

<reports>  <report>    <ReportBandtype="PageHeader"height="70">      <TContainerFieldtype="label"value="进货单"left="40"top="20"                       width="300" height="30"/>    </ReportBand>    <ReportBandtype="MasterData"height="26">      <TContainerFieldtype="label"value="[Goods]"left="40"top="4"width="220"height="18"/>      <TContainerFieldtype="label"value="[Price]"left="280"top="4"width="90"height="18"/>      <TContainerFieldtype="label"value="<[Price]*1.2>"left="390"top="4"width="90"height="18"/>    </ReportBand>    <ReportBandtype="ReportSummary"height="30">      <TContainerFieldtype="label"value="<Sum([Price])>"left="280"top="6"width="120"height="20"/>    </ReportBand>  </report></reports>

三种节点就够了：

• 根节点，**可以塞多个
  **（一个 XML 出多张报表）
• `` 带区，一共 9 种类型
• `` 带区里的元素（标签、图片、条码、图形、图表……）

坐标单位是"点"（point），1 cm = 40 points。这条得记住，不然你会按 96 dpi 算，结果整张单子都偏。

颜色格式是 rgba(100,100,100,255)；想让某个元素隐藏，写 rgba(255,255,255,0)——纯白 + 全透明，而不是删节点。

三、九种 Band 和它们的打印顺序

这是最容易搞错的部分，官方按优先级排的顺序：

直觉上记：MasterData是循环体，ReportTitle只出现一次，ReportSummary只在末尾。

分组靠 DataGroupHeader + groupingField 指定分组字段；showInGroup=1 表示 MasterHeader/MasterFooter 要嵌进每个分组里；startNewPage=1 可以让每个分组强制换页（做"每个客户一张单"就靠它）。

金句：Band 模型的本质是把"循环"这件事，从代码里搬到了模板里。

四、数据怎么进去：一个信号 + 一个计数

这是全篇最该背下来的 15 行代码。

voidMainWindow::onPrintClicked(){    QtRPT *report = new QtRPT(this);    // 1. 加载模板    if (!report->loadReport(”invoice.xml”)) { /* 处理失败 */ return; }    // 2. 告诉引擎 MasterData 要循环几次    report->recordCount << ui->tableWidget->rowCount();    // 3. 引擎渲染到某个字段时会喊你的名字，你把值填进去    connect(report, &QtRPT::setValue,            [=](const int recNo, const QString paramName,                QVariant &paramValue, const int reportPage)    {        Q_UNUSED(reportPage)        if (paramName == ”customer”) paramValue = ui->edtCustomer->text();        if (paramName == ”Goods”)            paramValue = ui->tableWidget->item(recNo, 0)->text();        if (paramName == ”Price”)            paramValue = ui->tableWidget->item(recNo, 2)->text();    });    report->printExec();          // 弹预览    // report->printPDF(”out.pdf”);  // 或者直接出 PDF}

四个参数的含义：

这个设计叫"拉取式"：引擎不是把整个数据集塞给你，而是渲染到哪个字段就问你要哪个字段。所以：

• 数据源可以是 QTableWidget、QList、QSqlQuery、网络返回的 JSON——引擎根本不关心；
• 同一个 QtRPT 对象理论上可以喂完全不同的数据结构。

但有个大坑：recordCount 忘了设置，MasterData 就一圈都不画，预览出来是空的。这是 QtRPT 新手第一大报错原因。

五、表达式系统：[ ] 和 < > 别搞混

模板里有两种括号，语义完全不同：

函数分三类：

聚合函数（对 MasterData 的所有行汇总，放在 ReportSummary 或 MasterFooter 里）：

<Sum([Price])>      求和<Avg([Price])>      平均<Count([Goods])>    计数<Max([Price])>      最大<Min([Price])>      最小 

还能组合：<Sum([Quantity]) + Sum([Price])>、<Sum([Sum]) * 1.2>。

数学/文本函数：Frac、Floor、Ceil、Round、ToUpper、ToLower、NumberToWords（金额转中文大写，做财务单据很实用）。

系统变量（直接写，不用方括号）：

<Date>  <Time>  <Page>  <TotalPages>  <LineNo>  <LineCount> 

要跑两遍才能拿到（先排完才知道总页数），所以 QtRPT 内部做了 firstPass / secondPass 两轮渲染——这也解释了为什么聚合函数必须放在"数据之后"的 band 里。

另外还有高亮与显隐：条件写在字段的逻辑属性里，满足时换字体色、换背景色，或者干脆隐藏。做"金额超 10 万变红"这种需求，改模板就行，不动代码。

六、SQL 数据源：可以不经过你的代码

如果数据在数据库里，模板里可以直接写查询：

<DataSource>  <sqlQuery>select * from orders where year = [year]</sqlQuery>  <sqlDriver>QSQLITE</sqlDriver>  <charsetCoding>UTF-8</charsetCoding></DataSource>

这时候字段写法变成 订单表.字段名，引擎自己去取。设计器里还有可视化 SQL 编辑器。

两种数据源可以混用：SQL 负责明细，setValue 负责表头参数（客户名、日期、单号）。这是做单据最实用的组合。

七、脚本引擎：模板里写 if

QtRPT 内嵌了一个脚本引擎（Qt 的 QScriptEngine），可以在模板里写逻辑：

function priceBeforeData(){    if ([total] > 1000) {        price.visible = true;        price.fontColor = QColor(255,0,0);    } else {        price.visible = false;    }}function goodsAfterData(value){    return value + ” （已复核）”;}

命名约定是硬性的：

• 字段名 + BeforeData
   —— 在拿到应用数据之前执行
• 字段名 + AfterData(value)
   —— 在拿到数据之后执行，用 return 返回新字符串

字段名必须一字不差，写错了不会报错，只是不生效。这是第二大坑。

AfterData 只该用来改文本；改 visible 之类的属性请放 BeforeData（官方文档明确警告）。

八、四条输出路径

想自己做预览 UI（Qt 自带的那个预览控件很丑），这是标准做法：

QPrinter *printer = new QPrinter(QPrinter::HighResolution);printer->setOutputFormat(QPrinter::PdfFormat);printer->setPageSize(QPageSize::A4);auto *preview = new QPrintPreviewWidget(printer, this);connect(preview, &QPrintPreviewWidget::paintRequested,        report,   &QtRPT::printPreview);report->setPrinter(printer);

setPrinter只能成功设置一次，第二次调用直接返回 false——想换打印机要复用同一个 QPrinter 对象。

九、集成：三种方式

方式一：直接 include 源码（最省事）

include(../QtRPT/QtRpt.pri)

方式二：编译成库

在 config.pri 里打开：

DEFINES += QTRPT_LIBRARY

然后 .pro 里：

contains(DEFINES, QTRPT_LIBRARY) {    INCLUDEPATH += $$PWD/../QtRPT/    LIBS += -L$${DEST_DIRECTORY}/lib -lQtRPT}

方式三：只要打印不要条码（推荐给在意许可的人）

DEFINES += NO_BARCODE

config.pri 一共三个宏：QTRPT_LIBRARY、NO_BARCODE、QXLSX_LIBRARY。

集成后第一步永远是：把设计器生成的 XML 放进 Qt 资源（:/reports/x.xml），用loadReport(":/…")加载，避免发布时路径丢失。

十、坑清单（都是真的会踩）

最后一条尤其值得强调：别假设老 Qt 库能平滑升到 Qt 6。Qt Script 模块在 Qt 6 中被拿掉了，依赖它的报表引擎一定得改造（换成 QJSEngine 或去掉脚本功能）。

十一、它适合谁

适合：

• Qt 桌面端的单据、发票、工单、报表类需求
• 需要客户自己改模板（把 XML 丢给对方就行）
• 需要 PDF / HTML / XLSX 多格式输出
• 想要拖拽设计器但不想买商业报表控件
• 数据源五花八门（表格控件、SQL、内存对象）

不适合：

• 需要服务端批量出报表的 Web 场景（它是桌面库）
• 需要像素级复杂排版（跨页表格、套打、子报表嵌套）——这些是 FastReport / Stimulsoft 的地盘
• 死守 Qt 6 且必须用脚本功能——先验证再决定
• 不愿处理 Zint 的 GPL 传染（那就 NO_BARCODE）

同类可比的还有 QReport、QxFlatPrint 等，但 QtRPT 的优势很实在：Apache 2.0 + 自带设计器 + 十余年迭代 + 完全开源。

结语

QtRPT 没有什么惊天动地的创新，它做的事情非常朴素：

把"排版"从代码里抽出去，变成一个可以被设计器编辑、被版本控制追踪、被客户自己改的 XML 文件。

报表这个需求的恶心之处从来不是"画不出来"，而是"需求一直在变"。当排版躺在代码里，每次改动都是一次编译、一次发版；当排版躺在模板里，改一个 XML 就完事了。

这也是所有模板化方案的共同逻辑——把易变的部分，从编译期挪到运行期。

最后留一句给所有还在手写 drawText 算坐标的朋友：

"代码负责算数，模板负责好看。"

一天的排版工作，本就不该变成一万行 drawText。