轻松搞定Excel操作: 掌握EasyPoi中@Excel神注解的使用秘籍！

EasyPoi的@Excel注解具有多个属性，下表总结了这些属性及其作用。请注意，随着EasyPoi版本的更新，可能会有新的属性加入或旧的属性被修改，以下信息基于EasyPoi的一个特定版本，可能不涵盖所有的属性和最新的变动。

1、注解属性如下

属性	类型	用途	示例
name	String	定义Excel列的名称，用于Excel表头。	@Excel(name = "学生姓名")
width	double	定义列宽度，单位为字符。	@Excel(width = 20)
height	double	定义行高，单位为磅。仅对导出有效。	@Excel(height = 10)
orderNum	String	定义列的显示顺序。	@Excel(orderNum = "1")
needMerge	boolean	表示是否需要合并单元格。	@Excel(needMerge = true)
mergeVertical	boolean	表示是否纵向合并单元格。	@Excel(mergeVertical = true)
mergeRely	int[]	指定合并单元格时依赖的列，数组中的数字为列的索引。	@Excel(mergeRely = {1})
isImportField	String	定义是否为导入字段，“true"或"false”。	@Excel(isImportField = "true")
isWrap	boolean	定义是否自动换行。	@Excel(isWrap = true)
exportFormat	String	定义导出时的格式化模式，如日期格式。	@Excel(exportFormat = "yyyy-MM-dd")
importFormat	String	定义导入时的格式化模式。	@Excel(importFormat = "yyyy-MM-dd")
imageType	int	定义图片类型（如1表示从文件导入，2表示从数据库导入）。	@Excel(imageType = 1)
suffix	String	定义文本后缀，如在文本后添加特定的后缀。	@Excel(suffix = "%")
type	int	定义字段类型（如1表示文本，2表示图片）。	@Excel(type = 1)
enumExportField	String	定义枚举导出时，调用枚举字段的哪个方法获取实际的值。	@Excel(enumExportField = "getText")
savePath	String	定义图片保存路径，仅对导入有效。	@Excel(savePath = "/tmp")
dateFormat	String	简化的日期格式设置，简化的exportFormat/importFormat。	@Excel(dateFormat = "yyyy-MM-dd")
use1904windowing	boolean	定义是否使用1904年日期窗口。	@Excel(use1904windowing = true)
fixedIndex	int	指定Excel列的索引，从0开始，用于导入时准确匹配列位置。	@Excel(fixedIndex = 0)
groupName	String	用于分组导出/导入时定义的组名。	@Excel(groupName = "group1")
dict	String	用于指定数据字典，将数据转换为对应的文本值。	@Excel(dict = "sex=1_男,2_女")
replace	String[]	定义要替换的值，用于导出时将字段值替换为指定的文本值。	@Excel(replace = {"男_1", "女_2"})
statistics	boolean	定义是否进行统计，用于对数字字段进行求和统计。	@Excel(statistics = true)

2、示例

EasyPoi的@Excel注解提供了丰富的属性来控制Excel文件的导入导出行为。

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

public class Employee {

    // 基本用法：定义列名称和顺序
    @Excel(name = "员工编号", orderNum = "0")
    private Long id;

    // 使用width属性指定列宽
    @Excel(name = "姓名", orderNum = "1", width = 25)
    private String name;

    // 使用replace属性进行值替换和suffix设置文本后缀
    @Excel(name = "性别", orderNum = "2", replace = {"男_1", "女_2"}, suffix = "生")
    private String gender;

    // 使用dateFormat和exportFormat控制日期格式
    @Excel(name = "出生日期", orderNum = "3", exportFormat = "yyyy/MM/dd", width = 20)
    private Date birthDate;

    // 使用height控制行高
    @Excel(name = "身高(cm)", orderNum = "4", height = 15)
    private Double height;

    // 使用type来控制导出字段类型，例如导出图片
    @Excel(name = "照片", type = 2, imageType = 1, savePath = "/photos/", orderNum = "5")
    private String photoPath;

    // 使用isImportField控制导入时是否忽略该字段
    @Excel(name = "邮箱", orderNum = "6", isImportField = "false")
    private String email;

    // 使用needMerge进行单元格合并
    @Excel(name = "所属部门", orderNum = "7", needMerge = true)
    private String department;

    // 其他特殊用法，如fixedIndex确定导入时列的匹配索引
    @Excel(name = "备注", orderNum = "8", fixedIndex = 8, width = 40)
    private String remark;

    // 构造器、Getter和Setter方法省略
}

在这个综合示例中，Employee类代表了员工信息，每一个属性上的@Excel注解都演示了不同的属性用法：

• name和orderNum设置列名和列的顺序。
• width和height控制列宽和行高。
• replace和suffix用于值替换和文本后缀的添加。
• exportFormat定制导出的日期格式。
• type和imageType用于导出图片类型的字段。
• isImportField指示某字段是否参与导入过程。
• needMerge用于单元格合并。
• fixedIndex在导入数据时用来确保按照指定的列索引顺序匹配列数据，而不是依靠列的名称。

这个示例并没有展示所有属性，但覆盖了大部分常用的功能。对于特定的属性用法，如dict、enumExportField、mergeVertical等，推荐查阅官方文档或源代码，因为它们有时需要结合具体使用场景来理解。

---

3、dict属性说明及用法

在EasyPoi中，@Excel注解的dict属性可以用于在导出数据时将字段值转换为对应的字典文本。这个功能特别适用于那些存储在数据库中为编码或ID但在显示时需要转换为人类可读文本的场景，如性别、状态码等。

使用场景:
假设你有一个员工信息管理系统，其中员工的性别在数据库中以1和2存储，分别代表男和女。在导出员工信息为Excel文件时，你希望在性别列显示为“男”和“女”而不是1和2。

