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

落日映苍穹つ 2024-04-01 19:05 85阅读 0赞

### 一、概述 ###

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

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

### 二、ExcelProperty ###

#### 2.1 作用 ####

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

**可以作用于字段上。**

#### 2.1 注解参数 ####

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

#### 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`的话，使用j`Java`进行默认排序。

`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 注解参数 ####

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

> 不写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 注解参数 ####

<table> 
 <thead> 
  <tr> 
   <th>名称</th> 
   <th>默认值</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>空</td> 
   <td>参照<code>java.text.DecimalFormat</code>书写即可</td> 
  </tr> 
  <tr> 
   <td>roundingMode</td> 
   <td>RoundingMode.HALF_UP</td> 
   <td>格式化的时候设置舍入模式</td> 
  </tr> 
 </tbody> 
</table>

#### 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 注解参数 ####

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

#### 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 注解参数 ####

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

#### 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 注解参数 ####

<table> 
 <thead> 
  <tr> 
   <th>名称</th> 
   <th>默认值</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>eachRow</td> 
   <td>1</td> 
   <td>用于设置当前列每隔几行合并一次单元格</td> 
  </tr> 
  <tr> 
   <td>columnExtend</td> 
   <td>1</td> 
   <td>用于合并列</td> 
  </tr> 
 </tbody> 
</table>

#### 10.3 使用示例 ####

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