因为大部分用户没有积分,所以,我帮作者免费供应下。如果损害本文作者利益,请及时通知我,我将及时删除此文档。
NOPI使用手册
目录
2. 使用NPOI生成xls文件
2.1 创建基本内容
2.1.2 创建DocumentSummaryInformation和SummaryInformation
2.2 单元格操作
2.3 使用Excel公式
2.4 创建图形
2.6 高级功能
3. 项目实践
本章将介绍NPOI的一些基本信息,包括以下几个部分
- 什么是NPOI
- 版权说明
- 相关资源
- 团队介绍
- 未来展望
- 各Assembly的作用
1.1 什么是NPOI
NPOI,顾名思义,就是POI的.NET版本。那POI又是什么呢?POI是一套用Java写成的库,能够帮助开发者在没有安装微软Office的情况下读写Office 97-2003的文件,支持的文件格式包括xls, doc, ppt等。在本文发布时,POI的最新版本是3.5 beta 6。
NPOI 1.x是基于POI 3.x版本开发的,与poi 3.2对应的版本是NPOI 1.2,目前最新发布的版本是1.2.1,在该版本中仅支持读写Excel文件和Drawing格式,其他文件格式将在以后的版本中得到支持。
1.2 版权说明
NPOI采用的是Apache 2.0许可证(poi也是采用这个许可证),这意味着它可以被用于任何商业或非商业项目,你不用担心因为使用它而必须开放你自己的源代码,所以它对于很多从事业务系统开发的公司来说绝对是很不错的选择。
当然作为一个开源许可证,肯定也是有一些义务的,例如如果你在系统中使用NPOI,你必须保留NPOI中的所有声明信息。对于源代码的任何修改,必须做出明确的标识。
完整的apache 2.0许可证请见http://www.phpx.com/man/Apache-2/license.html
1.3 相关资源
官方网站:http://npoi.codeplex.com/
POIFS Browser 1.2
下载地址:http://npoi.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=24305
QQ交流群: 78142590
1.4 团队介绍
Tony Qu来自于中国上海,是这个项目的发起人和开发人员,时区是GMT+8,2008年9月开始了NPOI的开发,负责NPOI所有底层库的开发、测试和bug修复。
个人blog地址为http://tonyqus.cnblogs.com/
Hüseyin Tüfekçilerli来自于土耳其的伊斯坦布尔,也是这个项目的开发人员,时区是GMT+2,2008年11月参与了NPOI的开发,主要负责POIFS Browser 1.0的开发工作。
个人blog地址为http://huseyint.com/
aTao.Xiang,来自中国,2009年8月开始参与该项目,主要参与了NPOI 1.2中文版的撰写工作和推广工作
个人blog地址为http://www.cnblogs.com/atao/
1.5 回顾与展望
目前POI版本中的HWPF(用于Word的读写库)还不是很稳定,并非正式发布版本,且负责HWPF的关键开发人员已经离开,所以NPOI可能考虑自己重新开发HWPF。另外,目前微软正在开发Open XML Format SDK,NPOI可能会放弃对ooxml的支持,当然这取决于用户的需求和Open XML Format SDK的稳定性和速度。从目前而言,NPOI有几大优势
第一,完全基于.NET 2.0,而非.NET 3.0/3.5。
第二,读写速度快(有个国外的兄弟回复说,他原来用ExcelPackage生成用了4-5个小时,现在只需要4-5分钟)
第三,稳定性好(相对于用Office OIA而言,毕竟那东西是基于Automation做的,在Server上跑个Automation的东西,想想都觉得可怕),跑过了将近1000个测试用例(来自于POI的testcase目录)
第四,API简单易用,当然这得感谢POI的设计师们
第五,完美支持Excel 2003格式(据说myxls无法正确读取xls模板,但NPOI可以),以后也许是所有Office 2003格式
希望NPOI把这些优势继续发扬下去,这样NPOI才会更有竞争力。
1.6 NPOI 1.2中各Assembly的作用
NPOI目前有好几个assembly,每个的作用各有不同,开发人员可以按需加载相应的assembly。在这里大概罗列一下:
NPOI.Util 基础辅助库
NPOI.POIFS OLE2格式读写库
NPOI.DDF Microsoft Drawing格式读写库
NPOI.SS Excel公式计算库
NPOI.HPSF OLE2的Summary Information和Document Summary Information属性读写库
NPOI.HSSF Excel BIFF格式读写库
NPOI 1.2教程 - 2.1.1 创建Workbook和Sheet
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
创建Workbook说白了就是创建一个Excel文件,当然在NPOI中更准确的表示是在内存中创建一个Workbook对象流。
本节作为第2章的开篇章节,将做较为详细的讲解,以帮助NPOI的学习者更好的理解NPOI的组成和使用。
NPOI.HSSF是专门负责Excel BIFF格式的命名空间,供开发者使用的对象主要位于NPOI.HSSF.UserModel和NPOI.HSSF.Util命名空间下,下面我们要讲到的Workbook的创建用的就是NPOI.HSSF.UserModel.HSSFWorkbook类,这个类负责创建.xls文档。
在开始创建Workbook之前,我们先要在项目中引用一些必要的NPOI assembly,如下所示:
NPOI.dll
NPOI.POIFS.dll
NPOI.HSSF.dll
NPOI.Util.dll
要创建一个新的xls文件其实很简单,只要我们初始化一个新的HSSFWorkbook实例就行了,如下所示:
using NPOI.HSSF.UserModel;
...
HSSFWorkbook hssfworkbook = new HSSFWorkbook();
是不是很方便啊,没有任何参数或设置,但这么创建有一些限制,这样创建出来的Workbook在Excel中打开是会报错的,因为Excel规定一个Workbook必须至少带1个Sheet,这也是为什么在Excel界面中,新建一个Workbook默认都会新建3个Sheet。所以必须加入下面的创建Sheet的代码才能保证生成的文件正常:
HSSFSheet sheet = hssfworkbook.CreateSheet("new sheet");
如果要创建标准的Excel文件,即拥有3个Sheet,可以用下面的代码:
hssfworkbook.CreateSheet("Sheet1");
hssfworkbook.CreateSheet("Sheet2");
hssfworkbook.CreateSheet("Sheet3");
最后就是把这个HSSFWorkbook实例写入文件了,代码也很简单,如下所示:
FileStream file = new FileStream(@"test.xls", FileMode.Create);
hssfworkbook.Write(file);
file.Close();
这里假设文件名是test.xls,,在创建完FileStream之后,直接调用HSSFWorkbook类的Write方法就可以了。
最后你可以打开test.xls文件确认一下,是不是有3个空的Sheet。
相关范例请见NPOI 1.2正式版中的CreateEmptyExcelFile项目。
NPOI 1.2教程 - 2.1.2 创建DocumentSummaryInformation和SummaryInformation
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
昨天收到了不少回复,有msn上的,也有blog上的,我代表NPOI Team向所有支持和关注NPOI的兄弟表示感谢,让我们共同完善NPOI 。
前一节中我们讲解了如何创建一个新的Workbook,但在此过程中大家也许会发现一个细节,这些文件没有包括DocummentSummaryInformation和SummaryInformation头。如果你还不是很清楚我在说什么,可以看POIFS Browser打开test.xls文件后的截图:
你会发现只有Workbook目录,其他什么都没有,但事实上一个正常的xls文件,比如说Excel生成的xls文件是类似下面的结构:
是不是多出来DocumentSummaryInformation和SummaryInformation两个头?很多人可能对DocumentSummaryInformation和SummaryInformation很陌生,可能第一次听说这玩意,没事,这很正常,因为普通用户很少会去使用这些东西,但它们其实比想象中有用。
请看上图中的信息,如作者、标题、标记、备注、主题等信息,其实这些信息都是存储在DocummentSummaryInformation和SummaryInformation里面的,这么一说我想大家应该明白了吧,这些信息是为了快速提取文件信息准备。在Windows XP中,也有对应的查看和修改界面,只是没有Vista这么方便,如下所示:
这恐怕也是很多人对于这些信息漠不关心的原因吧,因为没有人愿意通过 右击文件->属性 这样复杂的操作去查看一些摘要信息。
提示
DocummentSummaryInformation和SummaryInformation并不是Office文件的专利,只要是OLE2格式,都可以拥有这两个头信息,主要目的就是为了在没有完整读取文件数据的情况下获得文件的摘要信息,同时也可用作桌面搜素的依据。要了解DocummentSummaryInformation的全部属性请见http://msdn.microsoft.com/en-us/library/aa380374(VS.85).aspx;要了解SummaryInformation的全部属性请见http://msdn.microsoft.com/en-us/library/aa369794(VS.85).aspx。
好了,说到这里,我想大家对于接下来我们要创建的内容有了初步的认识,下面我们就马上动手创建。
首先引用以下这些命名空间:
using NPOI.HSSF.UserModel;
using NPOI.HPSF;
using NPOI.POIFS.FileSystem;
其中与DocummentSummaryInformation和SummaryInformation密切相关的是HPSF命名空间。
首先创建Workbook
HSSFWorkbook hssfworkbook = new HSSFWorkbook();
然后创建DocumentSummaryInformation
DocumentSummaryInformation dsi = PropertySetFactory.CreateDocumentSummaryInformation();
dsi.Company = "NPOI Team";
再创建SummaryInformation
SummaryInformation si = PropertySetFactory.CreateSummaryInformation();
si.Subject = "NPOI SDK Example";
因为是范例,这里仅各设置了一个属性,其他都没有设置。
现在我们把创建好的对象赋给Workbook,这样才能保证这些信息被写入文件。
hssfworkbook.DocumentSummaryInformation = dsi;
hssfworkbook.SummaryInformation = si;
最后和2.1.1节一样,我们把Workbook通过FileStream写入文件。
相关范例请见 NPOI 1.2正式版中的CreatePOIFSFileWithProperties
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
用过Excel的人都知道,单元格是Excel最有意义的东西,我们做任何操作恐怕都要和单元格打交道。在Excel中我们要添加一个单元格只需要点击任何一个单元格,然后输入内容就是了,但是Excel底层其实没有这么简单,不同的单元格是有不同的类型的,比如说数值单元格是用NumberRecord表示,文本单元格是用LabelSSTRecord表示,空单元格是用BlankRecord表示。这也就意味着,在设置单元格时,你必须告诉NPOI你需要创建哪种类型的单元格。
要创建单元格首先要创建单元格所在的行,比如,下面的代码创建了第0行:
HSSFSheet sheet1 = hssfworkbook.CreateSheet("Sheet1");
HSSFRow row1=sheet1.CreateRow(0);
行建好了,就可以建单元格了,比如创建A1位置的单元格:
row1.CreateCell(0).SetCellValue(1);
这里要说明一下,SetCellValue有好几种重载,你可以设置单元格为bool、double、DateTime、string和HSSFRichTextString类型。其中对于string类型的重载调用的就是HSSFRichTextString类型的重载,所以是一样的,HSSFRichTextString可用于有字体或者Unicode的文本。
如果你觉得每一行要声明一个HSSFRow很麻烦,可以用下面的方式:
sheet1.CreateRow(0).CreateCell(0).SetCellValue("This is a Sample");
这么用有个前提,那就是第0行还没创建过,否则得这么用:
sheet1.GetRow(0).CreateCell(0).SetCellValue("This is a Sample");
注意:这里的行在Excel里是从1开始的,但是NPOI内部是从0开始的;列在Excel里面是用字母表示的,而NPOI中也是用从0开始的数字表示的,所以要注意转换。
如果你要获得某一个已经创建的单元格对象,可以用下面的代码:
sheet1.GetRow(row_index).GetCell(column_index);
本节仅讲解最基本的单元格创建,有关单元格格式设置、样式等高级话题请见:2.2节单元格相关操作。
相关范例请见 NPOI 1.2正式版中的SetCellValuesInXls项目。
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
很多人不怎么用Excel中的批注,所以我特地截了张图,让大家知道本节我们要创建的到底是什么东西。
在过去,我们恐怕没有办法实现这一功能,因为无论是cvs法、html法、oledb法都没有提供这样的接口,当然Office PIA法可以做到,但是性能实在太差,而且稳定性不好,经常莫名其妙crash(这是某某兄弟给我的反馈,我引用了下,呵呵)。在以后的教程中,你将看到更多在过去无法通过传统方法实现的东西,好戏才刚刚开始。
批注主要有三个属性需要设置,一个是批注的位置和大小、一个是批注的文本、还有一个是批注的作者。
批注的位置和大小,在Excel中是与单元格密切相关的,NPOI中通过HSSFClientAnchor的实例来表示,它的构造函数比较复杂,有8个参数,它们分别是
参数 |
说明 |
dx1 |
第1个单元格中x轴的偏移量 |
dy1 |
第1个单元格中y轴的偏移量 |
dx2 |
第2个单元格中x轴的偏移量 |
dy2 |
第2个单元格中y轴的偏移量 |
col1 |
第1个单元格的列号 |
row1 |
第1个单元格的行号 |
col2 |
第2个单元格的列号 |
row2 |
第2个单元格的行号 |
例如,如果我们打算让注释显示在B3和E5之间,就应该这么写:
HSSFPatriarch patr = sheet.CreateDrawingPatriarch();
HSSFComment comment1 = patr.CreateComment(new HSSFClientAnchor(0, 0, 0, 0, 1, 2 , 4, 4));
下面我们设置这个批注的内容和作者,这个比较简单:
comment1.String = new HSSFRichTextString("Hello World");
comment1.Author = "NPOI Team";
最后一步就是把批注赋给某个单元格:
HSSFCell cell = sheet.CreateRow(1).CreateCell(1);
cell.CellComment = comment1;
对于批注,你有两种选择,一种是隐藏(默认),一种是显示(即表单一打开就显示该批注),可以通过comment1.Visible属性来控制。
看了上面这张图大家就应该明白了,这里有2个批注,下面那个是显示的,上面那个是隐藏的。
相关范例请见 NPOI 1.2正式版中的SetCellCommentInXls。
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
很多人并不知道Excel的页眉和页脚功能,因为在界面上是显示不了页眉和页脚的,必须在打印页面中才能看到,这也直接导致了其设置界面也显得更隐秘,你必须进入页面设置 –> 页眉和页脚才能设置。以下是Office 2007中的设置界面。
当你按“自定义页眉”或“自定义页脚”时,你会看到以下界面,Excel把页眉、页脚分成了左中右三部分,这一点绝非单纯体现在界面上,在底层的存储中也是如此。如果你设置的是“左”的内容,底层的存储字符串就会在开头加上&L,如果是“右”的内容则会加上&R,所以HeaderRecord中的字符串看上去是这样的:"&C&LFooter A&R”,这个字符串的意思是仅设置了“左”的内容,内容是Footer A。
看了这些我想你应该对页眉和页脚有所了解了,回过头来说NPOI,NPOI中主要是靠HSSFSheet.Header和HSSFSheet.Footer来设置的,这两个属性分别是HSSFHeader和HSSFFooter类型的。
参考代码如下:
HSSFSheet s1 = hssfworkbook.CreateSheet("Sheet1");
s1.CreateRow(0).CreateCell(1).SetCellValue(123);
//set header text
s1.Header.Center = "This is a test sheet";
//set footer text
s1.Footer.Left = "Copyright NPOI Team";
s1.Footer.Right = "created by Tony Qu(瞿杰)";
以上代码中我添加了页眉的Center内容,Footer的Left和Right内容,在打印预览中看到的效果大概是这样的:
页眉
页脚
至于一些Excel特殊字符,比如说页码可以用&P,当前日期可以用&D,其他的东西你就自己研究吧。
本范例完整代码请见NPOI.Examples中的CreateHeaderFooterInXls项目。
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
在Excel中我们经常要设置格式,比如说日期格式(yyyymmdd)、小数点格式(1.20)、货币格式($2000)、百分比格式(99.99%)等等,这些东西在过去我们恐怕只能在服务器端生成好,不但增加了服务器端的代码量,还造成了不必要的字符串替换操作,如今NPOI将让服务器从这种完全没有必要的操作中解放出来,一切都将由Excel在客户端处理。
使用NPOI时要注意,所有的格式都是通过CellStyle.DataFormat赋给单元格的,而不是直接赋给单元格。
案例一 日期格式
假设我们现在需要显示的日期的格式为2008年5月5日,可以用下面的代码生成:
HSSFSheet sheet = hssfworkbook.CreateSheet("new sheet");
HSSFCell cell = sheet.CreateRow(0).CreateCell(0);
cell.SetCellValue(new DateTime(2008,5,5));
//set date format
HSSFCellStyle cellStyle = hssfworkbook.CreateCellStyle();
HSSFDataFormat format = hssfworkbook.CreateDataFormat();
cellStyle.DataFormat = format.GetFormat("yyyy年m月d日");
cell.CellStyle=cellStyle;
由于这里的“yyyy年m月d日”属于自定义格式(区别于Excel内嵌的格式),所以必须用hssfworkbook.CreateDataFormat()创建一个HSSFDataFormat实例,然后使用format.GetFormat来获取相应的格式,只要是Excel支持的格式表示方式,这种方式都能够实现。
案例二保留2位小数
假设我们有个单元格的值为1.2,怎么显示成1.20呢?在Excel中可以用“0.00”来表示,所以下面的代码就能完成:
// Create a row and put some cells in it. Rows are 0 based.
HSSFCell cell = sheet.CreateRow(0).CreateCell(0);
//set value for the cell
cell.SetCellValue(1.2);
//number format with 2 digits after the decimal point - "1.20"
HSSFCellStyle cellStyle = hssfworkbook.CreateCellStyle();
cellStyle.DataFormat = HSSFDataFormat.GetBuiltinFormat("0.00");
cell.CellStyle = cellStyle;
这里与上面有所不同,用的是HSSFDataFormat.GetBuiltinFormat()方法,之所以用这个,是因为0.00是Excel内嵌的格式,完整的Excel内嵌格式列表大家可以看这个窗口中的自定义列表:
这里就不一一列出了。
案例三货币格式
货币格式在金融的项目中经常用到,比如说人民币符号¥,美元符号$等,这里可以用下面的代码表示:
HSSFCell cell2 = sheet.CreateRow(1).CreateCell(0);
cell2.SetCellValue(20000);
HSSFCellStyle cellStyle2 = hssfworkbook.CreateCellStyle();
HSSFDataFormat format = hssfworkbook.CreateDataFormat();
cellStyle2.DataFormat = format.GetFormat("¥#,##0");
cell2.CellStyle = cellStyle2;
注意,这里还加入了千分位分隔符,所以是#,##,至于为什么这么写,你得去问微软,呵呵。
案例四百分比
百分比在报表中也很常用,其实基本上和上面一样,只是格式表示是0.00%,代码如下:
cellStyle4.DataFormat = HSSFDataFormat.GetBuiltinFormat("0.00%");
由于这里是内嵌格式,所以直接用HSSFDataFormat.GetBuiltinFormat即可。
案例五中文大写
在表示金额时,我们时常会用到,我也见过不少兄弟实现了数字转中文大小写的工具类,以后你可以尝试让Excel去处理这一切,代码和刚才差不多,也是改格式的表示:
HSSFDataFormat format = hssfworkbook.CreateDataFormat();
cellStyle6.DataFormat = format.GetFormat("[DbNum2][$-804]0");
由于是自定义格式,所以用了HSSFDataFormat.GetFormat,相信你对这两种获取格式的形式的区别越来越熟悉了。
案例六科学计数法
这东西数学课上我们都学过,虽然用的不多,但是既然Excel支持,这里也提一下:
cellStyle3.DataFormat = HSSFDataFormat.GetBuiltinFormat("0.00E+00");
下面展示下以上这些例子的显示效果:
最后总结一下HSSFDataFormat.GetFormat和HSSFDataFormat.GetBuiltinFormat的区别:
当使用Excel内嵌的(或者说预定义)的格式时,直接用HSSFDataFormat.GetBuiltinFormat静态方法即可。
当使用自己定义的格式时,必须先调用HSSFWorkbook.CreateDataFormat(),因为这时在底层会先找有没有匹配的内嵌FormatRecord,如果没有就会新建一个FormatRecord,所以必须先调用这个方法,然后你就可以用获得的HSSFDataFormat实例的GetFormat方法了,当然相对而言这种方式比较麻烦,所以内嵌格式还是用HSSFDataFormat.GetBuiltinFormat静态方法更加直接一些。不过自定义的格式也不是天马行空随便定义,还是要参照Excel的格式表示来定义,具体请看相关的Excel教程。
注意:自定义的FormatRecord是嵌入xls文件内部的,所以不用担心对方Excel中有没有定义过这种格式,都是能够正常使用的。
相关范例请参考NPOI 1.2正式版中的NumberFormatInXls项目。
作者:Tony Qu
NPOI官方网站:http://npoi.codeplex.com/
合并单元格在制作表格时很有用,比如说表格的标题就经常是把第一行的单元格合并居中。那么在NPOI中应该如何实现单元格的合并呢?
为了实现这一功能,NPOI引入了新的概念,即Region,因为合并单元格,其实就是设定一个区域。下面说一下Region类的参数,Region总共有4个参数,如下所示
Region的参数 |
说明 |
FirstRow |
区域中第一个单元格的行号 |
FirstColumn |
区域中第一个单元格的列号 |
LastRow |
区域中最后一个单元格的行号 |
LastColumn |
区域中最后一个单元格的列号 |
由于单元格的合并都是在表的基础上建立的,所以我们得先建Sheet:
HSSFWorkbook hssfworkbook = new HSSFWorkbook();
HSSFSheet sheet = hssfworkbook.CreateSheet("new sheet");
接下来我们根据实际场景来做一些演示。
场景一标题行的合并
这种场景是最常见的,比如说我们要建立一张销售情况表,英文叫Sales Report
我们先设置居中和字体样式,这里我们采用20号字体,代码如下:
HSSFRow row = sheet.CreateRow(0);
HSSFCell cell = row.CreateCell(0);
cell.SetCellValue("Sales Report");
HSSFCellStyle style = hssfworkbook.CreateCellStyle();
style.Alignment = HSSFCellStyle.ALIGN_CENTER;
HSSFFont font = hssfworkbook.CreateFont();
font.FontHeight = 20*20;
style.SetFont(font);