0
# Annotations and Mapping
1

2
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.
3

4
## Capabilities
5

6
### Core Mapping Annotations
7

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

10
```java { .api }
11
/**
12
 * Primary annotation for field-to-column mapping
13
 * Can be applied to fields or getter methods
14
 */
15
@Target({ElementType.FIELD, ElementType.METHOD})
16
@Retention(RetentionPolicy.RUNTIME)
17
public @interface ExcelProperty {
18
    /**
19
     * Column header names (supports multi-level headers)
20
     * @return Array of header names
21
     */
22
    String[] value() default {};
23
    
24
    /**
25
     * Column index (0-based), takes precedence over header names
26
     * @return Column index
27
     */
28
    int index() default -1;
29
    
30
    /**
31
     * Field order for sorting (used when index not specified)
32
     * @return Sort order
33
     */
34
    int order() default Integer.MAX_VALUE;
35
    
36
    /**
37
     * Custom converter class for type conversion
38
     * @return Converter class
39
     */
40
    Class<? extends Converter<?>> converter() default AutoConverter.class;
41
}
42

43
/**
44
 * Exclude field from Excel processing
45
 */
46
@Target({ElementType.FIELD, ElementType.METHOD})
47
@Retention(RetentionPolicy.RUNTIME)
48
public @interface ExcelIgnore {
49
}
50

51
/**
52
 * Class-level annotation to ignore all fields without explicit annotations
53
 */
54
@Target(ElementType.TYPE)
55
@Retention(RetentionPolicy.RUNTIME)
56
public @interface ExcelIgnoreUnannotated {
57
}
58
```
59

60
### Format Annotations
61

62
Annotations for controlling data formatting in Excel cells.
63

64
```java { .api }
65
/**
66
 * Configure date/time formatting
67
 */
68
@Target({ElementType.FIELD, ElementType.METHOD})
69
@Retention(RetentionPolicy.RUNTIME)
70
public @interface DateTimeFormat {
71
    /**
72
     * Date format pattern (SimpleDateFormat style)
73
     * @return Format pattern
74
     */
75
    String value() default "";
76
    
77
    /**
78
     * Use 1904 date windowing system
79
     * @return true for 1904 windowing
80
     */
81
    boolean use1904windowing() default false;
82
}
83

84
/**
85
 * Configure number formatting
86
 */
87
@Target({ElementType.FIELD, ElementType.METHOD})
88
@Retention(RetentionPolicy.RUNTIME)
89
public @interface NumberFormat {
90
    /**
91
     * Number format pattern
92
     * @return Format pattern
93
     */
94
    String value() default "";
95
}
96
```
97

98
### Style Annotations
99

100
Annotations for controlling visual appearance of cells and columns.
101

