FastReport 使用教程：从入门到精通

第一部分：FastReport 基础入门

什么是 FastReport？

FastReport 是一个功能强大、灵活且易于使用的报表生成器，它支持 .NET (WinForms, ASP.NET, MAUI, Blazor)、VCL (Delphi/C++ Builder)、Java 和 COM 等多种平台，你可以用它来创建各种复杂的报表，如列表、分组、主从、矩阵、条形码等。

核心优势：

• 跨平台：支持多种开发框架。
• 灵活性高：提供可视化设计器,可以像画图一样设计报表布局。
• 功能全面：支持几乎所有常见的报表元素和高级功能。
• 性能优秀：速度快,资源占用低。

安装 FastReport

• NuGet 方式（推荐）：在 Visual Studio 中，通过 NuGet 包管理器搜索 FastReport 并安装你需要的版本（如 FastReport.OpenSource 或商业版）。
• 官网下载：访问 FastReport 官网 (https://www.fast-report.com/) 下载安装包，按照向导进行安装，安装后会在 Visual Studio 工具箱中添加 FastReport 选项卡。

核心概念

在开始设计报表之前，必须理解 FastReport 的几个核心概念：

• 报表对象：报表的基本构成单元，Text (文本)、Picture (图片)、Table (表格)、Barcode (条形码) 等,你可以从工具箱中拖拽这些对象到报表设计器中。
• 数据源：报表的数据来源，最常见的是 DataSet，也可以是 ObjectList、JSON、XML 等,数据源是连接你的应用程序数据和报表的桥梁。
• 数据带：报表中用于显示数据的主要区域，FastReport 提供了多种数据带，它们垂直堆叠，从上到下依次执行：
  • Report Title (报表标题)：整个报表的最顶部,只出现一次。
  • Page Header (页眉)：每一页的顶部,通常用于显示列标题。
  • Column Header (列标题)：用于表格列的标题，与 Data 带配合使用。
  • Data (数据)：最重要的带，它会遍历数据源中的每一行数据，为每一行创建一个实例，表格中的每一行、列表中的每一项都放在这里。
  • Column Footer (列脚)：通常用于对列进行小计。
  • Page Footer (页脚)：每一页的底部，通常用于显示页码、日期等。
  • Report Summary (报表总结)：整个报表的最底部，只出现一次，通常用于总计、平均值等最终汇总。
  • Group Header/Footer (分组头/脚)：用于数据分组，当分组字段变化时，会打印一次头/脚。

简单理解流程：报表引擎从 Data 带开始，读取数据源的第一行，填充 Data 带中的所有对象，然后打印出来，接着读取第二行，再次填充并打印... 直到数据源所有行处理完毕。Header 和 Footer 等带则根据其规则（如每页、每组）在特定位置打印。

第二部分：创建第一个报表（详细步骤）

假设我们要为 Customers 表创建一个简单的客户列表报表。

步骤 1：准备数据源

1. 在你的项目中，创建一个 DataSet，在解决方案资源管理器中，右键项目 -> 添加 -> 新建项 -> 选择“数据集”。
2. 打开 .xsd 文件，从服务器资源管理器中拖拽你的 Customers 表（或其他数据表）到设计器中。
3. 保存后，你就得到了一个强类型的 DataSet（DataSet1）。

步骤 2：创建报表文件

1. 在项目中，右键添加 -> 新建项 -> 选择 "FastReport Report"。
2. 这会打开报表设计器,并自动创建一个空的报表结构。

步骤 3：绑定数据源

1. 在设计器左侧的 "Data"（数据）窗口中，点击 "Report" -> "Data" -> "Add Data Source..."。
2. 选择 "DataSet"，然后点击 "..." 按钮，选择你刚刚创建的 DataSet1。
3. 点击 "OK"，在 "Data" 窗口中，你应该能看到你的 Customers 表及其所有字段（如 CustomerID, CompanyName, ContactName 等）。

步骤 4：设计报表布局

1. 拖放数据带：从 "Report" 窗口中，将 Page Header 和 Data 带拖到设计画布上。Data 带没有自动出现,可以手动添加。
2. 设计页眉：
   • 从工具箱中拖拽一个 Text 对象到 Page Header 带。
   • 双击该 Text 对象，输入 "客户列表"。
   • 再拖三个 Text 对象到 Page Header 带，分别输入 "客户ID", "公司名称", "联系人姓名"。
3. 设计数据带：
   • 从工具箱中拖三个 Text 对象到 Data 带。
   • 关键一步：选中 Data 带中的第一个 Text 对象，然后在 "Data" 窗口中找到 Customers.CustomerID 字段，双击它，你会发现 Text 对象的 Text 属性自动变成了 [Customers."CustomerID"]，这个方括号 [] 是 FastReport 的表达式语法,表示显示该字段的值。
   • 用同样的方法，将另外两个 Text 对象分别绑定到 CompanyName 和 ContactName 字段。
4. 调整样式：你可以像在 Word 或设计工具中一样，选中对象，设置其字体、颜色、边框、对齐方式等。

步骤 5：预览报表

1. 在设计器工具栏中，点击 "Preview"（预览）按钮。
2. 一个新的窗口会弹出，显示你设计的报表，如果数据源中有数据,你应该能看到完整的客户列表。

步骤 6：在代码中调用报表

在你的窗体或页面代码中（Form1.cs）,添加以下代码来显示报表：

using FastReport;
using FastReport.Data;
using System;
using System.Data;
using System.Windows.Forms;
public partial class Form1 : Form
{
    public Form1()
    {
        InitializeComponent();
    }
    private void btnShowReport_Click(object sender, EventArgs e)
    {
        // 1. 创建报表实例
        Report report = new Report();
        // 2. 加载报表文件 (.frx)
        report.Load("YourReportName.frx"); // 替换成你的报表文件名
        // 3. (可选但推荐) 注册数据源
        // 如果你的数据是动态加载的，需要在这里注册
        DataSet1 dataSet1 = new DataSet1();
        // 假设你通过某种方式填充了 dataSet1.Customers
        // FillDataSet(dataSet1); 
        // 将DataSet注册到报表中
        report.RegisterData(dataSet1, "Customers");
        // 4. 预览报表
        report.Prepare(); // 准备报表
        report.Show();    // 显示预览窗口
    }
}

第三部分：常用功能详解

表达式与脚本

FastReport 的强大之处在于其表达式和脚本功能。

• 表达式：任何可以输入文本的地方，都可以使用表达式，表达式用 [...] 括起来。
  • 字段引用：[Customers."CompanyName"]
  • 算术运算：[UnitPrice] * [Quantity]
  • 函数调用：[Date.Now] (当前日期), [FormatDateTime(Date.Now, "yyyy-MM-dd")]
  • 条件表达式：[Iif([IsVIP] = True, "VIP客户", "普通客户")]
• 脚本：在报表设计器中，你可以编写 C# 或 VB.NET 脚本来实现复杂逻辑。
  • 打开 "Script" (脚本) 选项卡。
  • 你可以为报表事件（如 StartReport, BeforePrint）编写代码。
  • 示例：在 Data 带的 BeforePrint 事件中，可以动态改变某个文本的颜色：

    // 在 Customers_Data_BeforePrint 事件中
    if (this.GetColumnValue("IsVIP") == true)
    {
        TextObject txt = (TextObject)this.FindObject("txtContactName");
        txt.Color = System.Drawing.Color.Red;
    }

数据分组

分组是报表的常用功能,例如按城市对客户进行分组。

1. 在 "Data" 窗口中，右键点击你的数据源（如 Customers），选择 "Create Group"。
2. 选择要分组的字段（如 City），点击 "OK"。
3. 报表会自动添加 Group Header 和 Group Footer 两个带。
4. 将 City 字段拖到 Group Header 带中,作为分组的标题。
5. 在 Group Footer 带中，可以添加一个 Function 对象（来自工具箱），选择 Count 函数来统计每个城市的客户数量。

矩阵报表

矩阵报表（交叉表）用于显示行和列的汇总数据。

1. 在报表设计器中，右键点击报表，选择 "Add Matrix"。
2. 矩阵会自动创建四个区域：Corner (角), Rows (行), Columns (列), Data (数据)。
3. 从 "Data" 窗口中，将字段拖放到相应区域：
   • 行字段（如 ProductName） -> Rows 区域。
   • 列字段（如 Year） -> Columns 区域。
   • 汇总字段（如 SalesAmount） -> Data 区域。
4. 双击 Data 区域的 Function 对象，可以设置汇总方式（求和、计数、平均值等）。

参数

参数用于在运行时向报表传递值,例如选择日期范围。

1. 在 "Data" 窗口中，右键点击 "Parameters"，选择 "Add"。
2. 设置参数的名称（如 StartDate）和类型（如 System.DateTime）。
3. 在报表中，你可以像使用字段一样使用参数：["StartDate"]。
4. 在代码中传递参数：

   report.SetParameterValue("StartDate", dateTimePicker1.Value);
   report.Show();

过滤数据

你可以在报表加载后,通过代码对数据源进行过滤。

// 假设数据源是 DataSet
DataSet1 dataSet1 = (DataSet1)report.GetDataSource("Customers").DataSet;
dataSet1.Customers.DefaultView.RowFilter = "Country = 'Mexico'";
// 重新准备报表
report.Prepare();
report.Show();

第四部分：最佳实践与技巧

1. 使用变量：对于需要重复使用的复杂表达式，可以定义变量，在 "Variables" 窗口中添加变量，然后在表达式中使用 [VariableName]。
2. 使用图片：可以通过表达式动态加载图片，例如显示客户头像：[Picture.Load("C:\Images\" + [CustomerID] + ".png")]。
3. 使用条形码和二维码：从工具箱中拖拽 Barcode 或 QRCode 对象,绑定到相应的字段即可。
4. 子报表：一个报表中可以嵌入另一个报表，这在处理主从关系（如订单和订单明细）时非常有用，只需将 Subreport 对象拖到主报表的 Data 带中，然后设置其 ReportSource 属性即可。
5. 报表样式：可以定义样式（字体、颜色、边框等），然后应用到多个对象上,以保持报表外观的一致性。
6. 导出功能：FastReport 支持将报表导出为多种格式（PDF, Excel, Word, HTML, Image 等），在预览窗口中，点击 "Export" 按钮即可，也可以通过代码控制导出：

   report.Prepare();
   report.Export(new PDFExport(), "C:\Reports\MyReport.pdf");

第五部分：常见问题与解决

• Q: 报表中没有显示数据？

  • A: 检查数据源是否正确注册到报表中，检查 Data 带是否正确添加，检查数据是否真的加载到了 DataSet 中，在 Data 带的 BeforePrint 事件中打断点,看代码是否被执行。

• Q: 如何在页脚显示总页数和当前页码？

  • A: 在 Page Footer 带中，添加两个 Text 对象，一个输入 Page [Page#] of [Total#]，FastReport 会自动替换 [Page#] 和 [Total#]。

• Q: 如何根据条件隐藏整个行？

  • A: 选中 Data 带中的所有对象（或者用一个 Band 对象将它们包裹起来），在属性窗口中找到 Printable 属性，将其表达式设置为：[Iif([IsVisible] = True, True, False)]。

• Q: 如何实现分页符？

  • A: 在脚本中，调用 engine.NewPage() 方法，在 Group Header 的 AfterPrint 事件中,在每个分组结束后换页。

希望这份详尽的教程能帮助你完全掌握 FastReport！祝你使用愉快！