tessl/maven-com-alibaba--easyexcel

High-performance Java library for reading and writing Excel files with minimal memory usage

—

Pending

Overview

Eval results

Files

Annotations and Mapping

Name: tessl/maven-com-alibaba--easyexcel
Author: tessl

Annotation-based system for mapping Java fields to Excel columns with formatting, styling, and validation support. EasyExcel uses annotations to configure field behavior, appearance, and data conversion rules.

Capabilities

Core Mapping Annotations

Primary annotations for controlling field-to-column mapping behavior.

/**
 * Primary annotation for field-to-column mapping
 * Can be applied to fields or getter methods
 */
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ExcelProperty {
    /**
     * Column header names (supports multi-level headers)
     * @return Array of header names
     */
    String[] value() default {};
    
    /**
     * Column index (0-based), takes precedence over header names
     * @return Column index
     */
    int index() default -1;
    
    /**
     * Field order for sorting (used when index not specified)
     * @return Sort order
     */
    int order() default Integer.MAX_VALUE;
    
    /**
     * Custom converter class for type conversion
     * @return Converter class
     */
    Class<? extends Converter<?>> converter() default AutoConverter.class;
}

/**
 * Exclude field from Excel processing
 */
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ExcelIgnore {
}

/**
 * Class-level annotation to ignore all fields without explicit annotations
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ExcelIgnoreUnannotated {
}

Format Annotations

Annotations for controlling data formatting in Excel cells.

/**
 * Configure date/time formatting
 */
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DateTimeFormat {
    /**
     * Date format pattern (SimpleDateFormat style)
     * @return Format pattern
     */
    String value() default "";
    
    /**
     * Use 1904 date windowing system
     * @return true for 1904 windowing
     */
    boolean use1904windowing() default false;
}

/**
 * Configure number formatting
 */
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NumberFormat {
    /**
     * Number format pattern
     * @return Format pattern
     */
    String value() default "";
}

Style Annotations

Annotations for controlling visual appearance of cells and columns.

/**
 * Set column width
 */
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ColumnWidth {
    /**
     * Column width in characters
     * @return Width value
     */
    int value() default -1;
}

/**
 * Configure header cell styling
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface HeadStyle {
    /**
     * Background color index
     * @return Color index
     */
    short fillForegroundColor() default -1;
    
    /**
     * Fill pattern type
     * @return Fill pattern
     */
    FillPatternTypeEnum fillPatternType() default FillPatternTypeEnum.DEFAULT;
    
    /**
     * Data format index
     * @return Data format
     */
    short dataFormat() default -1;
    
    /**
     * Hidden status
     * @return true if hidden
     */
    BooleanEnum hidden() default BooleanEnum.DEFAULT;
    
    /**
     * Locked status
     * @return true if locked
     */
    BooleanEnum locked() default BooleanEnum.DEFAULT;
    
    /**
     * Text wrapping
     * @return true to wrap text
     */
    BooleanEnum wrapped() default BooleanEnum.DEFAULT;
    
    /**
     * Horizontal alignment
     * @return Alignment type
     */
    HorizontalAlignmentEnum horizontalAlignment() default HorizontalAlignmentEnum.DEFAULT;
    
    /**
     * Vertical alignment
     * @return Alignment type
     */
    VerticalAlignmentEnum verticalAlignment() default VerticalAlignmentEnum.DEFAULT;
    
    /**
     * Text rotation
     * @return Rotation angle
     */
    short rotation() default -1;
    
    /**
     * Text indent
     * @return Indent level
     */
    short indent() default -1;
    
    /**
     * Border configurations
     */
    BorderStyleEnum borderLeft() default BorderStyleEnum.DEFAULT;
    BorderStyleEnum borderRight() default BorderStyleEnum.DEFAULT;
    BorderStyleEnum borderTop() default BorderStyleEnum.DEFAULT;
    BorderStyleEnum borderBottom() default BorderStyleEnum.DEFAULT;
    
    /**
     * Border color configurations
     */
    short leftBorderColor() default -1;
    short rightBorderColor() default -1;
    short topBorderColor() default -1;
    short bottomBorderColor() default -1;
    
    /**
     * Shrink to fit
     * @return true to shrink to fit
     */
    BooleanEnum shrinkToFit() default BooleanEnum.DEFAULT;
}

