EasyExcel格式化映射注解和样式注解详解

一、概述

使用注解很简单，只要在对应的实体类上面加上注解即可。

也就是说使用实体类模型来读写Excel文件时，可以通过注解来控制实体类字段和Excel列之间的对应关系。

二、ExcelProperty

2.1 作用

ExcelProperty注解用于匹配excel和实体类字段之间的关系。

可以作用于字段上。

2.1 注解参数

名称	默认值	描述
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) 方法即可

2.3 使用示例

@Getter
@Setter
@EqualsAndHashCode
public class DemoData {
    @ExcelProperty("字符串标题")
    private String title;
    
    // 在这个字段前面加上 自定义三个字
    @ExcelProperty(value = "conver的使用", converter = CustomStringStringConverter.class)
    private String convert;
    
    @ExcelProperty(value = "日期标题", index = 3)
    private Date date;
    
    @ExcelProperty(value = "数字标题", index = 5)
    private Double doubleData;
}

import com.alibaba.excel.converters.Converter;
import com.alibaba.excel.converters.ReadConverterContext;
import com.alibaba.excel.converters.WriteConverterContext;
import com.alibaba.excel.enums.CellDataTypeEnum;
import com.alibaba.excel.metadata.data.WriteCellData;

/**
 * 定义一个字符串转换器，需要实现Converter接口并且传递需要转换的泛型
 */
public class CustomStringStringConverter implements Converter<String> {
    
    // 所支持的java类型
    @Override
    public Class<?> supportJavaTypeKey() {
        return String.class;
    }

    // 所支持的Excel枚举类型
    @Override
    public CellDataTypeEnum supportExcelTypeKey() {
        return CellDataTypeEnum.STRING;
    }

    /**
     * 这里读的时候会调用
     * @param context	上下文对象  可以获取当前读的单元格的文字内容
     * @return			格式化后的值
     */
    @Override
    public String convertToJavaData(ReadConverterContext<?> context) {
        return "自定义：" + context.getReadCellData().getStringValue();
    }

    /**
     * 这里是写的时候会调用 通常情况可以不用管
     * @return
     */
    @Override
    public WriteCellData<?> convertToExcelData(WriteConverterContext<String> context) {
        return new WriteCellData<>(context.getValue());
    }

}

注意点：

1）关于index

如果所有字段都不加index的话，默认index会从0开始，最早的声明的字段的名字的index的值就是0。

之后字段的index就从0开始递增，依次类推。index是几决定了该字段数据会赋值给Excel中的第几列。

如果不想按这个顺序把数据写到Excel当中。那么就可以手动设置index的值，把字段写到想要的列中去。

如果index相同，直接会抛出异常，因为程序无法判断这个列放那个字段。

2）关于order

index和order虽然都决定顺序，但是两者语义不同：

如果order和index同时使用，index优先占据位置，order再进行排序。

index=-1的话，使用jJava进行默认排序。

order的默认值为Integer.MAX_VALUE，其中order的值越小，列越靠前。

三、ExcelIgnore

3.1 作用

默认所有字段都会和excel中对应列去匹配，但是加了这个注解EasyExcel会忽略该字段，使之不写入Excel。

可以作用于字段上。

3.2 使用示例

@Getter
@Setter
@EqualsAndHashCode
public class DemoData {

    // 忽略这个字段，不写入Excel当中
    @ExcelIgnore
    private String ignore;
}

四、ExcelIgnoreUnannotated

4.1 作用

默认不管加不加ExcelProperty的注解的所有字段都会参与读写。

加了@ExcelIgnoreUnannotated注解以后，不加ExcelProperty注解的字段就不会参与读写。

看起来和@ExcelIgnore注解作用类似，只是用法不同。

可以作用于类上。

4.2 使用示例

@data
@ExcelIgnoreUnannotated
public class DemoData {
    @ExcelProperty("字符串标题")
    private String string;
    @ExcelProperty("日期标题")
    private Date date;
    @ExcelProperty("数字标题")
    private Double doubleData;
	
    private String ignore;
}

五、DateTimeFormat

5.1 作用

日期转换，用String去接收excel日期格式的数据会调用这个注解,参数如下：

可以作用于字段上。

5.2 注解参数

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

不写use1904windowing这个参数默认就是1900的时间格式，一般也就是使用1900的时间格式

5.2 使用示例

@data
public class DemoData {
    @ExcelProperty("字符串标题")
    private String string;
    
  
    @DateTimeFormat("yyyy年MM月dd日HH时mm分ss秒")
    @ExcelProperty("日期标题")
    private Date date;

}

六、NumberFormat

6.1 作用

数字转换，用String去接收excel数字格式的数据会调用这个注解。

可以作用于字段上。

6.2 注解参数

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

6.3 使用示例

@data
@ExcelIgnoreUnannotated
public class DemoData {
    @ExcelProperty("字符串标题")
    private String string;

    @NumberFormat("#.##%")		// 使用百分比格式格式化这个数字
    @ExcelProperty("数字")
    private Double doubleData;
}