102
```java { .api }
103
/**
104
 * Set column width
105
 */
106
@Target({ElementType.FIELD, ElementType.METHOD})
107
@Retention(RetentionPolicy.RUNTIME)
108
public @interface ColumnWidth {
109
    /**
110
     * Column width in characters
111
     * @return Width value
112
     */
113
    int value() default -1;
114
}
115

116
/**
117
 * Configure header cell styling
118
 */
119
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
120
@Retention(RetentionPolicy.RUNTIME)
121
public @interface HeadStyle {
122
    /**
123
     * Background color index
124
     * @return Color index
125
     */
126
    short fillForegroundColor() default -1;
127
    
128
    /**
129
     * Fill pattern type
130
     * @return Fill pattern
131
     */
132
    FillPatternTypeEnum fillPatternType() default FillPatternTypeEnum.DEFAULT;
133
    
134
    /**
135
     * Data format index
136
     * @return Data format
137
     */
138
    short dataFormat() default -1;
139
    
140
    /**
141
     * Hidden status
142
     * @return true if hidden
143
     */
144
    BooleanEnum hidden() default BooleanEnum.DEFAULT;
145
    
146
    /**
147
     * Locked status
148
     * @return true if locked
149
     */
150
    BooleanEnum locked() default BooleanEnum.DEFAULT;
151
    
152
    /**
153
     * Text wrapping
154
     * @return true to wrap text
155
     */
156
    BooleanEnum wrapped() default BooleanEnum.DEFAULT;
157
    
158
    /**
159
     * Horizontal alignment
160
     * @return Alignment type
161
     */
162
    HorizontalAlignmentEnum horizontalAlignment() default HorizontalAlignmentEnum.DEFAULT;
163
    
164
    /**
165
     * Vertical alignment
166
     * @return Alignment type
167
     */
168
    VerticalAlignmentEnum verticalAlignment() default VerticalAlignmentEnum.DEFAULT;
169
    
170
    /**
171
     * Text rotation
172
     * @return Rotation angle
173
     */
174
    short rotation() default -1;
175
    
176
    /**
177
     * Text indent
178
     * @return Indent level
179
     */
180
    short indent() default -1;
181
    
182
    /**
183
     * Border configurations
184
     */
185
    BorderStyleEnum borderLeft() default BorderStyleEnum.DEFAULT;
186
    BorderStyleEnum borderRight() default BorderStyleEnum.DEFAULT;
187
    BorderStyleEnum borderTop() default BorderStyleEnum.DEFAULT;
188
    BorderStyleEnum borderBottom() default BorderStyleEnum.DEFAULT;
189
    
190
    /**
191
     * Border color configurations
192
     */
193
    short leftBorderColor() default -1;
194
    short rightBorderColor() default -1;
195
    short topBorderColor() default -1;
196
    short bottomBorderColor() default -1;
197
    
198
    /**
199
     * Shrink to fit
200
     * @return true to shrink to fit
201
     */
202
    BooleanEnum shrinkToFit() default BooleanEnum.DEFAULT;
203
}
204

205
/**
206
 * Configure header font styling
207
 */
208
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
209
@Retention(RetentionPolicy.RUNTIME)
210
public @interface HeadFontStyle {
211
    /**
212
     * Font name
213
     * @return Font name
214
     */
215
    String fontName() default "";
216
    
217
    /**
218
     * Font height in points
219
     * @return Font size
220
     */
221
    short fontHeightInPoints() default -1;
222
    
223
    /**
224
     * Italic style
225
     * @return true for italic
226
     */
227
    BooleanEnum italic() default BooleanEnum.DEFAULT;
228
    
229
    /**
230
     * Strikeout style
231
     * @return true for strikeout
232
     */
233
    BooleanEnum strikeout() default BooleanEnum.DEFAULT;
234
    
235
    /**
236
     * Font color
237
     * @return Color index
238
     */
239
    short color() default -1;
240
    
241
    /**
242
     * Type offset
243
     * @return Offset type
244
     */
245
    short typeOffset() default -1;
246
    
247
    /**
248
     * Underline style
249
     * @return Underline type
250
     */
251
    byte underline() default -1;
252
    
253
    /**
254
     * Character set
255
     * @return Character set
256
     */
257
    int charset() default -1;
258
    
259
    /**
260
     * Bold style
261
     * @return true for bold
262
     */
263
    BooleanEnum bold() default BooleanEnum.DEFAULT;
264
}
265

266
/**
267
 * Set header row height
268
 */
269
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
270
@Retention(RetentionPolicy.RUNTIME)
271
public @interface HeadRowHeight {
272
    /**
273
     * Row height in points
274
     * @return Height value
275
     */
276
    short value() default -1;
277
}
278

279
/**
280
 * Configure content cell styling (same properties as HeadStyle)
281
 */
282
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
283
@Retention(RetentionPolicy.RUNTIME)
284
public @interface ContentStyle {
285
    // Same properties as HeadStyle
286
    short fillForegroundColor() default -1;
287
    FillPatternTypeEnum fillPatternType() default FillPatternTypeEnum.DEFAULT;
288
    short dataFormat() default -1;
289
    BooleanEnum hidden() default BooleanEnum.DEFAULT;
290
    BooleanEnum locked() default BooleanEnum.DEFAULT;
291
    BooleanEnum wrapped() default BooleanEnum.DEFAULT;
292
    HorizontalAlignmentEnum horizontalAlignment() default HorizontalAlignmentEnum.DEFAULT;
293
    VerticalAlignmentEnum verticalAlignment() default VerticalAlignmentEnum.DEFAULT;
294
    short rotation() default -1;
295
    short indent() default -1;
296
    BorderStyleEnum borderLeft() default BorderStyleEnum.DEFAULT;
297
    BorderStyleEnum borderRight() default BorderStyleEnum.DEFAULT;
298
    BorderStyleEnum borderTop() default BorderStyleEnum.DEFAULT;
299
    BorderStyleEnum borderBottom() default BorderStyleEnum.DEFAULT;
300
    short leftBorderColor() default -1;
301
    short rightBorderColor() default -1;
302
    short topBorderColor() default -1;
303
    short bottomBorderColor() default -1;
304
    BooleanEnum shrinkToFit() default BooleanEnum.DEFAULT;
305
}
306

307
/**
308
 * Configure content font styling (same properties as HeadFontStyle)
309
 */
310
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
311
@Retention(RetentionPolicy.RUNTIME)
312
public @interface ContentFontStyle {
313
    // Same properties as HeadFontStyle
314
    String fontName() default "";
315
    short fontHeightInPoints() default -1;
316
    BooleanEnum italic() default BooleanEnum.DEFAULT;
317
    BooleanEnum strikeout() default BooleanEnum.DEFAULT;
318
    short color() default -1;
319
    short typeOffset() default -1;
320
    byte underline() default -1;
321
    int charset() default -1;
322
    BooleanEnum bold() default BooleanEnum.DEFAULT;
323
}
324

325
/**
326
 * Set content row height
327
 */
328
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
329
@Retention(RetentionPolicy.RUNTIME)
330
public @interface ContentRowHeight {
331
    /**
332
     * Row height in points
333
     * @return Height value
334
     */
335
    short value() default -1;
336
}
337
```
338

