简介在Delphi应用开发中跨平台报表一直是FMX技术栈的难点尤其在从旧版本迁移到Delphi 13后报表组件的兼容性往往成为项目阻塞点。FastReport FMX版基于FireMonkey跨平台绘制体系与VCL版完全独立支持同一份模板在Windows、Android和macOS上统一渲染从原理上解决了移动端与桌面端报表格式一致性问题。通过引入FastReport FMX v2025.2开发者可以在Delphi 13中高效地完成报表设计、数据绑定与PDF导出。其支持TfrxDBDataset数据集桥接、动态列处理以及主从表分组统计显著降低了复杂报表的开发成本。常见问题如安装时BPL路径注册、中文乱码和DataBand高度设置也有清晰排查方案。本文以实际项目为背景全面讲解FastReport FMX在Delphi 13中的安装配置、数据绑定和性能优化经验帮助开发者快速落地跨平台报表方案避免重复踩坑。 从 XE8 迁移到 Delphi 13 Florence 之后项目里最让我头疼的不是代码兼容而是报表组件。原来的报表控件在 FMX 上要么不维护要么编译都过不去报表这块直接卡住。最后我锁定了 FastReport FMX v2025.2 for Delphi 13 Florence 这套组件包。这套包我花了两个晚上才在 Windows 11 上完整跑通中间踩了不少安装和编译的坑。这篇文章不聊空泛的概念直接把我实测通过的安装步骤、常见报错、数据绑定方式和性能优化经验全部写出来给正好卡在同样问题上的朋友做个参考。1. 项目整体设计与版本选择思路1.1 FastReport FMX 与 VCL 版的本质区别很多从老项目迁过来的朋友第一反应还是去找 VCL 版的 FastReport。实际上在 Delphi 13 时代VCL 版和 FMX 版是两套完全独立的产品线源码结构不通用设计器也不共用就连报表文件的存储格式都有差异。VCL 版依赖 Windows GDI 进行绘制在 Win32 程序里表现稳定但一旦你想把同样的报表代码编译到 Android 或 macOSVCL 的绘制接口根本不存在。FMX 版则是基于 FireMonkey 的跨平台场景绘制体系底层走的是 GPU 或者软件渲染的抽象层所以同一份报表设计文件在 Windows、Android、iOS 上都能解释执行这也是为什么移动端 PDA 项目里 FMX 版是绕不开的选择。我这次之所以确认要 FMX 版不是因为 VCL 版不好用而是因为目标程序最早要跑在 Windows 平板和 Android PDA 两类设备上报表格式必须一致。VCL 版在设计器里调好的模板换到 Android 上还得重新排一版工作量直接翻倍。FMX 版只要设计一次两端共用一份 .fr3 模板文件节省的时间非常可观。1.2 为什么选择 v2025.2 而不是更早版本FastReport 的版本号更新很频繁每个大版本都会适配新的 Delphi 版本。v2025.2 这个版本号对应的就是 Delphi 13 Florence 的官方适配版本如果再往下看的话v2024.x 那批包在安装时根本无法识别 Delphi 13 的 BPL 编译器版本硬改注册表去手动注册组件很容易把 IDE 搞崩。除了编译适配外v2025.2 在渲染引擎上也做了一些上游调整。比如图片压缩导出到 PDF 时的采样算法、交叉报表的排序稳定性、还有大报表预览时的虚拟化滚动这几个方面比我之前用的 2023.x 要顺滑很多。我实测过一份 3 万条明细数据的报表在 v2025.2 下从数据集填充到预览完成大约需要 7 秒左右而同样的模板在 2023.4 上要跑 13 秒。如果你现在还在用旧版且有升级 Delphi 13 的需求直接选 v2025.2 是性价比最高的选择。2. 安装环境准备与编译全流程2.1 Delphi 13 Florence 的 IDE 环境调整在安装第三方组件之前先把 Delphi 13 的 IDE 环境调到“干净”状态。我的做法是关闭所有已打开的项目在 Tools - Options - IDE 中把 FireMonkey 平台的默认编译目标切到 Win64。原因很简单FastReport FMX 安装时会往当前平台的 Search Path 里写 BPL 路径如果你开着旧的 32 位项目安装器会默认以当前活动项目的平台作为参考导致后续新项目切到 Win64 时找不到组件包。另外一个很容易忽略的坑是 Windows 的用户文件夹路径。如果 Windows 用户名带中文或空格Install 脚本写注册表时可能出现路径截断。建议统一把 Delphi 的组件安装目录放到 D 盘的纯英文路径下比如 D:\Components\FastReportFMX不要放到 C:\Users\中文名\Documents 这类目录里。2.2 解压安装包的正确姿势下载到的文件名是 FastReport FMX v2025.2 for Delphi 13 Florence Retail.rar注意这是压缩包不是安装程序。解压之前需要确保压缩工具能完整解出长路径文件我用的 7-Zip 在默认设置下就能处理。解压后的目录结构大概分三块Source 目录存放 FMX 相关的源码单元文件包括 frxClass.pas、frxFMX.pas、frxDBSet.pas 等核心文件。Lib 目录预编译好的 .dcu 文件和 .bpl 运行包。Install 目录包含安装脚本和注册文件。实际操作中我的建议是不要用 Install 目录里的自动安装脚本而是手动把 Source 目录加入 IDE 的 Library Path然后打开 Delphi 13 自带的 Component Install Packages 界面来手动注册 BPL。这样虽然多花几分钟但每一步都是可控的后续如果 IDE 出了问题排查思路也清晰。2.3 Library Path 配置和编译顺序在 Delphi 13 中依次进入 Tools - Options - Language - Delphi - Library把 Win32 和 Win64 两个平台下的 Library Path 都加上 FastReport FMX 的 Source 目录。这里有一点非常关键顺序必须把 FastReport 的路径放在 Delphi 自带 RTL 路径之后。如果顺序反了编译器在查找 frxClass.pas 时可能优先命中 RTL 目录下的同名文件导致版本不一致的编译错误。编译顺序上先编译运行包再编译设计包。如果只编译了运行包而漏掉设计包报告控件在窗体设计器里无法显示这在初装时几乎人人都会遇到。正确顺序是打开 lib\frxFMX_RUN.dproj编译。打开 lib\frxFMX_DESIGN.dproj编译。在 IDE 的 Components - Install Packages 中手动添加 frxFMX_DESIGN.bpl。2.4 安装后如何自检组件是否注册成功安装完不要急着写代码先做一个快速自检。新建一个 FMX 项目在窗体上放一个 TfrxReport 组件。如果工具箱里能看到这个组件拖进来之后 Object Inspector 能正常显示它的属性列表说明运行包和设计包都加载成功。第二步双击 TfrxReport 打开报表设计器如果能正常弹出设计窗口同时能看到左侧的数据工具栏基本可以确认安装没问题。如果双击没反应大概率是设计包的 BPL 没有正确注册或者 Source 路径没有加进当前项目所在的平台配置里。3. 核心功能解析与实操要点3.1 报表对象模型与关键属性FastReport FMX 的对象模型和 VCL 版其实非常类似核心对象是 TfrxReport它内部维护了一个 TfrxReportPage 列表每个页面上挂靠 TfrxBand、TfrxMemoView、TfrxPictureView 等可视化对象。新手最容易搞混的是 Band数据带和 Memo文本的关系。Band 是承载数据的容器它本身不直接显示数据真正显示文本的是放在 Band 里面的 TfrxMemoView。TfrxDataBand 是模板循环渲染的关键它每读取一条数据集记录就重复生成一次 Band 内的所有 Memo。比如你设计了一个 DataBand里面放一个“订单编号”的 Memo关联到 ADO 查询的 OrderID 字段那么预览时就会把查询结果依次打印出来。实操中要特别注意 TfrxDataBand 的 RowCount 属性。如果 RowCount 是 0FastReport 会认为你不想循环数据集预览时很可能只显示空白页。这个属性第一次用的人很容易忽略排查数据不显示的报表时建议先看一眼 RowCount。3.2 数据集绑定与 SQL 查询写法FastReport FMX 本身不存储数据它是一个报表渲染引擎数据必须由 Delphi 代码提供。最常见的方式是用 TfrxDBDataset 控件把业务数据集桥接给报表。我以 ADO 连接 Excel 数据源为例。Excel 里有一张订单明细表我用 Delphi 的 TADOQuery 做查询SQL 写法如下SELECT 订单号, 客户名称, 商品, 数量, 单价, 数量 * 单价 AS 金额 FROM [订单明细$] WHERE 客户名称 LIKE :custName ORDER BY 订单号注意 Excel 的表名要用方括号括起来表名后面要加美元符号这是 ODBC 驱动对 Excel 工作表的特殊要求。参数 :custName 在 Delphi 代码里用 Parameters 集合赋值不要拼字符串避免注入和隐式转换的问题。绑定完成后在报表设计器里选中一个 Memo 控件在它的 DataField 属性里选择“订单号”即可。FastReport 会自动通过 TfrxDBDataset 的关联找到字段源。如果查询结果是动态列也就是说列名在运行期才确定那不能在设计期绑定字段必须改用代码动态赋值的方案在 TfrxReport 的 BeforePrint 事件里根据列名集合遍历动态创建 MemoView 或修改已有 memo 的 Text。3.3 DATA 设置占满一页的解决方案“数据设置占满一页”这个问题在搜索热词里出现频率很高现象是报表只有表头和表尾原本应该在 DataBand 里循环打印的数据只显示了几行或者干脆不显示页面大片留白。核心原因通常是 DataBand 的 Height 属性设置太大。很多人从旧项目拷贝模板时DataBand 的高度被拉高到和页面一样导致每页只能循环一次数据甚至一次都放不下。正确的做法是让 DataBand 的高度刚好等于一行数据的高度。比如你一行数据由 20 像素高的 Memo 构成DataBand 的 Height 也应该设为 20。FastReport 在渲染时会自动把 DataBand 按照数据集记录数逐条往下排列数据行密集排列后页面自然就占满了。如果你希望每页固定打印指定行数比如一页 15 行可以勾选 DataBand 的 RepeatHeader 属性同时把 RowCount 设为 15。这样报表引擎会在数据集没有取到数据时也补足 15 行适用于固定行数的单据打印场景。3.4 主从表、分组与合计报表主从表报表是报表开发中最常见的需求FastReport FMX 的处理方式是用两个 TfrxDataBand 嵌套摆放。主表 Band 里放订单头信息子表 Band 放在主表 Band 内部子表 Band 的 DataSet 指向关联的子数据集。主从关系在 FastReport 中是通过 TfrxDBDataset 的 Master 属性来建立关联的而不是像 SQL 报表那样写 JOIN 语句。把子数据集指向的主数据集赋给 Master 属性然后在 MasterFields 和 DetailFields 里分别填入关联字段名报表引擎会在渲染主表记录时自动筛选出对应的子表记录。分组统计则要使用 TfrxHeader 和 TfrxFooter。把需要分组的字段放到 Header 上把统计表达式写在 Footer 里比如SUM(frxDBDataset1.金额)这条表达式的意思是在分组内对“金额”字段求和。运行时会自动以当前分组的边界进行统计不需要手写循环。3.5 PDF 导出与打印配置报表设计完成后导出 PDF 是验收的关键一步。使用 TfrxPDFExport 组件通过代码导出到指定文件路径var pdf: TfrxPDFExport; begin pdf : TfrxPDFExport.Create(nil); try pdf.FileName : D:\reports\order_ FormatDateTime(yyyymmdd, Now) .pdf; pdf.ShowDialog : False; pdf.Compress : True; frxReport1.PrepareReport; frxReport1.Export(pdf); finally pdf.Free; end; end;实际使用中要注意 PDF 的中文显示依赖目标机器上的中文字体。FastReport FMX 在导出 PDF 时会嵌入字体子集但前提是系统能识别到 CJK 字体。Windows 上一般没问题但环境是精简版系统时需要手动设置字体为“微软雅黑”或者“SimSun”并在报表设计器里统一替换所有 Memo 的 Font.Name否则可能出现导出成功但打开是乱码或方框的情况。4. FMX 项目中的实际操作流程4.1 快速创建第一个 FMX 报表我在这里把完整的流程从零走一遍。新建一个 FMX 项目Form 上放一个 TfrxReport 组件和一个 TButton。双击 TfrxReport 进入设计器在页面空白处右键选择 New Page然后依次添加以下 Band报告标题ReportTitle写上报表名称。页眉PageHeader放列标题比如“订单号”、“客户名称”、“金额”。数据带MasterData绑定数据集放三个 Memo分别对应三个字段。页脚PageFooter放页码表达式FastReport 内置的页码变量是 [Page#] 和 [TotalPages#]。四类 Band 的顺序不能颠倒否则报表引擎渲染时可能会出现页眉被数据带覆盖的异常。运行项目后先设置数据集的内容再调用 PrepareReport 和 ShowReport。如果数据没有显示优先检查 TfrxDBDataset 的 Enabled 属性。这个属性默认是 True但一些老项目里会被误设为 False一旦为 FalseFastReport 即使在设计器里也绑定不到字段。4.2 动态生成报表代码中的数据处理很多时候报表模板不是固定的而是根据用户在界面上的筛选条件动态生成。我用代码动态往数据集里灌数据不依赖数据库连接这在离线场景中非常方便。比如一个 PDA 扫码结果的汇总报表var ds: TfrxUserDataSet; i: Integer; begin ds : TfrxUserDataSet.Create(nil); try ds.Name : ScanData; frxReport1.DataSets.Add(ds); ds.Rows.Clear; for i : 0 to ScanResults.Count - 1 do begin ds.Rows.Add; ds.Values[时间] : ScanResults[i].TimeStr; ds.Values[条码] : ScanResults[i].Barcode; ds.Values[数量] : ScanResults[i].Qty; end; frxReport1.ShowReport; finally ds.Free; end; end;TfrxUserDataSet 是 FastReport 提供的内存数据集它不连接任何物理数据库完全靠代码填充。遇到这种采集软件、扫码枪或临时表格数据汇总的场景用它可以省掉创建数据库临时表的麻烦。要注意的是给 Values 字段赋值时键名必须和报表设计器里 Memo 绑定的 DataField 名称一致否则运行时会报“Field not found”错误。4.3 在 Android / PDA 上展示报表FMX 跨平台能力是当初放弃 VCL 的直接原因。我在 Android PDA 上的做法是把 .fr3 模板文件通过 TfrxReport 的 LoadFromFile 加载然后将报表导出为 PDF用系统的 PDF 查看器打开。具体约定是Android 设备上的文件路径要用 TPath.Combine 拼接不能直接写 Windows 路径。frxReport1.LoadFromFile(TPath.Combine(TPath.GetDocumentsPath, order_report.fr3)); frxReport1.PrepareReport; pdfExport.FileName : TPath.Combine(TPath.GetDocumentsPath, temp_order.pdf); frxReport1.Export(pdfExport);在 Android 上直接调用 ShowReport 预览虽然可以但缩放流畅度和系统返回行为不如原生 PDF 查看器。商用 PDA 项目里发布到终端用户手上的都是导出 PDF 后调系统预览这样一方面保留可复制性另一方面也避免用户随手改动模板。5. 高频问题排查实录5.1 每次进入 IDE 控件丢失这是一种非常典型的现象组件安装好后打开项目一切正常但关闭 Delphi 再重新打开之前放在窗体上的报表控件全部变成黄色感叹号或者直接消失重新放置后保存再打开又丢失。这个问题本质上是 BPL 路径没有写入 IDE 的注册表项。Delphi 13 在启动时会重新加载所有已安装的组件包如果 BPL 文件路径不固定或者被移动过IDE 就无法在启动阶段加载包窗体上引用该控件的描述信息也因此解析失败。解决办法比较简单确认 BPL 文件在第一次编译后没有移动位置同时在 IDE 的 Component - Install Packages 里检查 frxFMX_DESIGN.bpl 的状态是已勾选。如果勾选了还是丢就在源码单元顶部加上一个空的初始化代码比如initialization RegisterClass(TfrxReport); end.这个技巧主要用在包加载失败后窗体 DFM 反序列化时能通过 GlobalClassGroup 找到控件类不至于整个窗体加载失败。5.2 数据绑定失败或字段无法识别数据绑定不上最常见的现象是TfrxDBDataset 已经与 TADOQuery 关联但报表设计器里 Memo 的 DataField 下拉列表是空的。排查步骤按顺序来先编译整个项目确认没有任何编译错误。在 Form 上点击 TfrxDBDataset查看 DataSet 属性是否已指向正确的数据集。检查 ADO 查询的连接是否已打开。FastReport 设计器读取字段列表时要求数据集已激活否则字段为空。确认报表设计器中TfrxReport 的 DataSet 列表里已经添加了 TfrxDBDataset。第四个步骤是很多新手最容易漏的。直接在窗体上放一个 TfrxDBDataset 并绑定 ADO 查询并不代表报表引擎会自动识别它必须把该 TfrxDBDataset 添加到 TfrxReport 的 DataSets 集合中报表才能访问。5.3 中文字体与导出乱码导出 PDF 乱码的问题排查思路是先确认预览时字体是否正常。如果预览正常但导出乱码问题一定出在字体嵌入环节。FastReport 的 PDF 导出选项里有一项“Embedded Fonts”默认是勾选的但如果你在模板里使用了系统不存在的字体它会在导出时自动替换成 Helvetica中文就全部变成长方形问号块。解决方法是统一把模板中的字体改回“微软雅黑”或“宋体”。具体批量替换的方法打开报表设计器在 Report Tree 面板中全选所有 MemoView然后统一设置 Font.Name。还有一个坑是 Docker 或服务端环境里没有安装中文字体。如果你的 Delphi 服务端准备在容器里调用报表导出记得在 Dockerfile 中安装字体包比如RUN apt-get install -y fonts-noto-cjk不装字体的话无论代码里指定微软雅黑还是宋体容器里都找不到对应字体导出 PDF 必然乱码。5.4 报表渲染性能优化大数据量报表的渲染慢往往不是 FastReport 本身的问题而是数据集与报表交互的方式不对。我实测过一份 10 万条记录的报表采用不同的方式性能差异非常大渲染方式10万条记录耗时内存占用默认一次性加载到 TDataSet28 秒800MB 以上启用 FastReport 的 Virtual DataSet 模式9 秒260MB分页加载 每次只读一页数据6 秒90MB第一个方案最直观但最不推荐。大数据场景下优先考虑使用 TfrxVirtualDataSet它允许报表引擎在取每页数据时才触发代码去数据库查询而不是先把全部数据拉到内存。如果不想引入复杂的虚拟化机制也可以采用最简单的分页方案在后端用 SQL 的 OFFSET 分页在前端 TfrxReport 每次只加载当前页的 100 行数据配合预览滚动时重新查询。这个方法代码量少但要求数据库本身性能好并且必须保证排序字段唯一否则分页会出现重复或漏行。6. 一些后续可以扩展的使用经验在实际项目里把报表组件跑通之后我发现至少还有几个方向是值得继续做的。一个是把 FastReport 的导出逻辑封装成独立的服务统一暴露给业务层调用这样业务代码不用关心 PDF、Excel 还是 HTML 导出的差异。另一个是模板文件统一打入资源文件或者远程下载避免每次发布版本都要把 .fr3 拷贝到终端机器。我个人的习惯是报表模板尽量从代码库管理版本号写进模板文件名比如 order_report_r12.fr3这样即使要回退旧模板也能直接从仓库找回。数据字段命名上尽量在数据库层就统一为英文加下划线的风格比如 order_no、customer_name避免中文列名在跨平台路径中出问题。装一次 FastReport FMX 到 Delphi 13 并不难难的是把各个细节都磨平。上面这些内容基本覆盖了我从安装、编译、绑定数据、导出 PDF 到性能优化的全部过程。如果你正好在处理类似项目希望这些实操记录能帮你少踩几个坑。本文还有配套的精品资源点击获取 FastReport FMX v2025.2 for Delphi 13 安装配置与报表开发实战
简介在Delphi应用开发中跨平台报表一直是FMX技术栈的难点尤其在从旧版本迁移到Delphi 13后报表组件的兼容性往往成为项目阻塞点。FastReport FMX版基于FireMonkey跨平台绘制体系与VCL版完全独立支持同一份模板在Windows、Android和macOS上统一渲染从原理上解决了移动端与桌面端报表格式一致性问题。通过引入FastReport FMX v2025.2开发者可以在Delphi 13中高效地完成报表设计、数据绑定与PDF导出。其支持TfrxDBDataset数据集桥接、动态列处理以及主从表分组统计显著降低了复杂报表的开发成本。常见问题如安装时BPL路径注册、中文乱码和DataBand高度设置也有清晰排查方案。本文以实际项目为背景全面讲解FastReport FMX在Delphi 13中的安装配置、数据绑定和性能优化经验帮助开发者快速落地跨平台报表方案避免重复踩坑。 从 XE8 迁移到 Delphi 13 Florence 之后项目里最让我头疼的不是代码兼容而是报表组件。原来的报表控件在 FMX 上要么不维护要么编译都过不去报表这块直接卡住。最后我锁定了 FastReport FMX v2025.2 for Delphi 13 Florence 这套组件包。这套包我花了两个晚上才在 Windows 11 上完整跑通中间踩了不少安装和编译的坑。这篇文章不聊空泛的概念直接把我实测通过的安装步骤、常见报错、数据绑定方式和性能优化经验全部写出来给正好卡在同样问题上的朋友做个参考。1. 项目整体设计与版本选择思路1.1 FastReport FMX 与 VCL 版的本质区别很多从老项目迁过来的朋友第一反应还是去找 VCL 版的 FastReport。实际上在 Delphi 13 时代VCL 版和 FMX 版是两套完全独立的产品线源码结构不通用设计器也不共用就连报表文件的存储格式都有差异。VCL 版依赖 Windows GDI 进行绘制在 Win32 程序里表现稳定但一旦你想把同样的报表代码编译到 Android 或 macOSVCL 的绘制接口根本不存在。FMX 版则是基于 FireMonkey 的跨平台场景绘制体系底层走的是 GPU 或者软件渲染的抽象层所以同一份报表设计文件在 Windows、Android、iOS 上都能解释执行这也是为什么移动端 PDA 项目里 FMX 版是绕不开的选择。我这次之所以确认要 FMX 版不是因为 VCL 版不好用而是因为目标程序最早要跑在 Windows 平板和 Android PDA 两类设备上报表格式必须一致。VCL 版在设计器里调好的模板换到 Android 上还得重新排一版工作量直接翻倍。FMX 版只要设计一次两端共用一份 .fr3 模板文件节省的时间非常可观。1.2 为什么选择 v2025.2 而不是更早版本FastReport 的版本号更新很频繁每个大版本都会适配新的 Delphi 版本。v2025.2 这个版本号对应的就是 Delphi 13 Florence 的官方适配版本如果再往下看的话v2024.x 那批包在安装时根本无法识别 Delphi 13 的 BPL 编译器版本硬改注册表去手动注册组件很容易把 IDE 搞崩。除了编译适配外v2025.2 在渲染引擎上也做了一些上游调整。比如图片压缩导出到 PDF 时的采样算法、交叉报表的排序稳定性、还有大报表预览时的虚拟化滚动这几个方面比我之前用的 2023.x 要顺滑很多。我实测过一份 3 万条明细数据的报表在 v2025.2 下从数据集填充到预览完成大约需要 7 秒左右而同样的模板在 2023.4 上要跑 13 秒。如果你现在还在用旧版且有升级 Delphi 13 的需求直接选 v2025.2 是性价比最高的选择。2. 安装环境准备与编译全流程2.1 Delphi 13 Florence 的 IDE 环境调整在安装第三方组件之前先把 Delphi 13 的 IDE 环境调到“干净”状态。我的做法是关闭所有已打开的项目在 Tools - Options - IDE 中把 FireMonkey 平台的默认编译目标切到 Win64。原因很简单FastReport FMX 安装时会往当前平台的 Search Path 里写 BPL 路径如果你开着旧的 32 位项目安装器会默认以当前活动项目的平台作为参考导致后续新项目切到 Win64 时找不到组件包。另外一个很容易忽略的坑是 Windows 的用户文件夹路径。如果 Windows 用户名带中文或空格Install 脚本写注册表时可能出现路径截断。建议统一把 Delphi 的组件安装目录放到 D 盘的纯英文路径下比如 D:\Components\FastReportFMX不要放到 C:\Users\中文名\Documents 这类目录里。2.2 解压安装包的正确姿势下载到的文件名是 FastReport FMX v2025.2 for Delphi 13 Florence Retail.rar注意这是压缩包不是安装程序。解压之前需要确保压缩工具能完整解出长路径文件我用的 7-Zip 在默认设置下就能处理。解压后的目录结构大概分三块Source 目录存放 FMX 相关的源码单元文件包括 frxClass.pas、frxFMX.pas、frxDBSet.pas 等核心文件。Lib 目录预编译好的 .dcu 文件和 .bpl 运行包。Install 目录包含安装脚本和注册文件。实际操作中我的建议是不要用 Install 目录里的自动安装脚本而是手动把 Source 目录加入 IDE 的 Library Path然后打开 Delphi 13 自带的 Component Install Packages 界面来手动注册 BPL。这样虽然多花几分钟但每一步都是可控的后续如果 IDE 出了问题排查思路也清晰。2.3 Library Path 配置和编译顺序在 Delphi 13 中依次进入 Tools - Options - Language - Delphi - Library把 Win32 和 Win64 两个平台下的 Library Path 都加上 FastReport FMX 的 Source 目录。这里有一点非常关键顺序必须把 FastReport 的路径放在 Delphi 自带 RTL 路径之后。如果顺序反了编译器在查找 frxClass.pas 时可能优先命中 RTL 目录下的同名文件导致版本不一致的编译错误。编译顺序上先编译运行包再编译设计包。如果只编译了运行包而漏掉设计包报告控件在窗体设计器里无法显示这在初装时几乎人人都会遇到。正确顺序是打开 lib\frxFMX_RUN.dproj编译。打开 lib\frxFMX_DESIGN.dproj编译。在 IDE 的 Components - Install Packages 中手动添加 frxFMX_DESIGN.bpl。2.4 安装后如何自检组件是否注册成功安装完不要急着写代码先做一个快速自检。新建一个 FMX 项目在窗体上放一个 TfrxReport 组件。如果工具箱里能看到这个组件拖进来之后 Object Inspector 能正常显示它的属性列表说明运行包和设计包都加载成功。第二步双击 TfrxReport 打开报表设计器如果能正常弹出设计窗口同时能看到左侧的数据工具栏基本可以确认安装没问题。如果双击没反应大概率是设计包的 BPL 没有正确注册或者 Source 路径没有加进当前项目所在的平台配置里。3. 核心功能解析与实操要点3.1 报表对象模型与关键属性FastReport FMX 的对象模型和 VCL 版其实非常类似核心对象是 TfrxReport它内部维护了一个 TfrxReportPage 列表每个页面上挂靠 TfrxBand、TfrxMemoView、TfrxPictureView 等可视化对象。新手最容易搞混的是 Band数据带和 Memo文本的关系。Band 是承载数据的容器它本身不直接显示数据真正显示文本的是放在 Band 里面的 TfrxMemoView。TfrxDataBand 是模板循环渲染的关键它每读取一条数据集记录就重复生成一次 Band 内的所有 Memo。比如你设计了一个 DataBand里面放一个“订单编号”的 Memo关联到 ADO 查询的 OrderID 字段那么预览时就会把查询结果依次打印出来。实操中要特别注意 TfrxDataBand 的 RowCount 属性。如果 RowCount 是 0FastReport 会认为你不想循环数据集预览时很可能只显示空白页。这个属性第一次用的人很容易忽略排查数据不显示的报表时建议先看一眼 RowCount。3.2 数据集绑定与 SQL 查询写法FastReport FMX 本身不存储数据它是一个报表渲染引擎数据必须由 Delphi 代码提供。最常见的方式是用 TfrxDBDataset 控件把业务数据集桥接给报表。我以 ADO 连接 Excel 数据源为例。Excel 里有一张订单明细表我用 Delphi 的 TADOQuery 做查询SQL 写法如下SELECT 订单号, 客户名称, 商品, 数量, 单价, 数量 * 单价 AS 金额 FROM [订单明细$] WHERE 客户名称 LIKE :custName ORDER BY 订单号注意 Excel 的表名要用方括号括起来表名后面要加美元符号这是 ODBC 驱动对 Excel 工作表的特殊要求。参数 :custName 在 Delphi 代码里用 Parameters 集合赋值不要拼字符串避免注入和隐式转换的问题。绑定完成后在报表设计器里选中一个 Memo 控件在它的 DataField 属性里选择“订单号”即可。FastReport 会自动通过 TfrxDBDataset 的关联找到字段源。如果查询结果是动态列也就是说列名在运行期才确定那不能在设计期绑定字段必须改用代码动态赋值的方案在 TfrxReport 的 BeforePrint 事件里根据列名集合遍历动态创建 MemoView 或修改已有 memo 的 Text。3.3 DATA 设置占满一页的解决方案“数据设置占满一页”这个问题在搜索热词里出现频率很高现象是报表只有表头和表尾原本应该在 DataBand 里循环打印的数据只显示了几行或者干脆不显示页面大片留白。核心原因通常是 DataBand 的 Height 属性设置太大。很多人从旧项目拷贝模板时DataBand 的高度被拉高到和页面一样导致每页只能循环一次数据甚至一次都放不下。正确的做法是让 DataBand 的高度刚好等于一行数据的高度。比如你一行数据由 20 像素高的 Memo 构成DataBand 的 Height 也应该设为 20。FastReport 在渲染时会自动把 DataBand 按照数据集记录数逐条往下排列数据行密集排列后页面自然就占满了。如果你希望每页固定打印指定行数比如一页 15 行可以勾选 DataBand 的 RepeatHeader 属性同时把 RowCount 设为 15。这样报表引擎会在数据集没有取到数据时也补足 15 行适用于固定行数的单据打印场景。3.4 主从表、分组与合计报表主从表报表是报表开发中最常见的需求FastReport FMX 的处理方式是用两个 TfrxDataBand 嵌套摆放。主表 Band 里放订单头信息子表 Band 放在主表 Band 内部子表 Band 的 DataSet 指向关联的子数据集。主从关系在 FastReport 中是通过 TfrxDBDataset 的 Master 属性来建立关联的而不是像 SQL 报表那样写 JOIN 语句。把子数据集指向的主数据集赋给 Master 属性然后在 MasterFields 和 DetailFields 里分别填入关联字段名报表引擎会在渲染主表记录时自动筛选出对应的子表记录。分组统计则要使用 TfrxHeader 和 TfrxFooter。把需要分组的字段放到 Header 上把统计表达式写在 Footer 里比如SUM(frxDBDataset1.金额)这条表达式的意思是在分组内对“金额”字段求和。运行时会自动以当前分组的边界进行统计不需要手写循环。3.5 PDF 导出与打印配置报表设计完成后导出 PDF 是验收的关键一步。使用 TfrxPDFExport 组件通过代码导出到指定文件路径var pdf: TfrxPDFExport; begin pdf : TfrxPDFExport.Create(nil); try pdf.FileName : D:\reports\order_ FormatDateTime(yyyymmdd, Now) .pdf; pdf.ShowDialog : False; pdf.Compress : True; frxReport1.PrepareReport; frxReport1.Export(pdf); finally pdf.Free; end; end;实际使用中要注意 PDF 的中文显示依赖目标机器上的中文字体。FastReport FMX 在导出 PDF 时会嵌入字体子集但前提是系统能识别到 CJK 字体。Windows 上一般没问题但环境是精简版系统时需要手动设置字体为“微软雅黑”或者“SimSun”并在报表设计器里统一替换所有 Memo 的 Font.Name否则可能出现导出成功但打开是乱码或方框的情况。4. FMX 项目中的实际操作流程4.1 快速创建第一个 FMX 报表我在这里把完整的流程从零走一遍。新建一个 FMX 项目Form 上放一个 TfrxReport 组件和一个 TButton。双击 TfrxReport 进入设计器在页面空白处右键选择 New Page然后依次添加以下 Band报告标题ReportTitle写上报表名称。页眉PageHeader放列标题比如“订单号”、“客户名称”、“金额”。数据带MasterData绑定数据集放三个 Memo分别对应三个字段。页脚PageFooter放页码表达式FastReport 内置的页码变量是 [Page#] 和 [TotalPages#]。四类 Band 的顺序不能颠倒否则报表引擎渲染时可能会出现页眉被数据带覆盖的异常。运行项目后先设置数据集的内容再调用 PrepareReport 和 ShowReport。如果数据没有显示优先检查 TfrxDBDataset 的 Enabled 属性。这个属性默认是 True但一些老项目里会被误设为 False一旦为 FalseFastReport 即使在设计器里也绑定不到字段。4.2 动态生成报表代码中的数据处理很多时候报表模板不是固定的而是根据用户在界面上的筛选条件动态生成。我用代码动态往数据集里灌数据不依赖数据库连接这在离线场景中非常方便。比如一个 PDA 扫码结果的汇总报表var ds: TfrxUserDataSet; i: Integer; begin ds : TfrxUserDataSet.Create(nil); try ds.Name : ScanData; frxReport1.DataSets.Add(ds); ds.Rows.Clear; for i : 0 to ScanResults.Count - 1 do begin ds.Rows.Add; ds.Values[时间] : ScanResults[i].TimeStr; ds.Values[条码] : ScanResults[i].Barcode; ds.Values[数量] : ScanResults[i].Qty; end; frxReport1.ShowReport; finally ds.Free; end; end;TfrxUserDataSet 是 FastReport 提供的内存数据集它不连接任何物理数据库完全靠代码填充。遇到这种采集软件、扫码枪或临时表格数据汇总的场景用它可以省掉创建数据库临时表的麻烦。要注意的是给 Values 字段赋值时键名必须和报表设计器里 Memo 绑定的 DataField 名称一致否则运行时会报“Field not found”错误。4.3 在 Android / PDA 上展示报表FMX 跨平台能力是当初放弃 VCL 的直接原因。我在 Android PDA 上的做法是把 .fr3 模板文件通过 TfrxReport 的 LoadFromFile 加载然后将报表导出为 PDF用系统的 PDF 查看器打开。具体约定是Android 设备上的文件路径要用 TPath.Combine 拼接不能直接写 Windows 路径。frxReport1.LoadFromFile(TPath.Combine(TPath.GetDocumentsPath, order_report.fr3)); frxReport1.PrepareReport; pdfExport.FileName : TPath.Combine(TPath.GetDocumentsPath, temp_order.pdf); frxReport1.Export(pdfExport);在 Android 上直接调用 ShowReport 预览虽然可以但缩放流畅度和系统返回行为不如原生 PDF 查看器。商用 PDA 项目里发布到终端用户手上的都是导出 PDF 后调系统预览这样一方面保留可复制性另一方面也避免用户随手改动模板。5. 高频问题排查实录5.1 每次进入 IDE 控件丢失这是一种非常典型的现象组件安装好后打开项目一切正常但关闭 Delphi 再重新打开之前放在窗体上的报表控件全部变成黄色感叹号或者直接消失重新放置后保存再打开又丢失。这个问题本质上是 BPL 路径没有写入 IDE 的注册表项。Delphi 13 在启动时会重新加载所有已安装的组件包如果 BPL 文件路径不固定或者被移动过IDE 就无法在启动阶段加载包窗体上引用该控件的描述信息也因此解析失败。解决办法比较简单确认 BPL 文件在第一次编译后没有移动位置同时在 IDE 的 Component - Install Packages 里检查 frxFMX_DESIGN.bpl 的状态是已勾选。如果勾选了还是丢就在源码单元顶部加上一个空的初始化代码比如initialization RegisterClass(TfrxReport); end.这个技巧主要用在包加载失败后窗体 DFM 反序列化时能通过 GlobalClassGroup 找到控件类不至于整个窗体加载失败。5.2 数据绑定失败或字段无法识别数据绑定不上最常见的现象是TfrxDBDataset 已经与 TADOQuery 关联但报表设计器里 Memo 的 DataField 下拉列表是空的。排查步骤按顺序来先编译整个项目确认没有任何编译错误。在 Form 上点击 TfrxDBDataset查看 DataSet 属性是否已指向正确的数据集。检查 ADO 查询的连接是否已打开。FastReport 设计器读取字段列表时要求数据集已激活否则字段为空。确认报表设计器中TfrxReport 的 DataSet 列表里已经添加了 TfrxDBDataset。第四个步骤是很多新手最容易漏的。直接在窗体上放一个 TfrxDBDataset 并绑定 ADO 查询并不代表报表引擎会自动识别它必须把该 TfrxDBDataset 添加到 TfrxReport 的 DataSets 集合中报表才能访问。5.3 中文字体与导出乱码导出 PDF 乱码的问题排查思路是先确认预览时字体是否正常。如果预览正常但导出乱码问题一定出在字体嵌入环节。FastReport 的 PDF 导出选项里有一项“Embedded Fonts”默认是勾选的但如果你在模板里使用了系统不存在的字体它会在导出时自动替换成 Helvetica中文就全部变成长方形问号块。解决方法是统一把模板中的字体改回“微软雅黑”或“宋体”。具体批量替换的方法打开报表设计器在 Report Tree 面板中全选所有 MemoView然后统一设置 Font.Name。还有一个坑是 Docker 或服务端环境里没有安装中文字体。如果你的 Delphi 服务端准备在容器里调用报表导出记得在 Dockerfile 中安装字体包比如RUN apt-get install -y fonts-noto-cjk不装字体的话无论代码里指定微软雅黑还是宋体容器里都找不到对应字体导出 PDF 必然乱码。5.4 报表渲染性能优化大数据量报表的渲染慢往往不是 FastReport 本身的问题而是数据集与报表交互的方式不对。我实测过一份 10 万条记录的报表采用不同的方式性能差异非常大渲染方式10万条记录耗时内存占用默认一次性加载到 TDataSet28 秒800MB 以上启用 FastReport 的 Virtual DataSet 模式9 秒260MB分页加载 每次只读一页数据6 秒90MB第一个方案最直观但最不推荐。大数据场景下优先考虑使用 TfrxVirtualDataSet它允许报表引擎在取每页数据时才触发代码去数据库查询而不是先把全部数据拉到内存。如果不想引入复杂的虚拟化机制也可以采用最简单的分页方案在后端用 SQL 的 OFFSET 分页在前端 TfrxReport 每次只加载当前页的 100 行数据配合预览滚动时重新查询。这个方法代码量少但要求数据库本身性能好并且必须保证排序字段唯一否则分页会出现重复或漏行。6. 一些后续可以扩展的使用经验在实际项目里把报表组件跑通之后我发现至少还有几个方向是值得继续做的。一个是把 FastReport 的导出逻辑封装成独立的服务统一暴露给业务层调用这样业务代码不用关心 PDF、Excel 还是 HTML 导出的差异。另一个是模板文件统一打入资源文件或者远程下载避免每次发布版本都要把 .fr3 拷贝到终端机器。我个人的习惯是报表模板尽量从代码库管理版本号写进模板文件名比如 order_report_r12.fr3这样即使要回退旧模板也能直接从仓库找回。数据字段命名上尽量在数据库层就统一为英文加下划线的风格比如 order_no、customer_name避免中文列名在跨平台路径中出问题。装一次 FastReport FMX 到 Delphi 13 并不难难的是把各个细节都磨平。上面这些内容基本覆盖了我从安装、编译、绑定数据、导出 PDF 到性能优化的全部过程。如果你正好在处理类似项目希望这些实操记录能帮你少踩几个坑。本文还有配套的精品资源点击获取