开源组件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章“演示”）

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

生成导出报表：