开源组件ExcelReport 1.5.2 使用手册

ExcelReport是一款基于NPOI开发的报表引擎组件。它基于关注点分离的理念，将数据与样式、格式分离。让模板承载样式、格式等NPOI不怎么擅长且实现繁琐的信息，结合NPOI对数据的处理的优点将Excel报表的生成化繁为简。同时，对报表组成的基本元素进行了抽象，进一步简化了Excel报表的生成过程。

官方站点

NuGet：https://www.nuget.org/packages/ExcelReport

GitHub：https://github.com/hanzhaoxin/ExcelReport

cnblogs：http://www.cnblogs.com/hanzhaoxin/tag/ExcelReport /

QQ Group：116476496 

团队介绍

Jensen

来自于中国深圳，是这个项目的发起人和开发人员，2014年11月开始了ExcelReport的开发，负责ExcelReport的开发、测试和bug修复。

个人博客地址：http:// hanzhaoxin.cnblogs.com

许可证说明

ExcelReport采用的是MIT许可，这意味着它可以被用于任何商业或非商业项目，你不用担心因为使用它而必须开放你自己的源代码，且可借助ExcelReport的影响力推广你的产品。

当然作为一个开源许可证，肯定也是有一些义务。例如：在软件和软件的所有副本中都必须包含以上版权声明和本许可声明。

完整的MIT许可证请见：http://mit-license.org/

版本升级说明：

如果您项目中使用了ExcelReport，Bug修复和功能扩充的升级版本请放心升级，这类升级不能影响您现有的项目。如果架构修改版本信息发生了变化，请谨慎升级，这类升级有可能影响您现有的项目。

为什么要用ExcelReport？

回答这个问题前，我们先看看Tony Qu是怎么回答为什么要用NPOI的？

1）你不需要在服务器上安装微软的 Office，可以避免版权问题。

2）NPOI使用起来比 Office PIA 的 API 更加方便，更人性化。

3）你不用去花大力气维护 NPOI，NPOI Team 会不断更新、改善 NPOI，绝对省成本。

4）很多事情是 html 和cvs法做不到的，比如说公式计算[Cell C1]=A1+B1*A2单元格

高级样式（如文本旋转、对齐、宽度）等，其中公式计算可以适当减轻服务器端的计算压力

回到我们的问题，为什么要用ExcelReport呢？

1） 复杂的事情简单了，不可能的事情可行了。

2） 你不需要了解NPOI大量的API，你不需要用.NET语言写蹩脚的Java的语法。

3） 套用Tony兄的描述，你不用去花大力气维护ExcelReport，ExcelReport Team会不断更新、改善ExcelReport，绝对省成本。

目录

1报表元素与元素格式化器

2演示：使用ExcelReport生成报表

3格式化器示例

3.1局部格式化器

3.2单元格格式化器

3.3表格格式化器

3.4重复单元格式化器

4多Sheet报表生成

1报表元素与元素格式化器

在开始示例之前，我们用一章的篇幅介绍ExcelReport是如何将报表的内容抽象为元素的？

又是如何为元素填充数据的？为了说明第一个问题，我们从一个现有的报表开始。

如下报表有两个Sheet：Sheet1名为“工资表”Sheet2名为“工资条”，其截图如下所示。

我们先把数据部用蓝色框线标出来。

名正才能言顺，先说说ExcelReport中报表元素的概念：

元素：填充到报表模板中的数据源对象，我们称之为元素。

局部元素：填充到报表模板中的数据源对象是一个单元格内容的一部分，我们称这样的数据源对象为局部元素。

单元格元素：填充到报表模板中的数据源对象是一个单元格的内容，我们称这样的数据源对象为单元格元素。

表格元素：填充到报表模板中的数据源是某对象的集合，该对象是一行中多个单元格的内容集合，我们称这样的数据源集合为表格元素。

重复单元元素：填充到报表模板中的数据源是某对象的集合，该对象是多行中多个单元格的内容集合，我们称这样的数据源集合为重复单元元素。

【表格元素与重复单元元素数据源以集合出现。为复元素。】

【对应的，局部元素和单元格元素称之为单元素。】

有了定义，我们让元素们各就各位。

那么，ExcelReport又是如何为元素填充数据的？

话说元素格式化器为此而生。

报表元素	元素格式化器
局部元素	PartFormatter
单元格元素	CellFormatter
表格元素	TableFormatter
重复单元元素	RepeaterFormatter

【元素格式化器的作用是格式化元素将其填充到报表模板。】

2演示：使用ExcelReport生成报表

