数据导入导出（EasyExcel）框架入门指南

写在前面
前些天发现了一个巨牛的人工智能学习网站，通俗易懂，风趣幽默，忍不住分享一下给大家。点击跳转到网站

EasyExcel 框架

本文仅作为快速入门指南，深入学习详见官方文档

概述

Java 解析、生成 Excel 比较有名的框架有Apache poi、jxl，但它们都存在一些严重的问题，如代码编写繁琐且重复，极其耗费内存。EasyExcel 是一个基于 Java 的简单、省内存的读写 Excel 的开源项目。在尽可能节约内存的情况下支持读写百万级数据的 Excel。

EasyExcel：阿里巴巴开源的操作 Excel 的框架，底层封装的 POI，可以大大减少占用内存的主要原因是在解析 Excel 时，没有将文件数据一次性全部加载到内存中，而是从磁盘上一行行读取数据，逐个解析。

下图是 easyExcel 和 POI 在解析 Excel 时的对比图：

easyExcel 采用一行一行的解析模式，并将一行的解析结果以观察者的模式通知处理（AnalysisEventListener）。

• 在实体类上配置注解（适配 Excel 中的标题）
• 调用 EasyExcel 的工具类方法，完成文件的上传或者下载

依赖

		<dependency><groupId>com.alibaba</groupId><artifactId>easyexcel</artifactId><version>3.1.1</version></dependency>

API

Excel 实体类注解

• @ExcelIgnoreUnannotated：标注在实体类上，作用是只使用标注了 @ExcelProperty 注解的字段参与 excel 读写。默认是不管加不加 ExcelProperty 的注解，所有字段都会参与读写

• @ExcelProperty：标注在实体类属性上，用于 excel 的列和实体类属性的匹配

  参数如下：

  名称	默认值	描述
  value	空	用于匹配excel中的头，必须全匹配，如果有多行头，会匹配最后一行头
  order	Integer.MAX_VALUE	优先级高于value，会根据order的顺序来匹配实体和 excel 中数据的顺序
  index	-1	优先级高于value和order，会根据index直接指定到excel中具体的哪一列
  converter	自动选择	指定当前字段用什么转换器，默认会自动选择。写的情况下只要实现com.alibaba.excel.converters.Converter#convertToExcelData(com.alibaba.excel.converters.WriteConverterContext<T>) 方法即可

• @ExcelIgnore：标注在实体类属性上，默认所有字段都会和 excel 去匹配，加了这个注解会忽略该字段

• @DateTimeFormat：标注在实体类属性上，日期转换

  参数如下：

  名称	默认值	描述
  value	空	参照java.text.SimpleDateFormat书写即可
  use1904windowing	自动选择	excel中时间是存储1900年起的一个双精度浮点数，但是有时候默认开始日期是1904，所以设置这个值改成默认1904年开始

• @NumberFormat：标注在实体类属性上，数字转换

  参数如下：

  名称	默认值	描述
  value	空	参照java.text.DecimalFormat书写即可
  roundingMode	RoundingMode.HALF_UP	格式化的时候设置舍入模式

写 Excel

概念介绍

• WriteWorkbook ：可以理解成一个 excel 文件
• WriteSheet ：理解成一个excel 文件里面的一个表单
• WriteTable ： 一个表单里面如果有多个实际用的表格，则可以用 WriteTablejava

写 Excel 通用参数

WriteWorkbook，WriteSheet ，WriteTable 都会有的参数，如果为空，默认使用上级。

名称	默认值	描述
converter	空	默认加载了很多转换器，这里可以加入不支持的字段
writeHandler	空	写的处理器。可以实现WorkbookWriteHandler,SheetWriteHandler,RowWriteHandler,CellWriteHandler，在写入excel的不同阶段会调用
relativeHeadRowIndex	0	写入到excel和上面空开几行
head	空	与clazz二选一。读取文件头对应的列表，会根据列表匹配数据，建议使用class
clazz	空	与head二选一。读取文件的头对应的class，也可以使用注解。如果两个都不指定，则会读取全部数据
autoTrim	true	会对头、读取数据等进行自动trim
use1904windowing	false	excel中时间是存储1900年起的一个双精度浮点数，但是有时候默认开始日期是1904，所以设置这个值改成默认1904年开始
useScientificFormat	false	数字转文本的时候在较大的数值的是否是否采用科学计数法
needHead	true	是否需要写入头到excel
useDefaultStyle	true	是否使用默认的样式
automaticMergeHead	true	自动合并头，头中相同的字段上下左右都会去尝试匹配
excludeColumnIndexes	空	需要排除对象中的index的数据
excludeColumnFieldNames	空	需要排除对象中的字段的数据
includeColumnIndexes	空	只要导出对象中的index的数据
includeColumnFieldNames	空	只要导出对象中的字段的数据

WriteWorkbook

设置方法如下（找不到参数的看下通用参数里面是否存在）：

