開源組件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章「演示」）

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

生成導出報表：