1. 背景
在实际开发中,经常会遇到这样的需求:
某些字段的值为 "未知"
、"N/A"
、"UNKNOWN"
等时,希望在 Excel 导出时显示为空。
EasyExcel 默认不会处理这种情况,因此需要实现 自定义转换器。
2. 实现步骤
2.1 定义注解
用于标记哪些值需要转为空,字段级别可灵活配置。
java
import java.lang.annotation.*;
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ExcelUnknownValue {
/**
* 需要当作"空"的值
*/
String[] values() default {"未知"};
}
2.2 编写转换器
继承 Converter<String>
,在导出时检查字段值是否在注解配置的"未知值"列表中。
typescript
import com.alibaba.excel.converters.Converter;
import com.alibaba.excel.enums.CellDataTypeEnum;
import com.alibaba.excel.metadata.data.WriteCellData;
import com.alibaba.excel.metadata.property.ExcelContentProperty;
import com.alibaba.excel.write.metadata.converter.WriteConverterContext;
import java.lang.reflect.Field;
public class ExcelUnknownValueConverter implements Converter<String> {
@Override
public Class<?> supportJavaTypeKey() {
return String.class;
}
@Override
public CellDataTypeEnum supportExcelTypeKey() {
return CellDataTypeEnum.STRING;
}
@Override
public WriteCellData<?> convertToExcelData(WriteConverterContext<String> context) {
String value = context.getValue();
if (value == null) {
return new WriteCellData<>("");
}
// 获取字段信息
ExcelContentProperty contentProperty = context.getContentProperty();
if (contentProperty != null) {
Field field = contentProperty.getField();
if (field != null) {
ExcelUnknownValue annotation = field.getAnnotation(ExcelUnknownValue.class);
if (annotation != null) {
for (String unknown : annotation.values()) {
if (unknown.equals(value)) {
return new WriteCellData<>("");
}
}
}
}
}
return new WriteCellData<>(value);
}
}
2.3 使用示例
less
public class UserExcelVo {
/**
* 组员状态
* 如果值是 "未知" 或 "N/A",导出为空
*/
@ExcelProperty(value = "组员状态", converter = ExcelUnknownValueConverter.class)
@ExcelUnknownValue(values = {"未知", "N/A"})
private String memberStatus;
/**
* 负责人
* 默认只处理 "未知"
*/
@ExcelProperty(value = "负责人", converter = ExcelUnknownValueConverter.class)
@ExcelUnknownValue
private String leader;
}
导出结果:
- 原始值
"未知"
→ Excel 显示为空 - 原始值
"N/A"
→ Excel 显示为空 - 其它值原样输出
3. 扩展
3.1 全局默认处理器
如果你希望所有 String
字段都自动把 "未知"
→ 空,可以在注册 EasyExcel.write()
时统一设置全局转换器,不需要在字段上写注解。
scss
EasyExcel.write(fileName, UserExcelVo.class)
.registerConverter(new ExcelUnknownValueConverter())
.sheet("人员信息")
.doWrite(data);
3.2 多值匹配
注解支持配置多个值:
ini
@ExcelUnknownValue(values = {"未知", "N/A", "UNKNOWN"})
这样更灵活,适配不同场景。
4. 总结
- 注解驱动:每个字段单独配置
- 通用性强:不仅限人员信息,任何字符串都能处理
- 灵活扩展:可支持全局默认逻辑