https://www.hoshino.asia/archives/hutool

概述

由来

Java针对MS Office的操作的库屈指可数，比较有名的就是Apache的POI库。这个库异常强大，但是使用起来也并不容易。Hutool针对POI封装一些常用工具，使Java操作Excel等文件变得异常简单。

介绍

Hutool-poi是针对Apache POI的封装，因此需要用户自行引入POI库,Hutool默认不引入。到目前为止，Hutool-poi支持：

Excel文件（xls, xlsx）的读取（ExcelReader）
Excel文件（xls，xlsx）的写出（ExcelWriter）

使用

引入POI依赖

推荐引入poi-ooxml，这个包会自动关联引入poi包，且可以很好的支持Office2007+的文档格式

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>${poi.version}</version>
</dependency>

如果需要使用Sax方式读取Excel，需要引入以下依赖（POI-4.x以上这个非必须）：

<dependency>
    <groupId>xerces</groupId>
    <artifactId>xercesImpl</artifactId>
    <version>${xerces.version}</version>
</dependency>

说明
hutool-4.x的poi-ooxml 版本需高于 3.17（别问我3.8版本为啥不行，因为3.17 > 3.8 ）
hutool-5.x的poi-ooxml 版本需高于 4.1.2
hutool-5.6.x支持poi-ooxml 版本高于 5.0.0
xercesImpl版本高于2.12.0（非必须）

引入后即可使用Hutool的方法操作Office文件了，Hutool提供的类有：

ExcelUtil Excel工具类，读取的快捷方法都被封装于此
ExcelReader Excel读取器，Excel读取的封装，可以直接构造后使用。
ExcelWriter Excel生成并写出器，Excel写出的封装（写出到流或者文件），可以直接构造后使用。

常见问题

部分用户使用POI模块时会提示：

You need to add dependency of 'poi-ooxml' to your project, and version >= 4.1.2

一般以下几个原因：

没有引入POI相关jar或引入版本太低
引入了多个版本的POI，导致包冲突了
没有引入关联依赖，这个具体要看下堆栈中的Cause By

Excel工具-ExcelUtil

介绍

Excel操作工具封装

使用

从文件中读取Excel为ExcelReader

ExcelReader reader = ExcelUtil.getReader(FileUtil.file("test.xlsx"));

从流中读取Excel为ExcelReader（比如从ClassPath中读取Excel文件）

ExcelReader reader = ExcelUtil.getReader(ResourceUtil.getStream("aaa.xlsx"));

读取指定的sheet

ExcelReader reader;

//通过sheet编号获取
reader = ExcelUtil.getReader(FileUtil.file("test.xlsx"), 0);
//通过sheet名获取
reader = ExcelUtil.getReader(FileUtil.file("test.xlsx"), "sheet1");

读取大数据量的Excel

private RowHandler createRowHandler() {
	return new RowHandler() {
		@Override
		public void handle(int sheetIndex, int rowIndex, List<Object> rowlist) {
			Console.log("[{}] [{}] {}", sheetIndex, rowIndex, rowlist);
		}
	};
}

ExcelUtil.readBySax("aaa.xlsx", 0, createRowHandler());

后续

ExcelUtil.getReader方法只是将实体Excel文件转换为ExcelReader对象进行操作。接下来请参阅章节ExcelReader对Excel工作簿进行具体操作。

Excel生成-ExcelWriter

由来

Excel有读取也便有写出，Hutool针对将数据写出到Excel做了封装。

原理

Hutool将Excel写出封装为ExcelWriter，原理为包装了Workbook对象，每次调用merge（合并单元格）或者write（写出数据）方法后只是将数据写入到Workbook，并不写出文件，只有调用flush或者close方法后才会真正写出文件。

由于机制原因，在写出结束后需要关闭ExcelWriter对象，调用close方法即可关闭，此时才会释放Workbook对象资源，否则带有数据的Workbook一直会常驻内存。

使用例子

1. 将行列对象写出到Excel

我们先定义一个嵌套的List，List的元素也是一个List，内层的一个List代表一行数据，每行都有4个单元格，最终list对象代表多行数据。

