FastReport FMX v2025.2 for Delphi 13安装与跨平台报表实战指南

简介：报表控件是跨平台应用开发中连接数据与打印输出的关键组件，其核心原理在于通过模板定义文档结构，再结合数据源接口和统一的渲染引擎，实现一次设计、多处运行。面对FireMonkey框架在Android、Windows等平台上的打印差异和PDF导出需求，成熟报表方案能显著降低开发成本。FastReport FMX作为Delphi生态中常用的报表工具，支持可视化设计器、多种数据源绑定及PDF、Excel等格式导出，尤其适合处理中文乱码、分页错乱等移动端报表难题。在实际工程中，从安装部署、设计器操作到移动端字体与尺寸适配，都需要系统化的实践指引。本文以FastReport FMX v2025.2 for Delphi 13为对象，记录在FireMonkey项目中从零搭建报表环境的完整流程，涵盖组件安装、数据关联、动态内容生成及Android真机部署的关键技巧，帮助开发者快速掌握跨平台报表的实现方法。 最近在做一个 FireMonkey 项目，被报表模块折磨得够呛。Windows 桌面端跑得好好的，一到 Android 平板上，要么中文变成方块，要么分页乱套，客户直接扔过来一句“你们这个报表不行”。折腾两天后，我决定老老实实用 FastReport FMX。正好手头拿到 FastReport FMX v2025.2 for Delphi 13 Florence 的包，这篇文章把从安装部署到实际写报表的完整过程都记录一下。如果你是 Delphi 开发者，尤其是用 FireMonkey 做跨平台应用，需要生成 PDF、打印、导出报表，这篇应该能帮你少走不少弯路。先说清楚，这是 FMX 版，不是 VCL 版，两者虽然同门，但安装方式和使用习惯差别不小。

1. FireMonkey 报表的困境，以及 FastReport FMX 为什么能填坑

1.1 FMX 跨平台 UI 很香，但报表一直是个老大难

FMX 框架本身跨平台做得很好，一套代码编到 Windows、macOS、iOS、Android，UI 效果也接近原生。但报表这玩意和平台关联太深了，因为报表最终要落到打印和 PDF，而每个平台的打印系统完全不一样。Windows 有 GDI/EMF，macOS 有 Quartz，Android 打印服务各家厂商还不太一样。FMX 自带的打印支持，其实只是最基础的页面绘制，真要做一个带页眉页脚、分页、数据分组的正式报表，靠自己写几乎是不现实的。

自己写报表，常规路子有三条，我全走过。第一条是用 TLayout 堆页面，设计时看着直观，运行时把数据库记录循环铺到子控件上，数据一多界面就卡，分页只能靠 TScrollBox，打印缩放完全失控。第二条是用 TStringGrid 或 TGrid 展示，表格样式好调，但 TGrid 是屏幕控件，不是文档模型，导出 PDF 时你得自己绘制，格式还原度很差。第三条是在 Canvas 上直接绘制，最灵活，但页眉怎么重复、页脚怎么放、跨页断行怎么处理、页边距怎么算，全得手写，维护成本高得吓人。

FastReport FMX 的出现把这条逻辑链彻底改了：报表模板（.fr3）里定义的是文档结构，数据通过 TDataSet 接口喂进去，渲染由引擎统一处理。所以你只需要关心数据从哪来、模板长什么样，而不是关心 Windows 和 Android 在打印上有啥区别。这种“一次设计，处处渲染”的模型，才是 FMX 项目里做报表的正解。

1.2 FastReport FMX 的核心能力清单

简单列一下这个版本的核心能力，方便还没接触过的朋友快速建立认知。

实际用下来，最让我满意的是条码对象和 PDF 导出的稳定性。以前用 Canvas 画条码，经常被扫码枪识别不了，换成 FastReport 内置的 Code128 和 QR Code 之后，这个问题再没出现过。

1.3 为什么升级到 v2025.2

v2025.2 这个版本最直观的变化，是官方宣告支持 Delphi 13 Florence。其次在高分屏设计器、PDF 导出字体嵌入、Linux 部署方面都有改进。我实测下来，PDF 导出在中文和嵌入字体方面比之前版本稳定，Android 上中文 PDF 导出不再出现方块字。如果你们项目里有跨平台报表需求，或者正准备迁移到 Delphi 13，这个版本值得关注。