目标报表，生成上章分析的”工资表-工资条”报表。

第一步：设计模板

【模板中参数格式：$[ParameterName]】

第二步：由模板生成模板填充规则文件

1） 打开模板填充规则文件生成工具

2） 将设计好的模板拖入Excel模板文件选择框

3） 点击“生成模板规则文件（.XML）”按钮，生成规则文件。

第三步：填充模板，生成报表【项目中要添加对ExcelReport及NPOI（2.0以上）的引用】

生成导出报表：

【注：演示示例“生成工资表-工资条报表”源码见解决方案：ExcelReportExamples】

3格式化器示例

通过上一章的示例，我们了解了ExcelReport生成报表的步骤，也用到了各种格式化器。在本章，我们将对格式化器逐一展开讲解，以更详细的了解它们。

3.1局部格式化器

局部格式化器用于格式化填充一个单元格内容的一部分。填充数据类型为string。

构成函数：

参数	描述
cellPoint	参数所在单元格位置
parameterName	参数名
value	要格式化填充的值

示例：（局部格式化器示例）

第一步：设计模板

第二步：由模板生成模板填充规则文件

第三步：填充模板，生成报表

生成导出报表：

3.2单元格格式化器

单元格格式化器用于格式化填充一个单元格。填充数据类型为object，详见下表：

填充数据类型	Excel中对应的数据类型	可视化设置项
String	String
DateTime	DateTime
Boolean	Boolean
Int16 Int32 Int64 Byte Single Double UInt16 UInt32 UInt64	Double
Byte[]	Image

构成函数：

参数	描述
cellPoint	参数所在单元格位置
value	要格式化填充的值

示例：（单元格格式化器示例）

第一步：设计模板

第二步：由模板生成模板填充规则文件（略，详参见第2章“演示”）

第三步：填充模板，生成报表

生成导出报表：

3.3表格格式化器

表格格式化器用于格式化填充一个表格。填充数据类型为IEnumerable<TSource>。

构造函数：

参数	描述
templateRowIndex	模板行行标
dataSource	要格式化填充的数据
columnInfos	列信息集合

TableColumnInfo构造函数：

参数	描述
columnIndex	列标
dgSetValue	Func<TSource, object>类型的委托对象（返回值Object，可参照第二节填充数据类型与Excel中数据类型对应表。）

示例：（表格格式化器示例）

第一步：设计模板

第二步：由模板生成模板填充规则文件（略，详参见第2章“演示”）

第三步：填充模板，生成报表

生成导出报表：

提问回复：【关于TableFormatter有以下知识点，多次被提问，这里做出统一回答。】

问题一：TableFormatter的数据源可以是DataTable吗？

答：你可以这样写：

问题二：我的实体类中没有实现外链，在实体对象中有一个ID属性，我想导出的内容是ID对应的Name，这怎么办？

答：和示例中的“性别”没什么区别吧。好吧，贴行代码：

3.4重复单元格式化器

重复单元格式化器用于格式化填充一个重复单元元素。填充数据类型为IEnumerable<TSource>。

构造函数：

参数	描述
startTagCell	重复单元（开始）标识单元格
endTagCell	重复单元（结束）标识单元格
dataSource	要格式化填充的数据
cellInfos	重复单元包含的单元格信息集合

RepeaterCellInfo构造函数：

参数	描述
cellPoint	单元格坐标
dgSetValue	Func<TSource, object>类型的委托对象（返回值Object，可参照第二节填充数据类型与Excel中数据类型对应表。）

示例：（重复单元格式化器示例）

第一步：设计模板

根据需求，隐藏重复单元标识行。

第二步：由模板生成模板填充规则文件（略，详参见第2章“演示”）

第三步：填充模板，生成报表

生成导出报表：

4多Sheet报表生成

到目前为止，我们所有导出都直接使用的是：ExportHelper类中的静态方法。其实在ExcelReport组件的设计中Export类便是终点了，ExportHelper类正如它的名字只是为了方便操作提供的助手类而已。

【哦，它还是部分类，你可以根据需求扩展。】

回到本章的主题，我们要谈的是多Sheet报表的生成。什么？这和前边啰嗦的那些有什么关系？好吧，其实关系也不大，我只是想说关注报表的生成，你看Export类就对了。

参数	描述
templateFile	模板文件路径
containers	Sheet格式化容器的数组【数组中的每个元素对应一个Sheet】

示例：（多Sheet报表生成示例）

第一步：设计模板

第二步：由模板生成模板填充规则文件（略，详参见第2章“演示”）

第三步：填充模板，生成报表

生成导出报表：