/**
 * Configure header font styling
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface HeadFontStyle {
    /**
     * Font name
     * @return Font name
     */
    String fontName() default "";
    
    /**
     * Font height in points
     * @return Font size
     */
    short fontHeightInPoints() default -1;
    
    /**
     * Italic style
     * @return true for italic
     */
    BooleanEnum italic() default BooleanEnum.DEFAULT;
    
    /**
     * Strikeout style
     * @return true for strikeout
     */
    BooleanEnum strikeout() default BooleanEnum.DEFAULT;
    
    /**
     * Font color
     * @return Color index
     */
    short color() default -1;
    
    /**
     * Type offset
     * @return Offset type
     */
    short typeOffset() default -1;
    
    /**
     * Underline style
     * @return Underline type
     */
    byte underline() default -1;
    
    /**
     * Character set
     * @return Character set
     */
    int charset() default -1;
    
    /**
     * Bold style
     * @return true for bold
     */
    BooleanEnum bold() default BooleanEnum.DEFAULT;
}

/**
 * Set header row height
 */
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface HeadRowHeight {
    /**
     * Row height in points
     * @return Height value
     */
    short value() default -1;
}

/**
 * Configure content cell styling (same properties as HeadStyle)
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ContentStyle {
    // Same properties as HeadStyle
    short fillForegroundColor() default -1;
    FillPatternTypeEnum fillPatternType() default FillPatternTypeEnum.DEFAULT;
    short dataFormat() default -1;
    BooleanEnum hidden() default BooleanEnum.DEFAULT;
    BooleanEnum locked() default BooleanEnum.DEFAULT;
    BooleanEnum wrapped() default BooleanEnum.DEFAULT;
    HorizontalAlignmentEnum horizontalAlignment() default HorizontalAlignmentEnum.DEFAULT;
    VerticalAlignmentEnum verticalAlignment() default VerticalAlignmentEnum.DEFAULT;
    short rotation() default -1;
    short indent() default -1;
    BorderStyleEnum borderLeft() default BorderStyleEnum.DEFAULT;
    BorderStyleEnum borderRight() default BorderStyleEnum.DEFAULT;
    BorderStyleEnum borderTop() default BorderStyleEnum.DEFAULT;
    BorderStyleEnum borderBottom() default BorderStyleEnum.DEFAULT;
    short leftBorderColor() default -1;
    short rightBorderColor() default -1;
    short topBorderColor() default -1;
    short bottomBorderColor() default -1;
    BooleanEnum shrinkToFit() default BooleanEnum.DEFAULT;
}

/**
 * Configure content font styling (same properties as HeadFontStyle)
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ContentFontStyle {
    // Same properties as HeadFontStyle
    String fontName() default "";
    short fontHeightInPoints() default -1;
    BooleanEnum italic() default BooleanEnum.DEFAULT;
    BooleanEnum strikeout() default BooleanEnum.DEFAULT;
    short color() default -1;
    short typeOffset() default -1;
    byte underline() default -1;
    int charset() default -1;
    BooleanEnum bold() default BooleanEnum.DEFAULT;
}

/**
 * Set content row height
 */
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ContentRowHeight {
    /**
     * Row height in points
     * @return Height value
     */
    short value() default -1;
}

Merge Annotations

Annotations for controlling cell merging behavior.

/**
 * Configure repetitive cell merging for content
 */