举例:
首先，你需要定义一个员工实体类Employee，并使用@Excel注解指定导出信息。

import cn.afterturn.easypoi.excel.annotation.Excel;

public class Employee {

    @Excel(name = "姓名", orderNum = "0")
    private String name;

    // 使用dict属性实现性别的编码到文本的转换
    @Excel(name = "性别", orderNum = "1", dict = "1_男,2_女")
    private String gender;

    // 其他属性和对应的getter和setter方法省略

    // 构造函数、getter和setter方法省略
}

在这个例子中，@Excel注解的dict属性被设置为"1_男,2_女"。这意味着在导出Excel文件时，如果原数据中gender字段的值为1，它会被自动替换为“男”；如果值为2，它会被自动替换为“女”。

注意:

• dict属性的格式遵循"key_value"模式，多个键值对之间用逗号,分隔。
• 使用dict属性进行值转换仅影响导出操作，即将Java对象中的数据导出到Excel文件时的展现形式。在导入Excel文件数据到Java对象时，dict属性不会应用转换逻辑，需使用其他方式处理。
• 实际开发中，字典数据可能会存储在数据库或配置文件中，需要在导出数据前将这些字典数据加载并应用到导出逻辑中。dict属性提供了一种快速在注解中直接定义转换规则的方式，适合于转换规则相对固定且简单的场景。

4、 enumExportField

在EasyPoi中，@Excel注解的enumExportField属性用于在导出数据时将枚举类型的字段值转换为枚举中指定的属性值。这个功能特别适用于那些在Java中用枚举类型表示的字段，而在导出Excel时希望显示枚举的某个特定属性（如描述信息）而不是枚举的名称。

使用场景

假设你有一个订单管理系统，其中包含一个订单实体，订单状态使用枚举类型表示。在数据库中，这个状态可能是以枚举的序号或名称存储的，但在导出订单信息为Excel文件时，你希望在订单状态列显示更友好的文本描述，而不是枚举的名称或序号。

举例

首先，定义一个表示订单状态的枚举类OrderStatus，其中包括状态对应的描述信息。

public enum OrderStatus {
    PENDING("待处理"),
    PROCESSING("处理中"),
    SHIPPED("已发货"),
    DELIVERED("已送达");

    private final String description;

    OrderStatus(String description) {
        this.description = description;
    }

    public String getDescription() {
        return description;
    }
}

然后，定义一个订单实体类Order，并使用@Excel注解指定导出信息，同时使用enumExportField属性将订单状态枚举转换为其描述文本。

import cn.afterturn.easypoi.excel.annotation.Excel;

public class Order {

    @Excel(name = "订单编号", orderNum = "0")
    private String orderId;

    // 使用enumExportField属性指定枚举转换为描述文本
    @Excel(name = "订单状态", orderNum = "1", enumExportField = "description")
    private OrderStatus status;

    // 其他属性和对应的getter和setter方法省略

    // 构造函数、getter和setter方法省略
}

在这个例子中，@Excel注解的enumExportField属性被设置为"description"。这意味着在导出Excel文件时，如果原数据中status字段的值为某个OrderStatus枚举实例，它会被自动替换为该枚举实例的description属性值。

注意

• enumExportField属性指定了枚举类中要导出的字段名称，该字段应该是枚举类中的一个属性。
• 使用enumExportField属性进行值转换仅影响导出操作，在导入Excel文件数据到Java对象时，enumExportField属性不会应用转换逻辑。
• 这个属性为开发者提供了一种灵活的方式来控制枚举类型数据在导出Excel时的显示，使得导出的数据更加直观和友好。

---

5、imageType

在EasyPoi中，@Excel注解的imageType属性用于处理导出到Excel文件中的图片类型字段。这个属性允许开发者指定如何将Java对象中的图片信息（通常是图片的路径或者是二进制数据）导出到生成的Excel文件中。使用场景主要包括将实体类中表示图片信息的字段正确地以图片形式展示在Excel中，而不是仅仅作为文本或者链接。

使用场景

假设你正在开发一个员工管理系统，你需要导出包含员工照片的Excel报告。在这种情况下，你的员工实体可能包含一个字段，用于存储员工照片的路径或者照片的二进制数据。使用@Excel注解的imageType属性，你可以确保这些员工照片在Excel文件中以图片形式被正确导出和展示。

举例

假设有一个Employee类，其中包含员工的照片信息。这个照片信息可以是一个指向图片文件的路径，或者直接是图片的二进制数据。下面是如何使用@Excel注解及其imageType属性的一个示例：

import cn.afterturn.easypoi.excel.annotation.Excel;

public class Employee {

    @Excel(name = "员工姓名", orderNum = "0")
    private String name;

    // 假设这里使用图片路径
    @Excel(name = "照片", orderNum = "1", type = 2, imageType = 1, width = 20, height = 30)
    private String photoPath;

    // 假设这里使用二进制数据
    // @Excel(name = "照片", orderNum = "1", type = 2, imageType = 2, width = 20, height = 30)
    // private byte[] photoBytes;

    // 构造函数、getter和setter方法省略
}

在这个例子中，@Excel注解用于photoPath字段，并设置了几个关键属性：

• type = 2：表示这个字段是图片。
• imageType = 1：表示图片来源是一个文件路径（如果是二进制数据，则设置为imageType = 2）。
• width和height：指定了图片在Excel中的宽度和高度。

注意

• 当使用imageType = 1时，确保提供的路径是有效的，并且EasyPoi能够访问到这些图片文件。
• 当使用imageType = 2时，确保相关字段确实包含了有效的图片二进制数据。
• 考虑到Excel文件的大小和性能，应当谨慎处理高分辨率或大尺寸的图片。