List<String> row1 = CollUtil.newArrayList("aa", "bb", "cc", "dd");
List<String> row2 = CollUtil.newArrayList("aa1", "bb1", "cc1", "dd1");
List<String> row3 = CollUtil.newArrayList("aa2", "bb2", "cc2", "dd2");
List<String> row4 = CollUtil.newArrayList("aa3", "bb3", "cc3", "dd3");
List<String> row5 = CollUtil.newArrayList("aa4", "bb4", "cc4", "dd4");

List<List<String>> rows = CollUtil.newArrayList(row1, row2, row3, row4, row5);

然后我们创建ExcelWriter对象后写出数据：

//通过工具类创建writer
ExcelWriter writer = ExcelUtil.getWriter("d:/writeTest.xlsx");
//通过构造方法创建writer
//ExcelWriter writer = new ExcelWriter("d:/writeTest.xls");

//跳过当前行，既第一行，非必须，在此演示用
writer.passCurrentRow();

//合并单元格后的标题行，使用默认标题样式
writer.merge(row1.size() - 1, "测试标题");
//一次性写出内容，强制输出标题
writer.write(rows, true);
//关闭writer，释放内存
writer.close();

2. 写出Map数据

构造数据：

Map<String, Object> row1 = new LinkedHashMap<>();
row1.put("姓名", "张三");
row1.put("年龄", 23);
row1.put("成绩", 88.32);
row1.put("是否合格", true);
row1.put("考试日期", DateUtil.date());

Map<String, Object> row2 = new LinkedHashMap<>();
row2.put("姓名", "李四");
row2.put("年龄", 33);
row2.put("成绩", 59.50);
row2.put("是否合格", false);
row2.put("考试日期", DateUtil.date());

ArrayList<Map<String, Object>> rows = CollUtil.newArrayList(row1, row2);

写出数据：

// 通过工具类创建writer
ExcelWriter writer = ExcelUtil.getWriter("d:/writeMapTest.xlsx");
// 合并单元格后的标题行，使用默认标题样式
writer.merge(row1.size() - 1, "一班成绩单");
// 一次性写出内容，使用默认样式，强制输出标题
writer.write(rows, true);
// 关闭writer，释放内存
writer.close();

3. 写出Bean数据

定义Bean:

public class TestBean {
	private String name;
	private int age;
	private double score;
	private boolean isPass;
	private Date examDate;

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public double getScore() {
		return score;
	}

	public void setScore(double score) {
		this.score = score;
	}

	public boolean isPass() {
		return isPass;
	}

	public void setPass(boolean isPass) {
		this.isPass = isPass;
	}

	public Date getExamDate() {
		return examDate;
	}

	public void setExamDate(Date examDate) {
		this.examDate = examDate;
	}
}

构造数据：

TestBean bean1 = new TestBean();
bean1.setName("张三");
bean1.setAge(22);
bean1.setPass(true);
bean1.setScore(66.30);
bean1.setExamDate(DateUtil.date());

TestBean bean2 = new TestBean();
bean2.setName("李四");
bean2.setAge(28);
bean2.setPass(false);
bean2.setScore(38.50);
bean2.setExamDate(DateUtil.date());

List<TestBean> rows = CollUtil.newArrayList(bean1, bean2);

写出数据：

// 通过工具类创建writer
ExcelWriter writer = ExcelUtil.getWriter("d:/writeBeanTest.xlsx");
// 合并单元格后的标题行，使用默认标题样式
writer.merge(4, "一班成绩单");
// 一次性写出内容，使用默认样式，强制输出标题
writer.write(rows, true);
// 关闭writer，释放内存
writer.close();

4. 自定义Bean的key别名（排序标题）

在写出Bean的时候，我们可以调用ExcelWriter对象的addHeaderAlias方法自定义Bean中key的别名，这样就可以写出自定义标题了（例如中文）。

写出数据：

// 通过工具类创建writer
ExcelWriter writer = ExcelUtil.getWriter("d:/writeBeanTest.xlsx");