另外一个细节是，v2025.2 对 FMX 的 HiDPI 支持明显做得更好了，Windows 上 150% 缩放的屏幕里，设计器里的标尺和控件位置不会错位。之前某些版本在 4K 屏上打开设计器，字体小到怀疑人生，这个版本修复得不错。

1.4 Retail 版与试用版的区别

Retail 指的是零售正式版，和 Trial 试用版的主要区别在于：试用版会在预览和导出时加限制，比如水印、部分导出格式不可用；Retail 版功能完整，没有这些限制。安装包命名里的 Retail 表明这不是评估版，而是完整功能的正式授权版本。这里也提醒一句：FastReport 是商业控件，拿到安装包后务必确认授权许可，不要在未经授权的环境里使用。

2. 从 rar 压缩包到 IDE 可用的完整部署笔记

2.1 解压后的目录结构，先认清楚再动手

我拿到的是 FastReport FMX v2025.2 for Delphi 13 Florence Retail.rar，解压后是典型的 FastReport FMX 分发包结构。核心目录有这么几个：

• FastReportFMX\Lib：包含各平台的运行时 .dcu 和编译好的 .bpl
• FastReportFMX\Design：设计期包源码和编译单元，这是要安装进 IDE 的部分
• FastReportFMX\Source：核心源码，Retail 版通常包含，排查问题时很有用
• FastReportFMX\Demos：官方 Demo，强烈建议先跑一遍
• FastReportFMX\Setup.exe 或 Install.bat：官方安装脚本

如果你手里的压缩包里有 Setup.exe，直接以管理员身份运行，它会自动识别 Delphi 版本并完成路径配置。但如果只有源码和 dpk，就需要手动编译安装。我这次是手动安装的，因为我需要同时给 Win32、Win64 和 Android 三个平台准备环境，脚本自动装的路径有时候不满足需求。

2.2 在 Delphi 13 中设置 Library 路径

手动安装的第一步，是把 FastReportFMX 的 Lib 目录加入 IDE 库路径。操作路径是 Tools -> Options -> Delphi Options -> Library，在 Library path 里新增以下几项：

$(FastReportFMX)\Lib\Win32 $(FastReportFMX)\Lib\Win64 $(FastReportFMX)\Lib\Android $(FastReportFMX)\Lib\iOS $(FastReportFMX)\Lib\OSX

这里强烈建议先定义一个环境变量 FastReportFMX，指向解压根目录，然后在 Library path 里引用变量。这样以后升级控件版本，只需要改环境变量，不用逐个改项目搜索路径。这步不做的话，编译你的项目时会报找不到 FastReport 相关单元，而且错误提示不会直接告诉你缺的是路径，只会说某个 frx 单元不存在，容易让人误判成组件没装好。

2.3 编译并安装设计期包

FastReport FMX 和其他控件一样，分运行时包和设计期包。运行时包负责程序运行时的逻辑，设计期包安装到 IDE 后，工具箱里才会出现 TfrxReport、TfrxDBDataSet 这些组件。安装步骤大致是这样：

1. 打开 FastReportFMX\Design 目录下的 .dpk 文件，用 Delphi 13 打开。
2. 在工程管理器里确认目标平台为 Win32，设计期包一般只装 Win32。
3. 先编译运行时包，右键 dpk 选择 Build，确保没有编译错误。
4. 再对设计期 dpk 执行 Install，看到 “Package installed successfully” 提示。
5. 重启 IDE，打开一个 FMX 项目，在 Tool Palette 搜索 frx，就能看到组件。

编译过程中如果提示找不到 dcu，回 2.2 步检查路径顺序，尽量把 FastReport 的 Lib 放在 Library path 列表前面，避免和其他控件版本冲突。这里有个小技巧：编译顺序一定是从最底层的运行时包开始往上编译，如果先装了设计期包，会发现它依赖的运行时包还没注册，IDE 启动时会报 “Cannot load package” 错误。

2.4 解决“每次进 IDE 控件丢失”的经典问题

很多 Delphi 开发者都遇到过：装完控件当时能用，重启 IDE 后组件面板里控件不见了，或者打开项目提示“组件类不存在”。这在 FastReport FMX 安装里也常见，我排查下来无非三种原因。

