EasyPoi的核心映射工具：@Excel注解详解

文章目录

在EasyPoi框架中，@Excel注解是实现Java对象与Excel表格之间数据映射的核心桥梁。通过简单的注解配置，开发者可以轻松控制Excel的导入导出行为，包括列名映射、格式转换、样式控制等复杂功能，大幅提升开发效率。

1、基础属性详解

@Excel注解提供了丰富的属性来控制Excel列的各种行为，从基本的列名映射到高级的格式控制，每个属性都有其特定的应用场景。

1.1、核心映射属性

name
作用：定义Excel列的表头名称
类型：String
示例：@Excel(name = "员工姓名")
注意：当Excel中存在重复列名时，需要配合fixedIndex使用
orderNum
作用：指定列在Excel中的显示顺序
类型：String
示例：@Excel(name = "ID", orderNum = "0")
默认值："0"
fixedIndex
作用：直接指定Excel列的索引位置（从0开始）
类型：int
示例：@Excel(name = "数量", fixedIndex = 2)
应用场景：解决重复列名问题，精确匹配列位置
width & height
width：定义列宽度（单位：字符）
height：定义行高（单位：磅，仅导出有效）
示例：@Excel(name = "用户名", width = 20, height = 15)
注意：height属性主要用于控制导出时的行高显示

1.2、数据处理属性

这些属性用于控制数据的格式转换、值替换等处理逻辑，确保数据在Excel和Java对象之间正确转换。

时间格式
format：统一设置导入导出格式
exportFormat：仅控制导出格式
importFormat：仅控制导入格式
示例：@Excel(name = "日期", format = "yyyy-MM-dd")
值替换
replace：实现值映射转换
格式："导出值_导入值"
示例：@Excel(name = "性别", replace = {"男_1", "女_0"})
效果：导出时1→男，导入时男→1
numFormat
数字格式化，使用DecimalFormat模式
示例："#,##0.00"
dict
数据字典转换
示例："1_男,2_女"
将编码转为可读文本
suffix
文本后缀添加
示例：suffix = "%"
90 → "90%"
databaseFormat
数据库时间格式
默认："yyyMMddHHmmss"
用于String类型时间转换

2、样式与高级功能

除了基本的数据映射，@Excel注解还提供了丰富的样式控制和高级功能，满足复杂的Excel操作需求。

属性	类型	默认值	说明
name	String	null	列名
needMerge	boolean	fasle	纵向合并单元格
orderNum	String	"0"	列的排序,支持name_id
replace	String[]	{}	值得替换导出是{a_id,b_id} 导入反过来
savePath	String	"upload"	导入文件保存路径
type	int	1	导出类型 1 是文本 2 是图片,3 是函数,10 是数字默认是文本
width	double	10	列宽
height	double	10	列高,后期打算统一使用@ExcelTarget的height,这个会被废弃,注意
isStatistics	boolean	fasle	自动统计数据,在追加一行统计,把所有数据都和输出这个处理会吞没异常,请注意这一点
isHyperlink	boolean	false	超链接,如果是需要实现接口返回对象
isImportField	boolean	true	校验字段,看看这个字段是不是导入的Excel中有,如果没有说明是错误的Excel,读取失败,支持name_id
exportFormat	String	""	导出的时间格式,以这个是否为空来判断是否需要格式化日期
importFormat	String	""	导入的时间格式,以这个是否为空来判断是否需要格式化日期
format	String	""	时间格式,相当于同时设置了exportFormat 和 importFormat
databaseFormat	String	"yyyyMMddHHmmss"	导出时间设置,如果字段是Date类型则不需要设置数据库如果是string类型,这个需要设置这个数据库格式,用以转换时间格式输出
numFormat	String	""	数字格式化,参数是Pattern,使用的对象是DecimalFormat
imageType	int	1	导出类型 1 从file读取 2 是从数据库中读取默认是文件同样导入也是一样的
suffix	String	""	文字后缀,如% 90 变成90%
isWrap	boolean	true	是否换行即支持\n
mergeRely	int[]	{}	合并单元格依赖关系,比如第二列合并是基于第一列则{1}就可以了
mergeVertical	boolean	fasle	纵向合并内容相同的单元格
isColumnHidden	boolean	false	导出时是否隐藏该列

3、实战应用示例

通过一个完整的实体类示例，展示@Excel注解在实际项目中的综合应用。

java 复制代码

import cn.afterturn.easypoi.excel.annotation.Excel;
import java.util.Date;

public class Employee {
    
    // 基础映射：ID列，宽度10字符，顺序第一列
    @Excel(name = "员工编号", width = 10, orderNum = "0")
    private Long id;
    
    // 文本处理：姓名列，自动换行，宽度25字符
    @Excel(name = "姓名", orderNum = "1", width = 25, isWrap = true)
    private String name;
    
    // 值替换：性别编码转换，1→男，2→女
    @Excel(name = "性别", orderNum = "2", 
           replace = {"男_1", "女_2"}, suffix = "生")
    private Integer gender;
    
    // 时间格式：统一导入导出格式
    @Excel(name = "出生日期", orderNum = "3", 
           format = "yyyy-MM-dd", width = 20)
    private Date birthDate;
    
    // 数字格式化：身高保留两位小数
    @Excel(name = "身高(cm)", orderNum = "4", 
           height = 15, numFormat = "0.00")
    private Double height;
    
    // 图片处理：从文件读取图片
    @Excel(name = "照片", orderNum = "5", 
           type = 2, imageType = 1, savePath = "photos")
    private String photoPath;
    
    // 导入控制：该字段不参与导入
    @Excel(name = "邮箱", orderNum = "6", 
           isImportField = false)
    private String email;
    
    // 合并单元格：部门相同则纵向合并
    @Excel(name = "所属部门", orderNum = "7", 
           needMerge = true)
    private String department;
    
    // 固定索引：解决重复列名问题
    @Excel(name = "备注", orderNum = "8", 
           fixedIndex = 8, width = 40)
    private String remark;
    
    // 构造器、Getter和Setter方法省略
}

4、最佳实践与注意事项

掌握@Excel注解的高级用法和避坑指南，让Excel操作更加得心应手。

重复列名处理：当Excel中存在相同列名时，必须使用fixedIndex属性指定列索引，否则会导致数据映射错误或丢失。
性能优化：对于大数据量导出，合理设置needMerge和isWrap属性，避免过度合并和换行影响性能。
版本兼容：不同版本的EasyPoi可能对某些属性的支持有差异，建议使用稳定版本（如4.1.3）并参考对应版本的官方文档。
图片处理：使用type = 2导出图片时，确保savePath路径存在且具有读写权限，同时注意图片大小控制。
日期格式：优先使用format属性统一设置时间格式，避免导入导出格式不一致导致的数据解析错误。
字典转换：对于状态码、类型等枚举字段，使用dict或replace属性实现编码与文本的自动转换，提升代码可读性。

通过合理组合这些属性，@Excel注解能够满足绝大多数Excel导入导出需求，从简单的数据映射到复杂的样式控制，真正实现了"注解即配置"的开发理念。

"人的一生会经历很多痛苦，但回头想想，都是传奇"。