//自定义标题别名
writer.addHeaderAlias("name", "姓名");
writer.addHeaderAlias("age", "年龄");
writer.addHeaderAlias("score", "分数");
writer.addHeaderAlias("isPass", "是否通过");
writer.addHeaderAlias("examDate", "考试时间");

// 默认的，未添加alias的属性也会写出，如果想只写出加了别名的字段，可以调用此方法排除之
writer.setOnlyAlias(true);

// 合并单元格后的标题行，使用默认标题样式
writer.merge(4, "一班成绩单");
// 一次性写出内容，使用默认样式，强制输出标题
writer.write(rows, true);
// 关闭writer，释放内存
writer.close();

同时支持别名注解的。可以在字段上加@Alias注解。

@Alias(value = "姓名")
private String name;

提示（since 4.1.5）
默认情况下Excel中写出Bean字段不能保证顺序，此时可以使用addHeaderAlias方法设置标题别名，Bean的写出顺序就会按照标题别名的加入顺序排序。
如果不需要设置标题但是想要排序字段，请调用writer.addHeaderAlias("age", "age")设置一个相同的别名就可以不更换标题。
未设置标题别名的字段不参与排序，会默认排在前面。

5. 写出到流

// 通过工具类创建writer，默认创建xls格式
ExcelWriter writer = ExcelUtil.getWriter();
//创建xlsx格式的
//ExcelWriter writer = ExcelUtil.getWriter(true);
// 一次性写出内容，使用默认样式，强制输出标题
writer.write(rows, true);
//out为OutputStream，需要写出到的目标流
writer.flush(out);
// 关闭writer，释放内存
writer.close();

6. 写出到客户端下载（写出到Servlet）

写出xls

// 通过工具类创建writer，默认创建xls格式
ExcelWriter writer = ExcelUtil.getWriter();
// 一次性写出内容，使用默认样式，强制输出标题
writer.write(rows, true);
//out为OutputStream，需要写出到的目标流

//response为HttpServletResponse对象
response.setContentType("application/vnd.ms-excel;charset=utf-8"); 
//test.xls是弹出下载对话框的文件名，不能为中文，中文请自行编码
response.setHeader("Content-Disposition","attachment;filename=test.xls"); 
ServletOutputStream out=response.getOutputStream(); 

writer.flush(out, true);
// 关闭writer，释放内存
writer.close();
//此处记得关闭输出Servlet流
IoUtil.close(out);

写出xlsx

ExcelWriter writer = ExcelUtil.getWriter(true);
writer.write(rows, true);

response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;charset=utf-8"); 
response.setHeader("Content-Disposition","attachment;filename=test.xlsx"); 
ServletOutputStream out=response.getOutputStream(); 

writer.flush(out, true);
writer.close();
IoUtil.close(out);

注意
ExcelUtil.getWriter()默认创建xls格式的Excel，因此写出到客户端也需要自定义文件名为XXX.xls，否则会出现文件损坏的提示。
若想生成xlsx格式，请使用ExcelUtil.getWriter(true)创建。

下载提示文件损坏问题解决

有用户反馈按照代码生成的Excel下载后提示文件损坏，无法打开，经过排查，可能是几个问题：

（1）writer和out流没有正确关闭，请在代码末尾的finally块增加关闭。
（2）扩展名不匹配。getWriter默认生成xls，Content-Disposition中也应该是xls，只有getWriter(true)时才可以使用xlsx
（3）Maven项目中Excel保存于ClassPath中（src/main/resources下）宏替换导致被破坏，解决办法是添加filtering（参考：springboot下载Excel模板，Excel表损坏问题
（4）Excel打开提示文件损坏，WPS可以打开。这是Excel的安全性控制导致的，解决办法见：springboot下载excel（解决文件损坏问题）

自定义Excel

1. 设置单元格背景色

ExcelWriter writer = ...;

// 定义单元格背景色
StyleSet style = writer.getStyleSet();
// 第二个参数表示是否也设置头部单元格背景
style.setBackgroundColor(IndexedColors.RED, false);

2. 自定义字体