339
### Merge Annotations
340

341
Annotations for controlling cell merging behavior.
342

343
```java { .api }
344
/**
345
 * Configure repetitive cell merging for content
346
 */
347
@Target({ElementType.FIELD, ElementType.METHOD})
348
@Retention(RetentionPolicy.RUNTIME)
349
public @interface ContentLoopMerge {
350
    /**
351
     * Number of rows to merge for each loop
352
     * @return Merge count
353
     */
354
    int eachRow() default -1;
355
    
356
    /**
357
     * Number of columns to merge
358
     * @return Column count
359
     */
360
    int columnExtend() default -1;
361
}
362

363
/**
364
 * Configure absolute cell range merging
365
 */
366
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
367
@Retention(RetentionPolicy.RUNTIME)
368
public @interface OnceAbsoluteMerge {
369
    /**
370
     * First row to merge (0-based)
371
     * @return First row
372
     */
373
    int firstRowIndex() default -1;
374
    
375
    /**
376
     * Last row to merge (0-based)
377
     * @return Last row
378
     */
379
    int lastRowIndex() default -1;
380
    
381
    /**
382
     * First column to merge (0-based)
383
     * @return First column
384
     */
385
    int firstColumnIndex() default -1;
386
    
387
    /**
388
     * Last column to merge (0-based)
389
     * @return Last column
390
     */
391
    int lastColumnIndex() default -1;
392
}
393
```
394

395
## Supporting Enums
396

397
```java { .api }
398
// Boolean enum with default option
399
public enum BooleanEnum {
400
    TRUE, FALSE, DEFAULT
401
}
402

403
// Horizontal alignment options
404
public enum HorizontalAlignmentEnum {
405
    GENERAL, LEFT, CENTER, RIGHT, FILL, JUSTIFY, CENTER_SELECTION, DISTRIBUTED, DEFAULT
406
}
407

408
// Vertical alignment options
409
public enum VerticalAlignmentEnum {
410
    TOP, CENTER, BOTTOM, JUSTIFY, DISTRIBUTED, DEFAULT
411
}
412

413
// Fill pattern types
414
public enum FillPatternTypeEnum {
415
    NO_FILL, SOLID_FOREGROUND, FINE_DOTS, ALT_BARS, SPARSE_DOTS, THICK_HORZ_BANDS,
416
    THICK_VERT_BANDS, THICK_BACKWARD_DIAG, THICK_FORWARD_DIAG, BIG_SPOTS, BRICKS,
417
    THIN_HORZ_BANDS, THIN_VERT_BANDS, THIN_BACKWARD_DIAG, THIN_FORWARD_DIAG,
418
    SQUARES, DIAMONDS, LESS_DOTS, LEAST_DOTS, DEFAULT
419
}
420

421
// Border style options
422
public enum BorderStyleEnum {
423
    NONE, THIN, MEDIUM, DASHED, DOTTED, THICK, DOUBLE, HAIR, MEDIUM_DASHED,
424
    DASH_DOT, MEDIUM_DASH_DOT, DASH_DOT_DOT, MEDIUM_DASH_DOT_DOT, 
425
    SLANTED_DASH_DOT, DEFAULT
426
}
427
```
428

