EasyExcel 自定义转换器（某些字段的值为 "N/A"、"UNKNOWN" 等时，希望在 Excel 导出时显示为空。）

1. 背景

在实际开发中，经常会遇到这样的需求：
某些字段的值为 "未知"、"N/A"、"UNKNOWN" 等时，希望在 Excel 导出时显示为空。

EasyExcel 默认不会处理这种情况，因此需要实现 自定义转换器。

2. 实现步骤

2.1 定义注解

用于标记哪些值需要转为空，字段级别可灵活配置。

import java.lang.annotation.*;

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ExcelUnknownValue {
    /**
     * 需要当作“空”的值
     */
    String[] values() default {"未知"};
}

2.2 编写转换器

继承 Converter<String>，在导出时检查字段值是否在注解配置的“未知值”列表中。

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 使用示例

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() 时统一设置全局转换器，不需要在字段上写注解。

EasyExcel.write(fileName, UserExcelVo.class)
        .registerConverter(new ExcelUnknownValueConverter())
        .sheet("人员信息")
        .doWrite(data);

3.2 多值匹配

注解支持配置多个值：

@ExcelUnknownValue(values = {"未知", "N/A", "UNKNOWN"})

这样更灵活，适配不同场景。

4. 总结

• 注解驱动：每个字段单独配置
• 通用性强：不仅限人员信息，任何字符串都能处理
• 灵活扩展：可支持全局默认逻辑