ExcelWriter writer = ...;
//设置内容字体
Font font = writer.createFont();
font.setBold(true);
font.setColor(Font.COLOR_RED); 
font.setItalic(true); 
//第二个参数表示是否忽略头部样式
writer.getStyleSet().setFont(font, true);

3. 写出多个sheet

//初始化时定义表名
ExcelWriter writer = new ExcelWriter("d:/aaa.xls", "表1");
//切换sheet，此时从第0行开始写
writer.setSheet("表2");
...
writer.setSheet("表3");
...

4. 更详细的定义样式

在Excel中，由于样式对象个数有限制，因此Hutool根据样式种类分为4个样式对象，使相同类型的单元格可以共享样式对象。样式按照类别存在于StyleSet中，其中包括：

headCellStyle 头部样式
cellStyle 普通单元格样式
cellStyleForNumber 数字单元格样式
cellStyleForDate 日期单元格样式

其中cellStyleForNumber cellStyleForDate用于控制数字和日期的显示方式。

因此我们可以使用以下方式获取CellStyle对象自定义指定种类的样式：

StyleSet style = writer.getStyleSet();
CellStyle cellStyle = style.getHeadCellStyle();
...

5. 自定义写出的值

你可以实现CellSetter接口来自定义写出到单元格的值，此接口只有一个方法：setValue(Cell cell)，通过暴露Cell对象使得用户可以自定义输出单元格内容，甚至是样式。

// 此处使用lambda自定义写出内容
List<Object> row = ListUtil.of((CellSetter) cell -> cell.setCellValue("自定义内容"));

ExcelWriter writer = ExcelUtil.getWriter("/test/test.xlsx");
writer.writeRow(row);
writer.close();

注意
某些特殊的字符串会导致Excel自动转义，如_xXXXX_这种格式的字符串会被当做unicode转义符，会被反转义。
此时可以使用Hutool内置的EscapeStrCellSetter

List<Object> row = ListUtil.of(new EscapeStrCellSetter("_x5116_"));

ExcelWriter writer = ExcelUtil.getWriter("/test/test.xlsx");
writer.writeRow(row);
writer.close();

此问题的详细说明见：单元格包含"_x”导致字符串转码

Excel大数据生成-BigExcelWriter

介绍

对于大量数据输出，采用ExcelWriter容易引起内存溢出，因此有了BigExcelWriter，使用方法与ExcelWriter完全一致。

使用

List<?> row1 = CollUtil.newArrayList("aa", "bb", "cc", "dd", DateUtil.date(), 3.22676575765);
List<?> row2 = CollUtil.newArrayList("aa1", "bb1", "cc1", "dd1", DateUtil.date(), 250.7676);
List<?> row3 = CollUtil.newArrayList("aa2", "bb2", "cc2", "dd2", DateUtil.date(), 0.111);
List<?> row4 = CollUtil.newArrayList("aa3", "bb3", "cc3", "dd3", DateUtil.date(), 35);
List<?> row5 = CollUtil.newArrayList("aa4", "bb4", "cc4", "dd4", DateUtil.date(), 28.00);

List<List<?>> rows = CollUtil.newArrayList(row1, row2, row3, row4, row5);

BigExcelWriter writer= ExcelUtil.getBigWriter("e:/xxx.xlsx");
// 一次性写出内容，使用默认样式
writer.write(rows);
// 关闭writer，释放内存
writer.close();

Excel读取-ExcelReader

介绍

读取Excel内容的封装，通过构造ExcelReader对象，指定被读取的Excel文件、流或工作簿，然后调用readXXX方法读取内容为指定格式。

使用

读取Excel中所有行和列，用二维列表表示

ExcelReader reader = ExcelUtil.getReader("d:/aaa.xlsx");
List<List<Object>> readAll = reader.read();

读取为Map列表，默认第一行为标题行，数据从第二行开始，一个Map表示一行，Map中的key为标题，value为标题对应的单元格值。

ExcelReader reader = ExcelUtil.getReader("d:/aaa.xlsx");
List<Map<String, Object>> readAll = reader.readAll();

读取为Bean列表，Bean中的字段名为标题，字段值为标题对应的单元格值。