429
## Usage Examples
430

431
### Basic Mapping
432
```java
433
import com.alibaba.excel.annotation.ExcelProperty;
434
import com.alibaba.excel.annotation.ExcelIgnore;
435

436
public class UserData {
437
    @ExcelProperty("Full Name")
438
    private String name;
439
    
440
    @ExcelProperty(value = "Age", index = 1)
441
    private Integer age;
442
    
443
    @ExcelProperty("Email Address")
444
    private String email;
445
    
446
    @ExcelIgnore // This field will not be processed
447
    private String internalId;
448
    
449
    // Getters and setters...
450
}
451
```
452

453
### Multi-level Headers
454
```java
455
import com.alibaba.excel.annotation.ExcelProperty;
456

457
public class SalesData {
458
    @ExcelProperty({"Q1", "January"})
459
    private Double janSales;
460
    
461
    @ExcelProperty({"Q1", "February"})
462
    private Double febSales;
463
    
464
    @ExcelProperty({"Q1", "March"})
465
    private Double marSales;
466
    
467
    @ExcelProperty({"Q2", "April"})
468
    private Double aprSales;
469
    
470
    // Getters and setters...
471
}
472
```
473

474
### Format Annotations
475
```java
476
import com.alibaba.excel.annotation.ExcelProperty;
477
import com.alibaba.excel.annotation.format.DateTimeFormat;
478
import com.alibaba.excel.annotation.format.NumberFormat;
479

480
public class FinancialRecord {
481
    @ExcelProperty("Transaction ID")
482
    private String transactionId;
483
    
484
    @ExcelProperty("Amount")
485
    @NumberFormat("#,##0.00")
486
    private BigDecimal amount;
487
    
488
    @ExcelProperty("Transaction Date")
489
    @DateTimeFormat("yyyy-MM-dd HH:mm:ss")
490
    private Date transactionDate;
491
    
492
    @ExcelProperty("Percentage")
493
    @NumberFormat("0.00%")
494
    private Double percentage;
495
    
496
    // Getters and setters...
497
}
498
```
499

500
### Style Annotations
501
```java
502
import com.alibaba.excel.annotation.ExcelProperty;
503
import com.alibaba.excel.annotation.write.style.*;
504

505
@HeadStyle(fillForegroundColor = 40, fillPatternType = FillPatternTypeEnum.SOLID_FOREGROUND)
506
@HeadFontStyle(fontHeightInPoints = 12, bold = BooleanEnum.TRUE)
507
@HeadRowHeight(25)
508
@ContentRowHeight(20)
509
public class StyledUserData {
510
    @ExcelProperty("Name")
511
    @ColumnWidth(20)
512
    @ContentStyle(fillForegroundColor = 42)
513
    private String name;
514
    
515
    @ExcelProperty("Age")
516
    @ColumnWidth(10)
517
    @ContentStyle(horizontalAlignment = HorizontalAlignmentEnum.CENTER)
518
    private Integer age;
519
    
520
    @ExcelProperty("Salary")
521
    @ColumnWidth(15)
522
    @NumberFormat("#,##0.00")
523
    @ContentStyle(
524
        fillForegroundColor = 43,
525
        horizontalAlignment = HorizontalAlignmentEnum.RIGHT
526
    )
527
    private BigDecimal salary;
528
    
529
    // Getters and setters...
530
}
531
```
532