第一种，装的是 32 位设计期包，但 IDE 以 64 位模式运行。Delphi 13 的 IDE 默认是 32 位，但如果你装了其他版本的 64 位 IDE，设计期包必须分别安装到对应的 IDE 里。第二种，设计期包依赖的运行时包没有被注册到系统路径。把 Lib 路径加入 IDE 库路径只是让编译器能找到 dcu，但安装包还要在 Windows 系统路径下找到 .bpl，运行时包没注册好，IDE 启动时静默跳过，组件就不见了。第三种，FastReport 版本和 Delphi 版本不严格匹配，项目面板里还残留旧版本的 FastReport 包，IDE 加载失败。

如果重启后还是丢控件，还有一个土办法：用文本编辑器打开项目的 .dproj 文件，搜索 fastreport 关键字，清理掉旧版本残留的搜索路径，再重新加载项目。IDE 会按 dproj 里的搜索路径去找包，路径不对就报错。这个办法能解决绝大多数“装好了但项目打不开”的问题。

2.5 验证安装成功的标志

安装完不要急着写代码，先跑官方 Demo 验证环境。打开 Demos 目录下的一个 FMX Demo，比如 PrintPreview，编译运行。如果设计器能打开 .fr3 文件、能预览、能导出 PDF，说明环境没问题。我第一次装完没跑 Demo，直接写代码，结果接口不会用，查了半天文档才明白。跑 Demo 还有一个好处是能学习官方推荐的写法，比如设计器里数据字典怎么配置、代码里 frxReport 怎么和 DBDataSet 关联，这些在 Demo 里都有现成的例子。

3. 设计器里最常见的三类操作：连接数据、版面布局、动态内容

3.1 把 TFDQuery 的数据拿到报表里

FastReport FMX 最常用的数据绑定方式是 TfrxDBDataSet。在 FMX 窗体上放一个 TFDConnection、TFDQuery 和 TfrxReport，然后再放一个 TfrxDBDataSet，把它的 DataSet 属性指向 TFDQuery1。接下来在设计器里操作：

1. 双击 TfrxReport 打开报表设计器。
2. 点击左侧“数据字典”窗口，右键新建一个 DataSet 数据源，选择 frxDBDataSet1。
3. 把 DataSet 的字段拖到报表区域，FastReport 会自动生成标题带和数据带。
4. 在数据带（MasterData）上确认数据源已绑定，运行时它会自动迭代数据源里的每一条记录。

一个新手特别容易懵的点是：设计器里的数据带和数据库记录之间的关系。其实很简单，MasterData 就是一个循环模板，一条记录渲染一次，设计器里看到的只是一行，运行时循环输出所有行。页脚带在设计器里是固定的，运行时只有当前页显示一次。如果想让数据刚好占满一页，可以在数据带的高度上做文章，把数据带高度设置成页面可用高度减掉页眉页脚的高度，这样数据量不足一页时自动铺满，数据多时则自动分页。

3.2 主从报表的绑定方式

主从报表常见于订单单据：一个订单对应多个明细。FastReport FMX 里配置也不复杂。窗体上放两个 TFDQuery，qryMaster 和 qryDetail，qryDetail 通过参数关联 qryMaster。再放两个 TfrxDBDataSet，frxDBMaster 指向 qryMaster，frxDBDetail 指向 qryDetail。

设计器里的关键步骤是添加两个数据带：MasterData 绑定 frxDBMaster，DetailData 绑定 frxDBDetail。然后在 DetailData 的 DataSource 属性里选择 MasterData，FastReport 会自动在主数据带迭代时同步刷新子数据。这里要注意，qryDetail 的 SQL 要写成参数化查询，参数值来自主查询的字段：

SELECT * FROM order_items WHERE order_id = :ORDER_ID

我实测这种参数联动在移动端速度还可以，订单明细几百条没问题。如果数据量再大，就要考虑先把明细数据一次性加载到 FDMemTable，再做内存关联，避免逐条查询数据库。

3.3 动态文本、图片和条码

