[Task] ExcelProperty添加分组字段，可以根据传参动态渲染表头数量

[ESCATS]

Motivation

如下案例：通过types定义每个字段，当我需要导出的时候传入all则渲染所有字段表头，传入school则只导出school相关的表头及数据
`package cn.idev.excel.test.demo.write;

import cn.idev.excel.annotation.ExcelProperty;
import lombok.Data;

@DaTa
public class SchoolWholeStatData {

@ExcelProperty(value = "学校名称", types = {"all", "school"})
private String schoolName;

@ExcelProperty(value = "学校地址", types = {"all", "school"})
private String schoolAddress;

@ExcelProperty(value = "学校编号", types = {"all", "school"})
private String schoolNo;

@ExcelProperty(value = "学生姓名", types = {"all", "student"})
private String studentName;

@ExcelProperty(value = "学生学号", types = {"all", "student"})
private String studentNo;

@ExcelProperty(value = "学生年龄", types = {"all", "student"})
private Integer studentAge;

@ExcelProperty(value = "学生身份证", types = {"all", "student"})
private String studentIdCard;

}`

How to complete

1、ExcelProperty注解新增分组
2、FastExcel.write()方法新增传入本次导出分组数据

Task List

No response

Anything else?

No response

[bengbengbalabalabeng]

NOTE: This proposal is an OUTDATED DRAFT, Please refer to my latest comment below for the updated version.

Hi, I have a design proposal for export by grouping support.

Proposal

This proposal aims to introduce a Java Type-based grouping feature for data export.

Use Case:

This addresses the issue of proliferating redundant VO classes caused by varying field filtering logic across different export scenarios. By implementing a grouping mechanism, a single DTO model can flexibly adapt to multiple business export templates.

Advantages:

• Avoids defining groups with "Magic Strings". It leverages the Java compiler to prevent typos, similar to the groups attribute in Bean Validation annotations.
• Utilizes Interface Inheritance to establish nested and inclusive relationships between groups.
• Reduce maintenance of redundant VO classes.

API Usage Example

1. Basic Grouping

Define simple Marker Interfaces to filter fields for different scenarios.

• Define Group Interfaces and Entity

public interface SchoolGroup {}
public interface StudentGroup {}

@Data
public class SchoolWholeStatData {
    @ExcelProperty(value = "School Name", groups = SchoolGroup.class)
    private String schoolName;

    @ExcelProperty(value = "Student Name", groups = StudentGroup.class)
    private String studentName;

    // Fields without 'groups' are treated as common fields and always exported.
    @ExcelProperty(value = "Update Time")
    private Date updateTime;

    // Fields without '@ExcelProperty and @ExcelIgnoreUnannotated' are treated as common fields and always exported.
    private String className;
}

• Demo

// Export only School-related fields + Common fields
FesodSheet.write(fileName)
    .head(SchoolWholeStatData.class)
    .group(SchoolGroup.class) 
    .sheet()
    .doWrite(dataList);

2. Hierarchical Grouping

Leverage interface inheritance to implement a "Base Group + Extended Group" export pattern.

• Define Group Interfaces with Inheritance and Entity

public interface BaseGroup {}
 // DetailGroup includes all fields from BaseGroup
public interface DetailGroup extends BaseGroup {}

@Data
public class OrderData {
    @ExcelProperty(value = "Order No", groups = BaseGroup.class)
    private String orderNo;

    @ExcelProperty(value = "Payment Transaction No", groups = DetailGroup.class)
    private String paymentNo;
}

• Demo

// By passing DetailGroup.class, both orderNo (inherited) and paymentNo are exported.
FesodSheet.write(fileName)
    .head(OrderData.class)
    .group(DetailGroup.class)
    .sheet()
    .doWrite(dataList);

3. Multiple Groups Activation

Supports activating multiple grouping logics within a single export session.

• Demo

// Export both School and Student fields simultaneously
FesodSheet.write(fileName)
    .head(SchoolWholeStatData.class)
    .group(SchoolGroup.class, StudentGroup.class)
    .sheet()
    .doWrite(dataList);

More