533
### Advanced Styling with Merge
534
```java
535
import com.alibaba.excel.annotation.ExcelProperty;
536
import com.alibaba.excel.annotation.write.style.*;
537

538
@OnceAbsoluteMerge(firstRowIndex = 0, lastRowIndex = 1, firstColumnIndex = 0, lastColumnIndex = 3)
539
public class ReportData {
540
    @ExcelProperty("Department")
541
    @ContentLoopMerge(eachRow = 2)
542
    private String department;
543
    
544
    @ExcelProperty("Employee")
545
    private String employee;
546
    
547
    @ExcelProperty("Q1 Sales")
548
    @NumberFormat("#,##0.00")
549
    private BigDecimal q1Sales;
550
    
551
    @ExcelProperty("Q2 Sales")  
552
    @NumberFormat("#,##0.00")
553
    private BigDecimal q2Sales;
554
    
555
    // Getters and setters...
556
}
557
```
558

559
### Custom Converter Example
560
```java
561
import com.alibaba.excel.annotation.ExcelProperty;
562
import com.alibaba.excel.converters.Converter;
563
import com.alibaba.excel.enums.CellDataTypeEnum;
564
import com.alibaba.excel.metadata.GlobalConfiguration;
565
import com.alibaba.excel.metadata.data.ReadCellData;
566
import com.alibaba.excel.metadata.data.WriteCellData;
567
import com.alibaba.excel.metadata.property.ExcelContentProperty;
568

569
// Custom converter for enum values
570
public class StatusConverter implements Converter<Status> {
571
    @Override
572
    public Class<?> supportJavaTypeKey() {
573
        return Status.class;
574
    }
575
    
576
    @Override
577
    public CellDataTypeEnum supportExcelTypeKey() {
578
        return CellDataTypeEnum.STRING;
579
    }
580
    
581
    @Override
582
    public Status convertToJavaData(ReadCellData<?> cellData, 
583
                                   ExcelContentProperty contentProperty,
584
                                   GlobalConfiguration globalConfiguration) {
585
        return Status.fromDisplayName(cellData.getStringValue());
586
    }
587
    
588
    @Override
589
    public WriteCellData<?> convertToExcelData(Status value,
590
                                              ExcelContentProperty contentProperty,
591
                                              GlobalConfiguration globalConfiguration) {
592
        return new WriteCellData<>(value.getDisplayName());
593
    }
594
}
595

596
// Data class using custom converter
597
public class OrderData {
598
    @ExcelProperty("Order ID")
599
    private String orderId;
600
    
601
    @ExcelProperty(value = "Status", converter = StatusConverter.class)
602
    private Status status;
603
    
604
    @ExcelProperty("Amount")
605
    @NumberFormat("#,##0.00")
606
    private BigDecimal amount;
607
    
608
    // Getters and setters...
609
}
610
```
611

612
### Ignore Unannotated Fields
613
```java
614
import com.alibaba.excel.annotation.ExcelProperty;
615
import com.alibaba.excel.annotation.ExcelIgnoreUnannotated;
616

617
@ExcelIgnoreUnannotated // Only annotated fields will be processed
618
public class SelectiveData {
619
    @ExcelProperty("Name") // This will be included
620
    private String name;
621
    
622
    @ExcelProperty("Email") // This will be included
623
    private String email;
624
    
625
    private String internalField; // This will be ignored
626
    private Long createdTimestamp; // This will be ignored
627
    
628
    // Getters and setters...
629
}
630
```
631

632
### Field Ordering
633
```java
634
import com.alibaba.excel.annotation.ExcelProperty;
635

636
public class OrderedData {
637
    @ExcelProperty(value = "Name", order = 1)
638
    private String name;
639
    
640
    @ExcelProperty(value = "ID", order = 0) // Will appear first
641
    private String id;
642
    
643
    @ExcelProperty(value = "Email", order = 2)
644
    private String email;
645
    
646
    @ExcelProperty(index = 3) // Index takes precedence over order
647
    private String description;
648
    
649
    // Getters and setters...
650
}
651
```