@Target({ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ContentLoopMerge {
    /**
     * Number of rows to merge for each loop
     * @return Merge count
     */
    int eachRow() default -1;
    
    /**
     * Number of columns to merge
     * @return Column count
     */
    int columnExtend() default -1;
}

/**
 * Configure absolute cell range merging
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface OnceAbsoluteMerge {
    /**
     * First row to merge (0-based)
     * @return First row
     */
    int firstRowIndex() default -1;
    
    /**
     * Last row to merge (0-based)
     * @return Last row
     */
    int lastRowIndex() default -1;
    
    /**
     * First column to merge (0-based)
     * @return First column
     */
    int firstColumnIndex() default -1;
    
    /**
     * Last column to merge (0-based)
     * @return Last column
     */
    int lastColumnIndex() default -1;
}

Supporting Enums

// Boolean enum with default option
public enum BooleanEnum {
    TRUE, FALSE, DEFAULT
}

// Horizontal alignment options
public enum HorizontalAlignmentEnum {
    GENERAL, LEFT, CENTER, RIGHT, FILL, JUSTIFY, CENTER_SELECTION, DISTRIBUTED, DEFAULT
}

// Vertical alignment options
public enum VerticalAlignmentEnum {
    TOP, CENTER, BOTTOM, JUSTIFY, DISTRIBUTED, DEFAULT
}

// Fill pattern types
public enum FillPatternTypeEnum {
    NO_FILL, SOLID_FOREGROUND, FINE_DOTS, ALT_BARS, SPARSE_DOTS, THICK_HORZ_BANDS,
    THICK_VERT_BANDS, THICK_BACKWARD_DIAG, THICK_FORWARD_DIAG, BIG_SPOTS, BRICKS,
    THIN_HORZ_BANDS, THIN_VERT_BANDS, THIN_BACKWARD_DIAG, THIN_FORWARD_DIAG,
    SQUARES, DIAMONDS, LESS_DOTS, LEAST_DOTS, DEFAULT
}

// Border style options
public enum BorderStyleEnum {
    NONE, THIN, MEDIUM, DASHED, DOTTED, THICK, DOUBLE, HAIR, MEDIUM_DASHED,
    DASH_DOT, MEDIUM_DASH_DOT, DASH_DOT_DOT, MEDIUM_DASH_DOT_DOT, 
    SLANTED_DASH_DOT, DEFAULT
}

Usage Examples

Basic Mapping

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.ExcelIgnore;

public class UserData {
    @ExcelProperty("Full Name")
    private String name;
    
    @ExcelProperty(value = "Age", index = 1)
    private Integer age;
    
    @ExcelProperty("Email Address")
    private String email;
    
    @ExcelIgnore // This field will not be processed
    private String internalId;
    
    // Getters and setters...
}

Multi-level Headers

import com.alibaba.excel.annotation.ExcelProperty;

public class SalesData {
    @ExcelProperty({"Q1", "January"})
    private Double janSales;
    
    @ExcelProperty({"Q1", "February"})
    private Double febSales;
    
    @ExcelProperty({"Q1", "March"})
    private Double marSales;
    
    @ExcelProperty({"Q2", "April"})
    private Double aprSales;
    
    // Getters and setters...
}

Format Annotations

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.format.DateTimeFormat;
import com.alibaba.excel.annotation.format.NumberFormat;

public class FinancialRecord {
    @ExcelProperty("Transaction ID")
    private String transactionId;
    
    @ExcelProperty("Amount")
    @NumberFormat("#,##0.00")
    private BigDecimal amount;
    
    @ExcelProperty("Transaction Date")
    @DateTimeFormat("yyyy-MM-dd HH:mm:ss")
    private Date transactionDate;
    
    @ExcelProperty("Percentage")
    @NumberFormat("0.00%")
    private Double percentage;
    
    // Getters and setters...
}

Style Annotations

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.*;

@HeadStyle(fillForegroundColor = 40, fillPatternType = FillPatternTypeEnum.SOLID_FOREGROUND)
@HeadFontStyle(fontHeightInPoints = 12, bold = BooleanEnum.TRUE)
@HeadRowHeight(25)
@ContentRowHeight(20)
public class StyledUserData {
    @ExcelProperty("Name")
    @ColumnWidth(20)
    @ContentStyle(fillForegroundColor = 42)
    private String name;
    
    @ExcelProperty("Age")
    @ColumnWidth(10)
    @ContentStyle(horizontalAlignment = HorizontalAlignmentEnum.CENTER)
    private Integer age;
    
    @ExcelProperty("Salary")
    @ColumnWidth(15)
    @NumberFormat("#,##0.00")
    @ContentStyle(
        fillForegroundColor = 43,
        horizontalAlignment = HorizontalAlignmentEnum.RIGHT
    )
    private BigDecimal salary;
    
    // Getters and setters...
}

Advanced Styling with Merge

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.*;

@OnceAbsoluteMerge(firstRowIndex = 0, lastRowIndex = 1, firstColumnIndex = 0, lastColumnIndex = 3)
public class ReportData {
    @ExcelProperty("Department")
    @ContentLoopMerge(eachRow = 2)
    private String department;
    
    @ExcelProperty("Employee")
    private String employee;
    
    @ExcelProperty("Q1 Sales")
    @NumberFormat("#,##0.00")
    private BigDecimal q1Sales;
    
    @ExcelProperty("Q2 Sales")  
    @NumberFormat("#,##0.00")
    private BigDecimal q2Sales;
    
    // Getters and setters...
}

Custom Converter Example

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.converters.Converter;
import com.alibaba.excel.enums.CellDataTypeEnum;
import com.alibaba.excel.metadata.GlobalConfiguration;
import com.alibaba.excel.metadata.data.ReadCellData;
import com.alibaba.excel.metadata.data.WriteCellData;
import com.alibaba.excel.metadata.property.ExcelContentProperty;

// Custom converter for enum values
public class StatusConverter implements Converter<Status> {
    @Override
    public Class<?> supportJavaTypeKey() {
        return Status.class;
    }
    
    @Override
    public CellDataTypeEnum supportExcelTypeKey() {
        return CellDataTypeEnum.STRING;
    }
    
    @Override
    public Status convertToJavaData(ReadCellData<?> cellData, 
                                   ExcelContentProperty contentProperty,
                                   GlobalConfiguration globalConfiguration) {
        return Status.fromDisplayName(cellData.getStringValue());
    }
    
    @Override
    public WriteCellData<?> convertToExcelData(Status value,
                                              ExcelContentProperty contentProperty,
                                              GlobalConfiguration globalConfiguration) {
        return new WriteCellData<>(value.getDisplayName());
    }
}

// Data class using custom converter
public class OrderData {
    @ExcelProperty("Order ID")
    private String orderId;
    
    @ExcelProperty(value = "Status", converter = StatusConverter.class)
    private Status status;
    
    @ExcelProperty("Amount")
    @NumberFormat("#,##0.00")
    private BigDecimal amount;
    
    // Getters and setters...
}

Ignore Unannotated Fields

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.ExcelIgnoreUnannotated;

@ExcelIgnoreUnannotated // Only annotated fields will be processed
public class SelectiveData {
    @ExcelProperty("Name") // This will be included
    private String name;
    
    @ExcelProperty("Email") // This will be included
    private String email;
    
    private String internalField; // This will be ignored
    private Long createdTimestamp; // This will be ignored
    
    // Getters and setters...
}

Field Ordering

import com.alibaba.excel.annotation.ExcelProperty;

public class OrderedData {
    @ExcelProperty(value = "Name", order = 1)
    private String name;
    
    @ExcelProperty(value = "ID", order = 0) // Will appear first
    private String id;
    
    @ExcelProperty(value = "Email", order = 2)
    private String email;
    
    @ExcelProperty(index = 3) // Index takes precedence over order
    private String description;
    
    // Getters and setters...
}

Install with Tessl CLI

npx tessl i tessl/maven-com-alibaba--easyexcel

docs

annotations-and-mapping.md

data-conversion.md

event-system.md

exception-handling.md

index.md

reading-operations.md

writing-operations.md

tile.json

tessl/maven-com-alibaba--easyexcel