FastReport ReportBuilder:用流式 API 无设计器构建 FastReport 报表

原创2026-10-14 14:07:541,663 阅读
文章标签:后端模板引擎数据可视化UI组件

FastReport ReportBuilder:用流式 API 无设计器构建 FastReport 报表

本文以仓库中 Extras/OpenSource/FastReport.ReportBuilder 的 README 为主体,详解 FastReport 官方开源仓库附带的一个轻量级辅助包 FastReport.ReportBuilder:它通过一组链式(Fluent)API,让你在不打开可视化设计器、不手写 .frx XML 的情况下,直接用 C# 代码构建包含标题、分组、表头和列定义的标准报表。读完后,你能掌握它的完整用法、每个构建器的参数与默认值,并理解 Prepare() 背后如何把 fluent 配置翻译成 FastReport 的分页带(Band)结构。

一、定位与获取方式

FastReport.ReportBuilder 的定位一句话概括:Building a FastReport without designer easy way!(用简单的方式构建 FastReport,无需设计器)。它位于仓库的 Extras/OpenSource/FastReport.ReportBuilder/ 目录下,包含一个核心库工程和一个单元测试工程,由作者 Emrah KONDUR 贡献。

从 FastReport.ReportBuilder.csproj 可以确认其技术形态:

  • 目标框架为 netstandard2.0,因此可在 .NET Framework 与 .NET Core/.NET 5+ 项目中使用;
  • 依赖 NuGet 包 FastReport.OpenSource(版本由 UsedPackages.version 中的 FROSVersion 决定,当前仓库中为 2025.2.0)和 System.ComponentModel.Annotations 4.1.0(后者用于读取实体上的 [Display]/[DisplayFormat] 特性);
  • 包标识为 FastReport.ReportBuilder,仓库内声明的包版本为 2021.1.0,构建时自动打包(GeneratePackageOnBuild=true)。

按 README 的说明,通过包管理器控制台安装:

PM> Install-Package FastReport.ReportBuilder

二、完整用法示例(README 核心示例)

README 给出的完整示例是整个包的门面 API 的最佳展示——从数据源到标题、分组、表头、列定义一气呵成,最后调用扩展方法 Prepare() 得到可直接导出的 Report 对象:

var builder = new ReportBuilder();

var report = builder.Report(list)
.ReportTitle(title => title
    .Text("Person Report - [MonthName(Month([Date]))]")
    .HorzAlign(HorzAlign.Center)
)
.GroupHeader(header => header
    .Condition(con => con.LastName)
    .SortOrder(SortOrder.Descending)
    .Expression("Substring({0},0,1)")
)
.DataHeader(header => header
    .TextColor(Color.Red)
    .Font("Helvetica")
)
.Data(data =>
{
    data.Column(col => col.FirstName).Width(20);
    data.Column(col => col.LastName).Expression("UpperCase({0})");
    data.Column(col => col.BirthDate).Format("MM/dd/yyyy");
    data.Column(col => col.IsActive).Title("Active").Width(10);
    data.Column(col => col.Level).HorzAlign(HorzAlign.Center);
})
.Prepare();

这个示例覆盖了 fluent API 的全部主要入口:

  • Report(list):注册业务对象数据源,list 是 IEnumerable<T>,T 必须为引用类型(where T : class);
  • ReportTitle(...):配置报表标题带(ReportTitleBand);
  • GroupHeader(...):按某个属性分组并配置排序、自定义分组条件表达式;
  • DataHeader(...):配置数据表头带(DataHeaderBand)的字体、颜色;
  • Data(...):逐列声明数据列,支持列宽百分比、表达式、格式、对齐;
  • Prepare():终结方法,构建并返回 Report 对象。

每个方法都返回 ReportBuilder<T> 或对应的子构建器自身,因此可以任意顺序、任意嵌套地链式调用;ReportTitle、GroupHeader、DataHeader、Data 均可省略,未配置的部分按各自定义类的默认值处理。

三、流式 API 逐项解析

3.1 报告级配置:Font / VertAlign / HorzAlign

ReportBuilder.cs 中定义了泛型构建器 ReportBuilder<T>,除四个子构建器入口外,还直接提供三个报告级方法:

方法 说明 默认值(见 ReportDefinition.cs)
Font(familyName) / Font(familyName, emSize) / Font(familyName, emSize, style) 设置报告整体字体 Times New Roman,10pt,Regular
VertAlign(VertAlign) 报告内容垂直对齐(Top/Bottom/Center) 未设置(default)
HorzAlign(HorzAlign) 报告内容水平对齐(Left/Right/Center/Justify) 未设置(default)