业务报表很少是纯静态文本，常见的是根据数据库字段动态显示。在 FastReport 里，动态显示字段的写法很直观：双击文本对象，在表达式编辑器里写 [qryMaster."FIELD_NAME"]。要拼接字符串，写 [qryMaster."客户姓名"] + ' - ' + [qryMaster."订单号"]。要显示条件内容，可以用 IIF 函数，格式是 IIF(条件, 真值, 假值)：

IIF([qryMaster."金额"] > 1000, '大额', '普通')

图片对象可以绑定数据库 BLOB 字段，比如签名照片、商品图片，也可以通过代码在 BeforePrint 事件里动态赋值。条码对象最常用在物流单上，支持 Code128、QR Code 等。FMX 版在 Android 上也可以渲染条码，这在 PDA 应用里非常实用。我做过一个项目，用 Delphi FireMonkey 的扫码组件拿到快递单号后，直接调用 FastReport 生成一张带条码的标签，从扫码到出单可以一条龙，整个流程跑下来体验很顺。

3.4 报表预览与导出

在代码里启动预览最简单的方式是：

frxReport1.ShowReport();

如果要把预览控件嵌入窗体，比如做一个自定义的预览页面，可以放一个 TfrxPreview 控件到 FMX 窗体，然后设置：

frxReport1.Preview := frxPreview1; frxReport1.ShowReport();

导出 PDF 也很直接：

frxReport1.PrepareReport(); frxReport1.Export(frxPDFExport1);

这里提醒一下，FMX 版的 PDF 导出有一个容易踩的坑：嵌入字体选项。在 TfrxPDFExport 的 Engine 属性里有 EmbeddingFonts 相关设置，移动端建议开启。否则 PDF 文件到了别的设备上，如果对方设备没有你用的中文字体，显示出来就是方框。这个坑我踩过一次，客户在手机上打开 PDF 说全是乱码，排查半天发现是导出时没有嵌入字体。

4. 移动端跑报表：字体、尺寸和运行时部署的几个大坑

4.1 同一套报表在 Windows 和 Android 上的差异

理论上 FastReport FMX 保证跨平台一致，但实际体验里，桌面和移动端还是有三个明显差异。第一个是字体差异：Windows 的微软雅黑，Android 上是 Roboto 或者厂商字体，同一个字体名两边可能都有，但渲染宽度不同，文本会自动换行，导致 PDF 分页不同。第二个是 DPI 差异：FMX 的 TfrxReport 走的是虚拟坐标，然后在不同平台上按 DPI 换算。Android 平板默认密度和 Windows 的 96dpi 不同，同样的报表模板在平板上预览会显得偏小。第三个是打印支持：Android 上没有通用的打印对话框，直接打印不完整，通常都是导出 PDF 再交给其他 App 处理。

这三点在项目规划阶段就要考虑，不要等模板设计完再适配。我当时就是先设计模板后适配移动端，结果字体和 DPI 两个问题来回调，浪费了不少时间。

4.2 中文字体在 FMX Android 上的处理

中文字体是重灾区。我遇到的情况是：Windows 上设置“宋体”没问题，到了 Android 上所有中文变方块。原因很简单，Android 系统里没有“宋体”这个字体名。FastReport FMX 的解决方案是使用字体回退机制，或者干脆在代码里适配。

方案一：模板里不直接指定具体字体名，运行时根据平台判断选择字体，用条件编译或者代码动态设置。方案二：把字体打包进 Assets，通过代码注册字体文件到 FMX 字体缓存，再让报表引用注册后的字体名。方案三：Android 上直接用系统默认字体，模板中文字对象全部不设置 FontName，FastReport 会使用默认字体。

我实际项目里用的是方案三的变种：在代码里设置一个公共字体名，所有中文文本跑报表前统一替换。虽然土但最稳。后来发现一个问题，系统默认字体在 Android 上显示中文没问题，但在 Windows 上字体比较丑，所以我在代码里区分平台：Windows 用微软雅黑，Android 用系统默认字体。

4.3 运行时文件部署

FMX 移动端跑 FastReport，不只是代码里引用单元那么简单。Android 打包时如果报错找不到 frx 资源，要去 Deployment Manager 里检查资源文件是否添加。中文字体文件，比如从 Windows 拷贝的 msyh.ttf，要添加到 Android 的 assets 目录，并确保 Remote Path 设为 assets/。如果用到条码，检查使用的条码库是否需要在 Android 下额外引入 .so 文件。