EasyExcel.write(fileName, DemoData.class)// 在 write 方法之后， 在 sheet方法之前都是设置 WriteWorkbook 的参数.sheet("模板").doWrite(() -> {// 分页查询数据return data();});

WriteWorkbook 方法：

public static ExcelWriterBuilder write()
public static ExcelWriterBuilder write(File file)
public static ExcelWriterBuilder write(String pathName)
public static ExcelWriterBuilder write(String pathName, Class head)
public static ExcelWriterBuilder write(OutputStream outputStream)
public static ExcelWriterBuilder write(OutputStream outputStream, Class head)
// 参数说明：
// 		file		创建的excel文件路径，路径需包含文件名
// 		pathName	创建的excel文件路径，路径需包含文件名
// 		outputStream	创建的excel文件的输出流，路径需包含文件名
// 		head		excel文件的行头实体类（标题栏）

WriteWorkbook 参数：

名称	默认值	描述
excelType	空	当前excel的类型,支持XLS、XLSX、CSV
outputStream	空	与file二选一。写入文件的流
file	空	与outputStream二选一。写入的文件
templateInputStream	空	模板的文件流
templateFile	空	模板文件
charset	Charset#defaultCharset	只有csv文件有用，写入文件的时候使用的编码
autoCloseStream	true	自动关闭写入的流。
password	空	读取文件的密码
inMemory	false	是否在内存处理，默认会生成临时文件以节约内存。内存模式效率会更好，但是容易OOM
writeExcelOnException	false	写入过程中抛出异常了，是否尝试把数据写入到excel

WriteSheet

• 设置方法如下（找不到参数的看下通用参数里面是否存在）

  EasyExcel.write(fileName, DemoData.class).sheet("模板")// 在 sheet 方法之后， 在 doWrite方法之前都是设置WriteSheet的参数.doWrite(() -> {// 分页查询数据return data();});
  

  参数说明：

  名称	默认值	描述
  sheetNo	0	需要写入的编码
  sheetName	空	需要些的Sheet名称，默认同sheetNo

WriteTable

• 设置方法如下（找不到参数的看下通用参数里面是否存在）

  EasyExcel.write(fileName, DemoData.class).sheet("模板").table()// 在 table 方法之后， 在 doWrite方法之前都是设置WriteTable的参数.doWrite(() -> {// 分页查询数据return data();});
  

  参数说明：

  名称	默认值	描述
  tableNo	0	需要写入的编码

代码示例

创建 Excel 文件

（1）配置实体类

在 EasyExcel 中，通过 java 代码生成或者解析 Excel 文件很简单。不需要创建繁琐的表头

• 创建数据行的实体类 ： ContractProductVo

• 在实体类上通过注解配置 ：标题，行高，列宽等数据

  • @ExcelProperty：在创建Excel的时候，自动的读取实体类中的注解配置，生成表头

• 示例代码如下

  import com.alibaba.excel.annotation.ExcelProperty;
  import com.alibaba.excel.annotation.format.DateTimeFormat;
  import com.alibaba.excel.annotation.write.style.ColumnWidth;
  import com.alibaba.excel.annotation.write.style.ContentRowHeight;
  import com.alibaba.excel.annotation.write.style.HeadRowHeight;
  import lombok.Data;
  import java.util.Date;/*** Excel 实体类*/
  @Data
  @ContentRowHeight(20)  //数据行高数
  @HeadRowHeight(20)     //表头高度
  @ColumnWidth(15)       //列宽
  public class UserExcelVo {@ExcelProperty("用户名")private String username;@ExcelProperty("密码")private String password;@ExcelProperty("电话")private String phone;@ExcelProperty("创建时间")@DateTimeFormat("yyyy-MM-dd")private Date createTime;
  }
  

（2）Excel 文件的生成和下载

• 在 java 代码中通过 EasyExcel 工具类完成 excel 文件的生成和下载