报告级对齐值是各列的兜底:数据列若未单独指定 VertAlign/HorzAlign,Prepare() 时会回退到报告级对齐(见 ReportHelper.cs 第 136-137 行的取值逻辑)。

3.2 ReportTitle:标题带

ReportTitleBuilder.cs 提供以下方法:

  • Text(string):标题文本。文本支持 FastReport 表达式,README 示例中的 [MonthName(Month([Date]))] 会在渲染时解析为当月月份名称。调用 Text 后标题带自动置为可见;
  • Font(...):三个重载。与数据表头不同,标题的字体默认是 Times New Roman 14pt 加粗(见 ReportTitleDefinition.cs 第 8 行),因此 Font("Arial") 这类单参调用会得到 14pt Bold 效果;
  • Visible(bool) / TextColor(Color) / FillColor(Color):显隐与颜色。TextColor 默认黑色,FillColor 默认为透明(Color.Empty);
  • VertAlign / HorzAlign:标题文本对齐。注意 Prepare() 内部把标题文本框的 HorzAlign 固定为 Center(ReportHelper.cs 第 61 行),而表头列的对齐则读取标题定义上的对齐值作为兜底。

3.3 GroupHeader:分组带

GroupHeaderBuilder.cs 的方法:

  • Condition<TProp>(Expression<Func<T, TProp>> property):以 lambda 表达式指定分组属性(如 con => con.LastName),通过反射解析出属性名,并将分组带置为可见。这是分组的前提——不调用 Condition 则不生成 GroupHeaderBand;
  • SortOrder(SortOrder):分组排序,可选 None/Ascending/Descending,默认 Ascending(GroupHeaderDefinition.cs 第 7 行);
  • Expression(string):用模板表达式覆盖分组条件,占位符 {0} 会被替换为 "[数据源名.属性名]"。README 示例中 "Substring({0},0,1)" 即按姓氏首字母分组;
  • TextVisible(bool):是否在分组带内渲染分组值文本,默认 true(第 9 行)。

3.4 DataHeader:数据表头带

DataHeaderBuilder.cs 提供 Font(...)(三个重载,默认 Times New Roman 10pt)、Visible(bool)(默认 true)、TextColor(Color)(默认黑色)、FillColor(Color)(默认浅蓝 Color.FromArgb(235, 243, 251),见 DataHeaderDefinition.cs 第 10 行)。

3.5 Data:列定义

DataBuilder.cs 中每次 Column(...) 开启一个列上下文,后续链式调用的 Title/Width/Format/Expression/VertAlign/HorzAlign 都作用于“当前列”。各方法含义如下(定义载体见 DataDefinition.cs):

  • Column<TProp>(Expression<Func<T, TProp>> property):以表达式指定属性。属性名通过 GenericHelpers.cs 从 MemberExpression 解析(兼容 Convert 一元表达式场景);列标题优先取实体属性上的 [Display(Name = ...)] 特性,缺省为属性名;列格式则优先取 [DisplayFormat(DataFormatString = ...)];
  • Title(string):显式指定表头标题,覆盖特性值;
  • Width(uint):列宽按百分比计(占页面可用宽度的比例),0 表示参与剩余空间的均分;
  • Format(string):列显示格式,如 "MM/dd/yyyy"、"P"(百分号)、货币/数字格式等;
  • Expression(string):用表达式模板渲染单元格,{0} 被替换为 "[数据源名.属性名]",例如 "UpperCase({0})";
  • VertAlign / HorzAlign:列级对齐,覆盖报告级对齐。

四、Prepare() 内部实现:从 fluent 配置到 Band 结构