这些步骤容易漏，漏了之后表现也很典型：开发机上跑没问题，部署到真机或模拟器就崩溃。我遇到过最诡异的一次是，报表里用了一张本地图片，Windows 上正常，Android 上报“Cannot open file”，最后发现是 Deployment Manager 里没有把图片文件打进去。建议在项目设置里把 Deployment 里的内容逐项对一遍，别图省事。

4.4 尺寸自适应：A4 不是唯一答案

移动端报表经常遇到这个问题。FastReport FMX 里页面尺寸是模板属性，A4、Letter 只是预设，你完全可以新建一个自定义纸张，宽度按屏幕比例设置。我习惯建一个“屏幕宽”纸张，宽度设为屏幕宽度像素，高度按内容长度动态调整。这样平板上预览效果接近原生应用。

还有预览缩放的问题。TfrxPreview 控件在 Android 上支持触摸缩放，但缩放比例如果设置不当，用户双指缩放之后分页预览会乱。建议固定启动缩放比例为“适合宽度”，再允许用户手动缩放，体验最好。这个设置我记得在 TfrxPreview 的 ZoomMode 属性里，可以设成 fzxFitWidth。

5. 与 Delphi 13 生态的配合：从数据到导出的实战组合

5.1 结合 FDMemTable 做报表数据集

很多报表数据不是直接来自数据库，而是内存数组、JSON 解析结果。这时候不用绕道数据库，直接把数据塞进 FDMemTable 就行。TFDMemTable 有个特性：可以 FieldDefs 自动建字段，也可以复用一个查询的字段结构。代码示例：

FDMemTable1.Close; FDMemTable1.FieldDefs.Clear; FDMemTable1.FieldDefs.Add('ID', ftInteger); FDMemTable1.FieldDefs.Add('Name', ftString, 50); FDMemTable1.Open; FDMemTable1.Append; FDMemTable1.FieldByName('ID').AsInteger := 1; FDMemTable1.FieldByName('Name').AsString := 'Delphi 13'; FDMemTable1.Post;

然后把 TfrxDBDataSet1.DataSet 指向 FDMemTable1，报表数据源不用动，模板不用改。这种模式和“先把业务逻辑跑完，最后集中渲染报表”的思路很搭。我在一个 PDA 项目里就是这样用的：扫码拿到数据，处理后塞进 FDMemTable，再生成报表，逻辑清晰，调试也方便。

5.2 与 TCSVDataSet、ODAC 等常用组件的配合

FastReport FMX 的数据接口是 TDataSet 标准接口，理论上任何 TDataSet 子类都能接上。我用过 TCSVDataSet 加载导出的 CSV，再丢给 FastReport 出报表，链路很简单：

CSVDataSet1.FileName := 'report_data.csv'; CSVDataSet1.Open; frxDBDataSet1.DataSet := CSVDataSet1; frxReport1.ShowReport();

这套组合适合从外部系统拿数据的场景，比如客户给的 CSV 导出文件，不用导入数据库，直接出报表。ODAC 组件在 Delphi 7 时代和 FastReport 的 VCL 版配合很多，但在 Delphi 13 FMX 项目中，ODAC 提供 FMX 支持的话也可以这样接。关键是 DataSet 接口不变，FastReport 认的是 DataSet，不是具体组件。

5.3 PDF 导出、水印和加密

业务报表里 PDF 导出最常见的两个需求是水印和加密。FastReport FMX 的 PDFExport 属性里都有。UserPassword 和 OwnerPassword 分别控制打开密码和权限密码。水印可以在报表模板上放一个半透明文本或图片，也可以在 TfrxPDFExport 的水印属性里配置。我实际用的是模板里的半透明文本，因为这样在预览时也能看到效果，导出 PDF 时保持一致。

还有一个容易被忽略的细节：导出 PDF 到微信里打开，建议将编码设为“Unicode”，兼容性比 ANSI 好，中文不会乱码。这个选项在 TfrxPDFExport 的属性面板里，默认值有时候是 ANSI，改成 Unicode 后跨平台分享就稳定了。

5.4 性能优化：大数据量报表该注意什么