七、ColumnWith

7.1 作用

设置列宽度。

可以作用于类或者字段上。

7.2 注解参数

@ColumnWith 只有一个参数value，value的单位是字符长度，最大可以设置255个字符。

因为一个excel单元格最大可以写入的字符个数就是255个字符。

7.3 使用示例

@data
public class DemoData {
    @ExcelProperty("字符串标题")
    @ColumnWidth(15)			//设置列宽为15个字符	
    private String string;
}

注解作用于类上将会设置全部单元格的宽度为15

注解作用于字段上会设置字段所对应的Excel列的宽度为15

八、ContentRowHeight

8.1 作用

用于设置行高。

可以作用于类上。

8.2 注解参数

只有一个参数value，它的值是Excel文件中的行高。值为-1时代表自动设置行高。

8.3 使用示例

@data
@ContentRowHeight(15)
public class DemoData {
    @ExcelProperty("字符串标题")
    private String string;
}

九、ContentFontStyle / HeadFontStyle

9.1 作用

ContentFontStyle：用于设置单元格内容字体格式的注解

HeadFontStyle ：设置标题的字体样式。

都可以作用于类或者字段上，注解参数也完全一致。

9.2 注解参数

名称	默认值	描述
fontName	“”	字体名称
fontHeightInPoints	-1	字体高度
italic	BooleanEnum.DEFAULT	是否斜体
strikeout	BooleanEnum.DEFAULT	是否设置删除水平线
color	-1	字体颜色
typeOffset	-1	偏移量
underline	-1	是否添加下划线
bold	-1	是否加粗
charset	BooleanEnum.DEFAULT	编码格式

9.3 使用示例

@data
public class DemoData {
    // 设置当前列的字体颜色为10(红色)   字体为斜体
    @ContentFontStyle(color = 10, italic = BooleanEnum.TRUE)
    @ExcelProperty("字符串标题")
    private String string;
}

这里的颜色值可以在IndexedColors.RED这个枚举中找到。

如果是使用代码可以直接IndexedColors.RED.getIndex()设置颜色值，注解的话，只能直接写数字

十、ContentStyle / HeadStyle

10.1 作用

ContentStyle：设置单元格内容样式注解。

HeadStyle ：设置标题样式。

都可以作用于类或者字段上，注解参数也完全一致。

10.2 注解参数

名称	默认值	描述
dataFormat	-1	数据格式
hidden	BooleanEnum.DEFAULT	设置单元格隐藏
locked	BooleanEnum.DEFAULT	设置单元格使用此样式锁定
quotePrefix	BooleanEnum.DEFAULT	设在单元格前面增加`符号，数字或公式将以字符串形式展示
horizontalAlignment	HorizontalAlignmentEnum.DEFAULT	设置是否水平居中
wrapped	BooleanEnum.DEFAULT	设置文本是否应换行。将此标志设置为true通过在多行上显示使单元格中的所有内容可见
verticalAlignment	VerticalAlignmentEnum.DEFAULT	设置是否垂直居中
rotation	-1	设置单元格中文本旋转角度。03版本的Excel旋转角度区间为-90°90°，07版本的Excel旋转角度区间为0°180°
indent	-1	设置单元格中缩进文本的空格数
borderLeft	BorderStyleEnum.DEFAULT	设置左边框的样式
borderRight	BorderStyleEnum.DEFAULT	设置右边框样式
borderTop	BorderStyleEnum.DEFAULT	设置上边框样式
borderBottom	BorderStyleEnum.DEFAULT	设置下边框样式
leftBorderColor	-1	设置左边框颜色
rightBorderColor	-1	设置右边框颜色
topBorderColor	-1	设置上边框颜色
bottomBorderColor	-1	设置下边框颜色
fillPatternType	FillPatternTypeEnum.DEFAULT	设置填充类型
fillBackgroundColor	-1	设置背景色
fillForegroundColor	-1	设置前景色
shrinkToFit	BooleanEnum.DEFAULT	设置自动单元格自动大小

10.3 使用示例

@data
public class DemoData {
    // 设置单元格的左边框颜色为10(红色)   数据格式为0.00
    @ContentStyle(leftBorderColor = 10, dataFormat = 0.00)
    @ExcelProperty("字符串标题")
    private String string;
}

这里的颜色值可以在IndexedColors.RED这个枚举中找到。

数据格式的值可以在类com.alibaba.excel.constant.BuiltinFormats的字段BUILTIN_FORMATS_CN中找到

十一、ContentLoopMerge

11.1 作用

用于合并单元格。

可以作用于字段上。

11.2 注解参数

名称	默认值	描述
eachRow	1	用于设置当前列每隔几行合并一次单元格
columnExtend	1	用于合并列

10.3 使用示例

@data
public class DemoData {
    // 单前列每隔两行合并一次单元格
    @ContentLoopMerge(eachRow = 2)
    @ExcelProperty("字符串标题")
    private String string;
}