FastReport ReportBuilder:用流式 API 无设计器构建 FastReport 报表
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 Roman14pt 加粗(见 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:分组带
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 引擎的关键。其构建流程如下:
- 注册数据源:
new Report()后调用report.RegisterData(reportBuilder._data, name),其中name = typeof(T).Name——数据源名就是实体类的类名(例如Person),随后GetDataSource(name).Enabled = true启用该数据源。这也解释了为什么所有表达式都形如[Person.FirstName]; - 页面与标题带:创建
ReportPage,ReportTitleBand高度固定为 1cm;标题文本框TextObject的边界为(5cm, 0, 10cm, 1cm),即从页面左侧 5cm 起、宽 10cm 的居中区域; - 数据带:创建
DataBand并绑定数据源,行高固定 0.5cm; - 分组带:若
Condition已配置,则创建GroupHeaderBand(高 0.5cm),其Condition取Expression模板格式化结果,否则为"[类名.属性名]";SortOrder原样写入。若TextVisible为真,还会在分组带内加一个 2cm 宽、Tahoma 10pt 加粗的文本对象,显示分组条件值; - 表头带:若
DataHeader.Visible,创建DataHeaderBand(高 0.5cm)并为每列生成一个带四边框线(BorderLines.All)的表头文本对象; - 列布局算法:可用宽度
pageWidth = PaperWidth - LeftMargin - RightMargin,cellWidth = pageWidth / 100。每列实际宽度为Width/10个 cell(即Width个百分比单位);Width == 0的列均分剩余百分比——代码中remainWidth = remainSize / (remainColumn * 10),其中remainSize是 100 减去所有已指定宽度之和; - 数据单元格:每列在
DataBand中生成带四边框线的文本对象,高度 0.5cm;文本为[类名.属性名]或表达式模板格式化结果;若配置了Format,则包装为CustomFormat赋给text.Format; - 收尾:调用
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 版本的兼容性。
- 版式固定——标题带 1cm、表头/数据行各 0.5cm、单
七、延伸阅读路径
- README.md:原始文档与门面示例;
- Builders/ReportBuilder.cs、Builders/DataBuilder.cs、Builders/GroupHeaderBuilder.cs、Builders/DataHeaderBuilder.cs、Builders/ReportTitleBuilder.cs:五个构建器的全部 API;
- Definitions/:各配置类及默认值;
- ReportHelper.cs:
Prepare()的 Band 构建全流程; - FastReport.Base/Report.cs:
RegisterData等被调用的核心引擎 API(第 2434-2472 行区域)。