• 示例代码如下

  	/*** 使用 EasyExcel完成 excel 的生成和下载*  1、数据查询*  2、设置下载信息*  3、调用EasyExcel的工具类完成生成下载*/@RequestMapping("/printEasyExcel")public void printEasyExcel(String inputDate) throws IOException {//1、数据查询List<ContractProductVo> list = contractService.findByShipTime(inputDate+"%");//2、设置下载信息response.setContentType("application/vnd.ms-excel"); //下载excelresponse.setCharacterEncoding("utf-8");String fileName = URLEncoder.encode("出货表", "UTF-8");response.setHeader("Content-disposition", "attachment;filename=" + fileName + ".xlsx");//3、调用EasyExcel的工具类完成生成下载EasyExcel.write(response.getOutputStream()).head(ContractProductVo.class) //设置表头.sheet("test127") //指定页名称.doWrite(list); //设置数据}
  

模板打印

对于复杂样式的 Excel 文件创建，EasyExcel 支持模板打印。以一个 Excel 文件作为模板，自动的进行数据的拓展和填充。

• 定义模板 ( 配置好了所有的样式 )
• 配置实体类（表头）
• java代码填充模板并下载 Excel

（1）定义模板

• 在 easyExcel 中，支持两个模板语言
• 语法：{map中的key}
  • 传入一个 map 集合：往往是用于处理非list集合的数据
• 语法：{.对象中的属性名}
  • 传入一个 list 集合，会自动的循环 list 集合构造数据列表

（2）填充模板并下载 Excel 模板文件

	/*** 模板打印**/@RequestMapping("/printTemplate")public void printTemplate(String inputDate) throws IOException {//1.准备数据List<ContractProductVo> list = contractService.findByShipTime(inputDate+"%");Map map = new HashMap<>();inputDate = inputDate.replaceAll("-0","-").replaceAll("-","年");map.put("time",inputDate);map.put("title1","客户名称");//2.设置下载信息response.setContentType("application/vnd.ms-excel"); //下载excelresponse.setCharacterEncoding("utf-8");String fileName = URLEncoder.encode("出货表", "UTF-8");response.setHeader("Content-disposition", "attachment;filename=" + fileName + ".xlsx");//3.加载excel模板String path = session.getServletContext().getRealPath("/")+"/make/tOUTPRODUCT.xlsx";//4.创建EasyExcel的excelWtire对象( 用于数据填充)ExcelWriter excelWriter = EasyExcel.write(response.getOutputStream()).head(ContractProductVo.class) //设置表头.withTemplate(path) //加载模板.build();//获取sheet对象WriteSheet sheet = EasyExcel.writerSheet().build();//5.调用方法完成填充map数据excelWriter.fill(map,sheet);//6.调用方法完成填充list数据excelWriter.fill(list,sheet);//7.属性资源，完成下载excelWriter.finish(); //下载excel文件，释放内存资源}

解析 Excel 文件

（1）配置实体类

创建实体类对象（用于解析封装对象），配置表头注解，EasyExcel 自动的根据注解配置获取文件中对应行的内容

• @ExcelIgnoreUnannotated：忽略默认表头配置
• @ExcelPropertym：配置表头

import cn.itcast.domain.BaseEntity;
import com.alibaba.excel.annotation.ExcelIgnoreUnannotated;
import com.alibaba.excel.annotation.ExcelProperty;import java.io.Serializable;
import java.util.List;/*** 合同下货物的实体类*  通过EasyExcel完成文件解析，在实体类上通过注解配置表头*  如果实体类中的属性，未配置@ExcelProperty*      默认按照属性的编写顺序，从excel中获取数据*      默认情况下，为配置注解的属性会影响数据封装*  在类上配置一个注解：忽略未配置注解的属性*/
@ExcelIgnoreUnannotated
@Data
public class ContractProduct extends BaseEntity implements Serializable {private String id;@ExcelProperty("货号")private String productNo;		//货号private String productImage;	//图片路径@ExcelProperty("货物描述")private String productDesc;		//货描@ExcelProperty("装率")private String loadingRate;		//报运：装率    1/3@ExcelProperty("箱数")private Integer boxNum;			//报运：箱数    100@ExcelProperty("包装单位")private String packingUnit;		//包装单位：PCS/SETS   支/箱@ExcelProperty("数量")private Integer cnumber;		//数量                            300private Integer outNumber;		//报运：出货数量            200private Integer finished;		//报运：是否完成		no@ExcelProperty("要求")private String productRequest;	//要求@ExcelProperty("单价")private Double price;			//单价private Double amount;			//总金额，冗余private Integer orderNo;		//排序号private String contractId;      //合同号@ExcelProperty("生产厂家")private String factoryName;		//厂家名称，冗余字段private String factoryId;private List<ExtCproduct> extCproducts ;	//货物和附件，一对多
}

（2）解析 Excel 文件

修改 ContractProductController 对象，完成 EasyExcel 的文件批量上传

	/*** 通过 EasyExcel 完成文件上传解析，批量货物保存*  参数：购销合同id*  参数：上传的excel文件对象*/@RequestMapping("/import")public String importExcel(String contractId, MultipartFile file) throws Exception {List<ContractProduct> list = EasyExcel.read(file.getInputStream()).head(ContractProduct.class) //设置表头，将数据转化为目标对象.sheet(0) //读取第一页数据.doReadSync(); //解析excel，获取所有的数据for (ContractProduct contractProduct : list) {System.out.println(contractProduct);contractProduct.setContractId(contractId);contractProduct.setCompanyId(getLoginCompanyId());contractProduct.setCompanyName(getLoginCompanyName());}contractProductService.saveAll(list);return  "redirect:/cargo/contractProduct/list.do?contractId="+contractId;}

拓展

csv 读写的支持

在3.0.0-beta1版本开始支持，读的时候会自动判断。写的时候指定 excelType 就行。

EasyExcel.write(fileName, DemoData.class)// 指定导出类型为csv.excelType(ExcelTypeEnum.CSV).sheet("模板").doWrite(() -> {// 分页查询数据return data();});