1. Fields not annotated with groups are considered "Common Fields" and are exported by default in all contexts.
2. This feature is fully compatible with Fesod's existing @ExcelIgnore, @ExcelIgnoreUnannotated, and includeColumn*/excludeColumn* logic.
   Filtering Priority:
   @ExcelIgnore, @ExcelIgnoreUnannotated >
   @ExcelProperty(groups = Class<?>[]) >
   includeColumn* / excludeColumn*

---

Feel free to let me know if you have any suggestions. :)

[alaahong]

Hi, I have a design proposal for export by grouping support.

Proposal

This proposal aims to introduce a Java Type-based grouping feature for data export.

Use Case:

This addresses the issue of proliferating redundant VO classes caused by varying field filtering logic across different export scenarios. By implementing a grouping mechanism, a single DTO model can flexibly adapt to multiple business export templates.

Advantages:

• Avoids defining groups with "Magic Strings". It leverages the Java compiler to prevent typos, similar to the groups attribute in Bean Validation annotations.
• Utilizes Interface Inheritance to establish nested and inclusive relationships between groups.
• Reduce maintenance of redundant VO classes.

API Usage Example

1. Basic Grouping

Define simple Marker Interfaces to filter fields for different scenarios.

• Define Group Interfaces and Entity

public interface SchoolGroup {}
public interface StudentGroup {}

@DaTa
public class SchoolWholeStatData {
@ExcelProperty(value = "School Name", groups = SchoolGroup.class)
private String schoolName;

@ExcelProperty(value = "Student Name", groups = StudentGroup.class)
private String studentName;

// Fields without 'groups' are treated as common fields and always exported.
@ExcelProperty(value = "Update Time")
private Date updateTime;

}

• Demo

// Export only School-related fields + Common fields
FesodSheet.write(fileName)
.head(SchoolWholeStatData.class)
.group(SchoolGroup.class)
.sheet()
.doWrite(dataList);

2. Hierarchical Grouping

Leverage interface inheritance to implement a "Base Group + Extended Group" export pattern.

• Define Group Interfaces with Inheritance and Entity

public interface BaseGroup {}
// DetailGroup includes all fields from BaseGroup
public interface DetailGroup extends BaseGroup {}

@DaTa
public class OrderData {
@ExcelProperty(value = "Order No", groups = BaseGroup.class)
private String orderNo;

@ExcelProperty(value = "Payment Transaction No", groups = DetailGroup.class)
private String paymentNo;

}

• Demo

// By passing DetailGroup.class, both orderNo (inherited) and paymentNo are exported.
FesodSheet.write(fileName)
.head(OrderData.class)
.group(DetailGroup.class)
.sheet()
.doWrite(dataList);

3. Multiple Groups Activation

Supports activating multiple grouping logics within a single export session.

• Demo

// Export both School and Student fields simultaneously
FesodSheet.write(fileName)
.head(SchoolWholeStatData.class)
.group(SchoolGroup.class, StudentGroup.class)
.sheet()
.doWrite(dataList);

More

1. Fields not annotated with groups are considered "Common Fields" and are exported by default in all contexts.
2. This feature is fully compatible with Fesod's existing @ExcelIgnore, @ExcelIgnoreUnannotated, and includeColumn*/excludeColumn* logic.
   Filtering Priority:
   @ExcelIgnore, @ExcelIgnoreUnannotated >
   @ExcelProperty(groups = Class<?>[]) >
   includeColumn* / excludeColumn*

Feel free to let me know if you have any suggestions. :)

Fesod will output the field without ExcelProperty, it's a kind of no group attribute scenario, so suggest to add such scenario in sample too.

[bengbengbalabalabeng]

Fesod will output the field without ExcelProperty, it's a kind of no group attribute scenario, so suggest to add such scenario in sample too.

@alaahong Thanks for the suggestion!
I've added the "without @ExcelProperty" scenario to the sample under <API Usage Example – 1. Basic Grouping>.

[bengbengbalabalabeng]

Proposal
This proposal aims to introduce a Java Type-based grouping feature for data export.
... ...

May I check if there are any additional comments regarding the current proposal?
If not, may I take this issue?

[delei]

Hi, @bengbengbalabalabeng

This is a very good proposal. I still have some doubts about some details.

Utilizes Interface Inheritance to establish nested and inclusive relationships between groups.

In this way, will there be a situation where the interface classes explode?? To achieve complex grouping, users may need to define many interface classes..