Prepare() 是定义在 ReportHelper.cs 中的扩展方法(ReportBuilderExtension.Prepare<T>),它是理解整个包如何落地到 FastReport 引擎的关键。其构建流程如下:

  1. 注册数据源:new Report() 后调用 report.RegisterData(reportBuilder._data, name),其中 name = typeof(T).Name——数据源名就是实体类的类名(例如 Person),随后 GetDataSource(name).Enabled = true 启用该数据源。这也解释了为什么所有表达式都形如 [Person.FirstName];
  2. 页面与标题带:创建 ReportPage,ReportTitleBand 高度固定为 1cm;标题文本框 TextObject 的边界为 (5cm, 0, 10cm, 1cm),即从页面左侧 5cm 起、宽 10cm 的居中区域;
  3. 数据带:创建 DataBand 并绑定数据源,行高固定 0.5cm;
  4. 分组带:若 Condition 已配置,则创建 GroupHeaderBand(高 0.5cm),其 Condition 取 Expression 模板格式化结果,否则为 "[类名.属性名]";SortOrder 原样写入。若 TextVisible 为真,还会在分组带内加一个 2cm 宽、Tahoma 10pt 加粗的文本对象,显示分组条件值;
  5. 表头带:若 DataHeader.Visible,创建 DataHeaderBand(高 0.5cm)并为每列生成一个带四边框线(BorderLines.All)的表头文本对象;
  6. 列布局算法:可用宽度 pageWidth = PaperWidth - LeftMargin - RightMargin,cellWidth = pageWidth / 100。每列实际宽度为 Width/10 个 cell(即 Width 个百分比单位);Width == 0 的列均分剩余百分比——代码中 remainWidth = remainSize / (remainColumn * 10),其中 remainSize 是 100 减去所有已指定宽度之和;
  7. 数据单元格:每列在 DataBand 中生成带四边框线的文本对象,高度 0.5cm;文本为 [类名.属性名] 或表达式模板格式化结果;若配置了 Format,则包装为 CustomFormat 赋给 text.Format;
  8. 收尾:调用 report.Prepare()(FastReport 核心 API)完成报表准备,返回 Report 实例,可直接交给任意导出器(PDF、Excel 等)。

从源码结构看,这个包刻意保持了一个非常固定的版式模型:单页面、标题 1cm、表头与数据行各 0.5cm、列宽百分比制、单一 DataBand。它没有暴露页脚、汇总带或多页面配置入口(GroupHeaderDefinition 中的 Height 字段与 _groupFooter 字段在当前 Prepare() 流程中并未参与渲染,可以推断为预留或未完成的扩展点)。

五、单元测试:可运行的完整验证

ReportTest.cs 中的五个测试方法(配合 Person.cs 示例实体)验证了 README 示例的每一种能力,且都以 PDFSimpleExport 导出 Employees.pdf 作为人工验证手段(测试注释明确说明“无断言,检查 bin\Debug\ 下生成的 PDF”):

  • export_basic_report_pdf:基础列输出,并注释了“FirstName 列标题来自数据注解 [Display(Name = "First Name")]”;
  • export_report_resized_columns_by_percentage_pdf:百分比列宽,Width(25)/Width(20) 与其余三列均分剩余 55%;
  • export_report_using_column_format_pdf:Format("MM/dd/yyyy") 显式格式,与 [DisplayFormat(DataFormatString = "P")] 特性格式并存;
  • export_report_using_expression_pdf:列级表达式 UpperCase({0}) 与标题表达式 [MonthName(Month([Date]))];
  • export_group_report_pdf:README 同款完整示例——分组、排序、分组表达式、表头配色、列宽/格式/对齐全量组合。

Person 实体(4 条示例数据)同时演示了注解驱动的特性:[Display] 决定缺省列标题、[DisplayFormat] 决定缺省列格式,这与 DataBuilder.cs 第 38-39 行读取 GetCustomAttribute<DisplayAttribute>/GetCustomAttribute<DisplayFormatAttribute> 的逻辑一一对应。

六、适用场景与使用限制

基于仓库代码可以确认的适用边界如下:

  • 适用:服务端生成结构化列表/明细类报表(员工清单、订单明细、按字段分组的统计列表),配合 FastReport.OpenSource 的任意导出器使用;netstandard2.0 使其跨 .NET 平台可用;
  • 限制:
    • 版式固定——标题带 1cm、表头/数据行各 0.5cm、单 DataBand,不支持页眉页脚、汇总带、多页布局或子报表;
    • 仅支持单一业务对象集合作为数据源,数据源名即实体类名,列必须能映射为实体属性;
    • 表达式模板仅支持 string.Format 风格的 {0} 占位;
    • 仓库内包版本停留在 2021.1.0,而 FastReport.OpenSource 引用已随仓库升至 2025.2.0(见 UsedPackages.version),在正式项目使用前建议核对你安装的 NuGet 版本与当前 FastReport.OpenSource 版本的兼容性。

七、延伸阅读路径

登录后查看全文
FastReport