ExcelReader reader = ExcelUtil.getReader("d:/aaa.xlsx");
List<Person> all = reader.readAll(Person.class);

Word生成-Word07Writer

由来

Hutool针对Word（主要是docx格式）进行封装，实现简单的Word文件创建。

介绍

Hutool将POI中Word生成封装为Word07Writer, 通过分段写出，实现word生成。

使用例子

Word07Writer writer = new Word07Writer();

// 添加段落（标题）
writer.addText(new Font("方正小标宋简体", Font.PLAIN, 22), "我是第一部分", "我是第二部分");
// 添加段落（正文）
writer.addText(new Font("宋体", Font.PLAIN, 22), "我是正文第一部分", "我是正文第二部分");
// 写出到文件
writer.flush(FileUtil.file("e:/wordWrite.docx"));
// 关闭
writer.close();

流方式读取Excel2003-Excel03SaxReader

介绍

在标准的ExcelReader中，如果数据量较大，读取Excel会非常缓慢，并有可能造成内存溢出。因此针对大数据量的Excel，Hutool封装了event模式的读取方式。

Excel03SaxReader只支持Excel2003格式的Sax读取。

使用

定义行处理器

首先我们实现一下RowHandler接口，这个接口是Sax读取的核心，通过实现handle方法编写我们要对每行数据的操作方式（比如按照行入库，入List或者写出到文件等），在此我们只是在控制台打印。

private RowHandler createRowHandler() {
	return new RowHandler() {
		@Override
		public void handle(int sheetIndex, long rowIndex, List<Object> rowlist) {
			Console.log("[{}] [{}] {}", sheetIndex, rowIndex, rowlist);
		}
	};
}

ExcelUtil快速读取

ExcelUtil.readBySax("aaa.xls", 1, createRowHandler());

构建对象读取

Excel03SaxReader reader = new Excel03SaxReader(createRowHandler());
reader.read("aaa.xls", 0);

reader方法的第二个参数是sheet的序号，-1表示读取所有sheet，0表示第一个sheet，依此类推。

流方式读取Excel2007-Excel07SaxReader

介绍

在标准的ExcelReader中，如果数据量较大，读取Excel会非常缓慢，并有可能造成内存溢出。因此针对大数据量的Excel，Hutool封装了Sax模式的读取方式。

Excel07SaxReader只支持Excel2007格式的Sax读取。

使用

定义行处理器

private RowHandler createRowHandler() {
	return new RowHandler() {
		@Override
		public void handle(int sheetIndex, long rowIndex, List<Object> rowlist) {
			Console.log("[{}] [{}] {}", sheetIndex, rowIndex, rowlist);
		}
	};
}

ExcelUtil快速读取

ExcelUtil.readBySax("aaa.xlsx", 0, createRowHandler());

构建对象读取

Excel07SaxReader reader = new Excel07SaxReader(createRowHandler());
reader.read("d:/text.xlsx", 0);

reader方法的第二个参数是sheet的序号，-1表示读取所有sheet，0表示第一个sheet，依此类推。

概述

由来

介绍

使用

引入POI依赖

常见问题

Excel工具-ExcelUtil

介绍

使用

后续

Excel生成-ExcelWriter

由来

原理

使用例子

1. 将行列对象写出到Excel

2. 写出Map数据

3. 写出Bean数据

4. 自定义Bean的key别名（排序标题）

5. 写出到流

6. 写出到客户端下载（写出到Servlet）

自定义Excel

1. 设置单元格背景色

2. 自定义字体

3. 写出多个sheet

4. 更详细的定义样式

5. 自定义写出的值

Excel大数据生成-BigExcelWriter

介绍

使用

Excel读取-ExcelReader

介绍

使用

Word生成-Word07Writer

由来

介绍

使用例子

流方式读取Excel2003-Excel03SaxReader

介绍

使用

定义行处理器

ExcelUtil快速读取

构建对象读取

流方式读取Excel2007-Excel07SaxReader

介绍

使用

定义行处理器

ExcelUtil快速读取

构建对象读取

Takanashi Hoshino