How about defining a separate @ExcelPropertyGroup or @ExcelPropertyTag annotation or extend the attributes of @ExcelProperty? IMO, The grouping function is actually a filtering condition for the fields of the entity class. It can be represented by a string type and is very simple and efficient.

[bengbengbalabalabeng]

Hi, @delei

Thanks for the review!

I completely understand the concern regarding "interface explosion" and the simplicity of String-based tags. However, I still recommend sticking with the Class/Interface approach for the following reasons:

1. Interface explosion
   we can define static inner interfaces within their VOs or a dedicated constant class. This keeps the project structure clean without creating separate files for every group.

@Data
public class SchoolWholeStatDataVO {

    public interface SchoolGroup {}
    public interface StudentGroup {}

    @ExcelProperty(value = "School Name", groups = SchoolGroup.class)
    private String schoolName;

    @ExcelProperty(value = "Student Name", groups = StudentGroup.class)
    private String studentName;
}

2. Hierarchical Grouping
   Inclusion relationships can be handled automatically using Java inheritance (Detail extends Base). Strings must be displayed and listed in all groups, which is easy to miss and duplicate. When there are too many fields, it is more likely to cause string group explosion.

Class/Interface

@ExcelProperty(value = "No", groups = Base.class)
private String no;

@ExcelProperty(value = "Name", groups = Details.class)
private String name;

String

@ExcelProperty(value = "No", groups = "base")
private String no;

@ExcelProperty(value = "Name", groups = {"base", "detail"})
private String name;

3. Type Safety
   String-based tags are prone to misspellings and difficult to reconstruct. Java Type-based avoid such problems at compile time.

So, I believe the robustness and functionality of the Java Type-based approach offer greater advantages. It seems worthwhile to prioritize the flexibility of inheritance over the simplicity of strings.

WDYT? Looking forward to your feedback.

[delei]

@Data
public class SchoolWholeStatDataVO {

    public interface SchoolGroup {}
    public interface StudentGroup {}

    @ExcelProperty(value = "School Name", groups = SchoolGroup.class)
    private String schoolName;

    @ExcelProperty(value = "Student Name", groups = StudentGroup.class)
    private String studentName;
}

IMO, to be honest, defining empty interfaces, particularly within VO classes, is not a common practice in actual development work.

[bengbengbalabalabeng]

Define static inner interfaces within their VO is not a common practice

I agree that.

Define empty interfaces (Marker-Interfaces)

I see that Bean Validation groups and Jackson‘s @JsonView are both used, which shows that Marker‑Interface grouping is widely used and accepted pattern.

[bengbengbalabalabeng]

NOTE: This proposal is an OUTDATED DRAFT, Please refer to my latest comment below for the updated version.

Or try this approach:

Use a unified annotation:

public @interface ExcelView {

    Class<?>[] asTypes() default {};
    
    String[] asStrings() default {};
}

enum SheetGroupView {
    BY_TYPE_BASED, // Or BY_MARKER_INTERFACE
    BY_STRING_BASED
}

Usage example:

// Use Type-Based
@ExcelView(asTypes = Details.class)
@ExcelProperty(value = "Name")
private String name;

FesodSheet.write(fileName)
    .head(OrderData.class)
    // .view(SheetGroupView.BY_TYPE_BASED, DetailGroup.class)
    .group(DetailGroup.class)
    .sheet()
    .doWrite(dataList);

// Use String-Based
@ExcelView(asStrings = "detail")
@ExcelProperty(value = "Name")
private String name;

FesodSheet.write(fileName)
    .head(OrderData.class)
    // .view(SheetGroupView.BY_STRING_BASED, "base", "detail")
    .tag("base", "detail")
    .sheet()
    .doWrite(dataList);

// When used simultaneously, only the last assignment takes effect.
FesodSheet.write(fileName)
    .head(OrderData.class)
    .group(DetailGroup.class) // Not effective
    .tag("base", "detail")
    .sheet()
    .doWrite(dataList);

With this design, SheetGroupView acts as an explicit switch that determines how the grouping values should be interpreted.

This approach supporting both marker‑interface grouping and lightweight string‑based tags. (However, I still recommend with the Class/Interface approach)

WDYT? @delei

[bengbengbalabalabeng]

Below is my updated design proposal:

Proposal (NEW)