先说结论：FastReport FMX 在大数据量下不要用设计器预览模式。几十万条记录直接 ShowReport()，UI 线程会被拖死，用户能看到界面卡成 PPT。我的做法是：

1. 关闭报表实时预览，调用 PrepareReport 时不绑定预览控件。
2. 使用缓存数据，把数据先加载到 FDMemTable，再传给报表，避免报表引擎直接连接数据库查询接口反复取数。
3. 必要的时候用报表脚本，FastReport 支持在报表里写 Pascal 脚本做聚合计算，比在 Delphi 代码里循环高效。
4. 控制每页数据量，模板里设置数据带每页显示 N 行，超过则自动换页，减少单页渲染对象数量。

实测一个三万多行的报表，直接 ShowReport 需要 8 秒，优化后 PrepareReport 控制在 2 秒内，预览只渲染当前页，用户体验完全不一样。

6. 关于版本、许可和后续升级的几点经验

6.1 版本匹配：FastReport 版本和 Delphi 版本必须严格对应

这是反复踩出来的教训。FastReport FMX 的每个版本针对特定 Delphi 版本编译，v2025.2 for Delphi 13 是给 Delphi 13 Florence 用的。如果你用 Delphi 12 Athens，硬装 for Delphi 13 的包，编译期可能过了，但运行期会 BPL 版本不匹配报错。

尤其是从旧版本迁到新 Delphi 时，不能只替换安装包，还要把项目里所有 FastReport 相关 DCU 重新编译一遍。项目搜索路径里如果同时存在旧版和新版目录，编译器会随机选择其中一个，报出非常奇怪的错误，比如“类 TfrxReport 没有默认属性”。这种问题排查半小时都找不到头绪，最后发现是搜索路径顺序问题。所以升级时，先在 IDE 的 Library path 里把旧路径删干净，再添加新路径。

6.2 Retail 授权管理的细节

Retail 授权通常绑定机器或用户。FastReport 的激活方式一般是通过授权文件或者注册号。拿到安装包后，先找到 GetLicense 之类的工具或文档，按照官网步骤激活，不要在开发机上重复激活过多导致授权失效。另一个容易忽略的细节：如果你是团队开发，最好把授权文件放在一个统一的位置，让所有开发机的 IDE 都能读到。否则别人打开你的项目时，FastReport 虽然能编译，但某些功能可能被降级成试用模式，导出 PDF 带水印，这种问题第一反应根本想不到是授权问题。

6.3 升级到新版本之前备份什么

升级 FastReport FMX 之前，建议备份以下内容：

• 现有的 .fr3 模板文件，新版本设计器可以打开旧模板，但反向不一定兼容，改坏了就回不去了。
• 项目里的 FastReport 相关单元引用，搜索 frx 关键字，记录所有使用位置。
• IDE 的组件包配置，记录当前已经安装的 FastReport 包名和版本号，出问题回滚时有用。

我吃过一次亏，升级之前没备份模板，新版设计器打开旧模板后保存，结果一个字段的表达式被自动改掉了，数据错位查了一下午。从那以后，凡是涉及报表的升级，我第一件事就是备份 .fr3 目录。

6.4 从个人经验谈报表控件选型

最后说点大实话。如果在 Delphi 13 FMX 项目里要用报表，可选的不多：FastReport FMX 是最成熟的选择，另一个是 Report Builder 的 FMX 版，但流行度和教程都少得多。如果你刚进项目，建议直接押 FastReport，因为资料多、案例多、遇到问题能搜到答案。

如果你只是在 VCL 项目里做报表，FastReport VCL 版也很好，但别把 FMX 版的源码和 VCL 版混装，两个版本在同一个 IDE 里并存容易冲突。需要在程序里动态判断当前平台时，用 {$IFDEF MSWINDOWS} 这类条件编译区分，别把两个版本的单元都写在 uses 里。

至少在我们这个项目里，报表模块从最开始的手写 Canvas 一路折腾到 FastReport FMX，后面基本就顺了。如果你也在 Delphi 13 Florence 上用 FMX 做跨平台报表，可以按这个顺序走：先装好环境，再跑 Demo，接着拿一个简单报表练手，最后再上移动端。报表这东西，模板设计阶段多花点时间，后面能帮你省下一大堆熬夜的功夫。

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