解读若依框架中的`@Excel` 和 `@Excels` 注解

news2025/1/10 15:01:46

文章目录

一、`@Excels` 注解详解
- 1.1 适用场景
- 1.2 作用与好处
二、`@Excel` 注解详解
- 2.1 核心属性解析
- 2.2 高级用法
- 2.3 综合应用案例
三、总结

解读若依框架中的 @Xss 注解博客：解读若依框架中的 @Xss 注解

接下来我们将对若依框架中的 @Excel 和 @Excels 注解进行更加详细的解析，并结合实际开发中的常见应用场景，帮助开发者更好地理解这些注解的功能及使用方法。我们将从注解的各个属性出发，逐一分析如何在实际项目中灵活运用，并通过实际代码示例来说明如何有效地配置Excel数据导出和导入功能。

一、`@Excels` 注解详解

@Excels 注解是若依框架提供的一个容器注解，它的作用是将多个 @Excel 注解封装在一起。通过这个注解，开发者可以在一个字段上同时应用多个Excel相关的导出配置，简化代码结构并避免冗余。

1.1 适用场景

假设我们有一个用户信息实体类，需要对多个字段进行Excel导出操作。为了避免重复代码，@Excels 注解非常有用，它允许我们在同一个字段上定义多个Excel字段配置。

@Excels({
    @Excel(name = "用户名", sort = 1),
    @Excel(name = "性别", sort = 2, readConverterExp = "0=男,1=女"),
    @Excel(name = "年龄", sort = 3),
    @Excel(name = "创建时间", sort = 4, dateFormat = "yyyy-MM-dd")
})
private List<User> users;

上面的代码通过 @Excels 注解集将多个 @Excel 注解进行了封装，用户信息字段在导出时将具有不同的配置。这使得开发者可以在多个字段上同时使用Excel导出的注解，避免为每个字段重复配置。

1.2 作用与好处

简化配置：将多个字段的配置集中在一起，减少了代码的冗余，使得Excel导出的配置更加清晰。
代码易维护：当多个字段有相同的导出配置时，可以在 @Excels 中统一管理，减少了代码的重复修改。
提高可读性：集中式配置使代码结构更加直观，其他开发人员阅读时更加容易理解字段的配置。

二、`@Excel` 注解详解

@Excel 注解是若依框架中用于配置Excel导出字段的核心注解，功能强大且灵活。它为开发者提供了丰富的属性，允许我们对每个字段的显示名称、格式、排序等进行详细的设置。

2.1 核心属性解析

sort()：字段的排序，决定Excel表格中字段的显示顺序。该属性值越小，字段越早显示，默认值为 Integer.MAX_VALUE。通过设置排序值，开发者可以灵活控制字段的排列顺序。
```
@Excel(name = "用户名", sort = 1)
private String username;
```
name()：设置字段在Excel中的列标题，也就是表头的名称。通常情况下，字段的名称会直接作为列头名称，但通过 name 属性，我们可以为字段指定一个更合适的表头名称。
```
@Excel(name = "用户姓名")
private String userName;
```
dateFormat()：指定日期字段的格式。如果字段类型是 Date 或 LocalDateTime，则可以使用此属性设置导出时的日期格式。例如，设置为 yyyy-MM-dd 将日期格式化为 “2025-01-09”。
```
@Excel(name = "创建时间", dateFormat = "yyyy-MM-dd")
private LocalDateTime createdTime;
```
readConverterExp()：字段值转换表达式，允许通过配置值映射来转换字段值。例如，性别字段的值为 0 和 1，通过 readConverterExp 可以转换为 “男” 和 “女”。
```
@Excel(name = "性别", readConverterExp = "0=男,1=女")
private Integer gender;
```
separator()：当字段值为字符串数组时，可以通过该属性指定分隔符。默认情况下，多个字符串会通过逗号 , 分隔，开发者也可以自定义分隔符。
```
@Excel(name = "兴趣爱好", separator = ";")
private String[] hobbies;
```
scale() 和 roundingMode()：这两个属性与 BigDecimal 类型相关，用于设置数字精度。scale 设置数字的精度，roundingMode 控制数字的舍入规则。默认情况下，scale 为 -1，表示不启用精度控制。
```
@Excel(name = "金额", scale = 2, roundingMode = BigDecimal.ROUND_HALF_UP)
private BigDecimal amount;
```
width() 和 height()：这两个属性分别设置列的宽度和行的高度。Excel表格的显示效果常常需要根据内容的大小进行调整，这两个属性提供了灵活的设置方式。
```
@Excel(name = "订单号", width = 20, height = 16)
private String orderNumber;
```
suffix()：该属性允许为数字字段添加后缀，例如在金额字段后添加 “%” 符号。适用于百分比等需要附加单位的场景。
```
@Excel(name = "增长率", suffix = "%")
private Double growthRate;
```
defaultValue()：当字段值为空时，设置字段的默认值。例如，订单的状态字段如果为空，可以默认填充为 未完成。
```
@Excel(name = "订单状态", defaultValue = "未完成")
private String orderStatus;
```
prompt()：设置字段的提示信息。此属性常用于在用户导出Excel模板时提供提示，帮助用户了解字段内容的填写要求。
```
@Excel(name = "备注", prompt = "请输入备注信息")
private String remarks;
```
isExport()：标识字段是否需要导出。当我们需要导出模板并让用户手动填写内容时，可以将该属性设置为 false，以便该字段只出现在模板中，不会导出数据。
```
@Excel(name = "备注", isExport = false)
private String remarks;
```
targetAttr()：该属性允许从其他对象获取属性值。例如，如果字段引用了其他类的属性，可以通过 targetAttr 指定属性路径以获取值。
```
@Excel(name = "用户地址", targetAttr = "user.address")
private User user;
```

2.2 高级用法

cellType()：指定字段的Excel单元格类型，常见的类型包括 ColumnType.STRING（字符串）、ColumnType.NUMERIC（数字）、ColumnType.IMAGE（图片）和 ColumnType.TEXT（文本）。例如，我们可以将某些数字字段设置为 NUMERIC 类型，确保Excel格式正确。
```
@Excel(name = "金额", cellType = ColumnType.NUMERIC)
private BigDecimal amount;
```

headerBackgroundColor() 和 headerColor()：设置Excel列头的背景色和字体颜色，帮助我们自定义导出的Excel表格的外观。

@Excel(name = "用户姓名", headerBackgroundColor = IndexedColors.YELLOW, headerColor = IndexedColors.BLACK)
private String username;

align()：设置单元格内容的对齐方式，支持 CENTER、LEFT 和 RIGHT 等常见对齐方式。
```
@Excel(name = "金额", align = HorizontalAlignment.RIGHT)
private BigDecimal amount;
```

2.3 综合应用案例

假设我们正在开发一个订单管理系统，下面是一个完整的 @Excel 注解使用示例：

public class Order {
    @Excel(name = "订单号", sort = 1, cellType = ColumnType.STRING, width = 20)
    private String orderNumber;

    @Excel(name = "客户姓名", sort = 2)
    private String customerName;

    @Excel(name = "订单金额", sort = 3, cellType = ColumnType.NUMERIC, scale = 2, roundingMode = BigDecimal.ROUND_HALF_UP)
    private BigDecimal amount;

    @Excel(name = "订单状态", sort = 4, readConverterExp = "0=未完成,1=已完成")
    private Integer status;

    @Excel(name = "创建时间", sort = 5, dateFormat = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @Excel(name = "备注", sort = 6, isExport = false)
    private String remarks;
}