This proposal aims to introduce a Java Type-based/String-based grouping feature for data export.

Use Case:

This addresses the issue of proliferating redundant VO classes caused by varying field filtering logic across different export scenarios. By implementing a grouping mechanism, a single DTO model can flexibly adapt to multiple business export templates.

Advantages:

• Compatible with both Type-based (Utilizes Interface Inheritance to establish nested and inclusive relationships between groups) and String-based grouping modes.
• Reduce maintenance of redundant VO classes.

API Usage Example

By Type-based

1. Basic Grouping

Define simple Marker Interfaces to filter fields for different scenarios.

• Define Group Interfaces and Entity

public interface SchoolGroup {}
public interface StudentGroup {}

@Data
public class SchoolWholeStatData {
    
    @ExcelView(asTypes = SchoolGroup.class)
    @ExcelProperty(value = "School Name")
    private String schoolName;

    @ExcelView(asTypes = StudentGroup.class)
    @ExcelProperty(value = "Student Name")
    private String studentName;

    // Fields not annotated with '@ExcelView' will not be processed for export.
    @ExcelProperty(value = "Update Time")
    private Date updateTime;
}

• Demo

// Export only School-related fields.
FesodSheet.write(fileName, SchoolWholeStatData.class)
    .groups(SchoolGroup.class) 
    .sheet()
    .doWrite(dataList);

2. Hierarchical Grouping

Leverage interface inheritance to implement a "Base Group + Extended Group" export pattern.

• Define Group Interfaces with Inheritance and Entity

public interface BaseGroup {}
 // DetailGroup includes all fields from BaseGroup
public interface DetailGroup extends BaseGroup {}

@Data
public class OrderData {
    
    @ExcelView(asTypes = BaseGroup.class)
    @ExcelProperty(value = "Order No")
    private String orderNo;

    @ExcelView(asTypes = DetailGroup.class)
    @ExcelProperty(value = "Payment Transaction No")
    private String paymentNo;
}

• Demo

// By passing DetailGroup.class, both orderNo (inherited) and paymentNo are exported.
FesodSheet.write(fileName, OrderData.class)
    .groups(DetailGroup.class)
    .sheet()
    .doWrite(dataList);

3. Multiple Groups Activation

Supports activating multiple grouping logics within a single export session.

• Demo

// Export both School and Student fields simultaneously
FesodSheet.write(fileName, SchoolWholeStatData.class)
    .groups(SchoolGroup.class, StudentGroup.class)
    .sheet()
    .doWrite(dataList);

By String-based

1. Basic Grouping

• Define Entity

@Data
public class SchoolWholeStatData {
    
    @ExcelView(asStrings = "SchoolGroup")
    @ExcelProperty(value = "School Name")
    private String schoolName;

    @ExcelView(asStrings = "StudentGroup")
    @ExcelProperty(value = "Student Name")
    private String studentName;

    // Fields not annotated with '@ExcelView' will not be processed for export.
    @ExcelProperty(value = "Update Time")
    private Date updateTime;
}

• Demo

// Export only School-related fields.
FesodSheet.write(fileName, SchoolWholeStatData.class)
    .tags("SchoolGroup") 
    .sheet()
    .doWrite(dataList);

2. Multiple Groups Activation

Supports activating multiple tags logics within a single export session.

• Demo

// Export both School and Student fields simultaneously
FesodSheet.write(fileName, SchoolWholeStatData.class)
    .tags("SchoolGroup", "StudentGroup")
    .sheet()
    .doWrite(dataList);

Override Strategies

When mixing groups and tags, the last assigned strategy takes effect.

• Demo

// Export both School and Student fields simultaneously
FesodSheet.write(fileName, SchoolWholeStatData.class)
    .groups(SchoolGroup.class)
    // takes effect
    .tags("SchoolGroup", "StudentGroup")
    .sheet()
    .doWrite(dataList);

More

• Fields not annotated with '@ExcelView' will not be processed for export.
• This feature is fully compatible with Fesod's existing @ExcelIgnore, @ExcelIgnoreUnannotated, and includeColumn*/excludeColumn* logic.

Filtering Priority:

@ExcelIgnore / @ExcelIgnoreUnannotated > @ExcelView > includeColumn* / excludeColumn*

---

Feel free to let me know if you have any suggestions :)