0
# Writing Operations
1

2
Functionality for creating and writing Excel files with template support, styling options, and memory-efficient streaming for large datasets.
3

4
## Capabilities
5

6
### Main Write Entry Points
7

8
Factory methods for creating Excel writers with various output destinations.
9

10
```java { .api }
11
/**
12
 * Create a writer builder without specifying output destination
13
 * @return ExcelWriterBuilder for configuration
14
 */
15
public static ExcelWriterBuilder write();
16

17
/**
18
 * Create a writer builder for a file
19
 * @param file File to write to
20
 * @return ExcelWriterBuilder for configuration
21
 */
22
public static ExcelWriterBuilder write(File file);
23

24
/**
25
 * Create a writer builder for a file path
26
 * @param pathName Path to the file to write
27
 * @return ExcelWriterBuilder for configuration
28
 */
29
public static ExcelWriterBuilder write(String pathName);
30

31
/**
32
 * Create a writer builder for an output stream
33
 * @param outputStream OutputStream to write to
34
 * @return ExcelWriterBuilder for configuration
35
 */
36
public static ExcelWriterBuilder write(OutputStream outputStream);
37

38
/**
39
 * Create a writer builder with head class
40
 * @param file File to write to
41
 * @param head Class for data mapping
42
 * @return ExcelWriterBuilder for configuration
43
 */
44
public static ExcelWriterBuilder write(File file, Class<?> head);
45

46
/**
47
 * Create a writer builder with head class for output stream
48
 * @param outputStream OutputStream to write to
49
 * @param head Class for data mapping
50
 * @return ExcelWriterBuilder for configuration
51
 */
52
public static ExcelWriterBuilder write(OutputStream outputStream, Class<?> head);
53
```
54

55
### ExcelWriterBuilder Configuration
56

57
Fluent builder for configuring Excel writer options before execution.
58

59
```java { .api }
60
public class ExcelWriterBuilder {
61
    /**
62
     * Set the output destination file
63
     * @param file File to write to
64
     * @return this builder
65
     */
66
    public ExcelWriterBuilder file(File file);
67
    
68
    /**
69
     * Set the output destination by path
70
     * @param pathName Path to file
71
     * @return this builder
72
     */
73
    public ExcelWriterBuilder file(String pathName);
74
    
75
    /**
76
     * Set the output destination stream
77
     * @param outputStream OutputStream to write to
78
     * @return this builder
79
     */
80
    public ExcelWriterBuilder file(OutputStream outputStream);
81
    
82
    /**
83
     * Set the head class for data mapping
84
     * @param head Class with ExcelProperty annotations
85
     * @return this builder
86
     */
87
    public ExcelWriterBuilder head(Class<?> head);
88
    
89
    /**
90
     * Set character encoding for CSV files
91
     * @param charset Character encoding
92
     * @return this builder
93
     */
94
    public ExcelWriterBuilder charset(Charset charset);
95
    
96
    /**
97
     * Set password for file encryption
98
     * @param password File password
99
     * @return this builder
100
     */
101
    public ExcelWriterBuilder password(String password);
102
    
103
    /**
104
     * Configure memory mode vs file mode
105
     * @param inMemory true for memory mode, false for file mode
106
     * @return this builder
107
     */
108
    public ExcelWriterBuilder inMemory(Boolean inMemory);
109
    
110
    /**
111
     * Use a template file for writing
112
     * @param templateFile Template Excel file
113
     * @return this builder
114
     */
115
    public ExcelWriterBuilder withTemplate(File templateFile);
116
    
117
    /**
118
     * Use a template from InputStream
119
     * @param templateInputStream Template Excel stream
120
     * @return this builder
121
     */
122
    public ExcelWriterBuilder withTemplate(InputStream templateInputStream);
123
    
124
    /**
125
     * Use a template from file path
126
     * @param templateFileName Template file path
127
     * @return this builder
128
     */
129
    public ExcelWriterBuilder withTemplate(String templateFileName);
130
    
131
    /**
132
     * Configure whether to write Excel on exception
133
     * @param writeExcelOnException true to write partial data on exception
134
     * @return this builder
135
     */
136
    public ExcelWriterBuilder writeExcelOnException(Boolean writeExcelOnException);
137
    
138
    /**
139
     * Configure BOM for CSV files
140
     * @param withBom true to include BOM in CSV files
141
     * @return this builder
142
     */
143
    public ExcelWriterBuilder withBom(Boolean withBom);
144
    
145
    /**
146
     * Build the ExcelWriter instance
147
     * @return ExcelWriter for manual control
148
     */
149
    public ExcelWriter build();
150
    
151
    /**
152
     * Create a sheet builder for sheet configuration
153
     * @return ExcelWriterSheetBuilder
154
     */
155
    public ExcelWriterSheetBuilder sheet();
156
    
157
    /**
158
     * Create a sheet builder for specific sheet
159
     * @param sheetNo Sheet index (0-based)
160
     * @return ExcelWriterSheetBuilder
161
     */
162
    public ExcelWriterSheetBuilder sheet(Integer sheetNo);
163
    
164
    /**
165
     * Create a sheet builder for named sheet
166
     * @param sheetName Sheet name
167
     * @return ExcelWriterSheetBuilder
168
     */
169
    public ExcelWriterSheetBuilder sheet(String sheetName);
170
}
171
```
172

173
### ExcelWriterSheetBuilder Configuration
174

175
Configure specific sheet writing parameters and execute writing operations.
176

177
```java { .api }
178
public class ExcelWriterSheetBuilder {
179
    /**
180
     * Set sheet index
181
     * @param sheetNo Sheet index (0-based)
182
     * @return this builder
183
     */
184
    public ExcelWriterSheetBuilder sheetNo(Integer sheetNo);
185
    
186
    /**
187
     * Set sheet name
188
     * @param sheetName Sheet name
189
     * @return this builder
190
     */
191
    public ExcelWriterSheetBuilder sheetName(String sheetName);
192
    
193
    /**
194
     * Set head class for this sheet
195
     * @param head Class with annotations
196
     * @return this builder
197
     */
198
    public ExcelWriterSheetBuilder head(Class<?> head);
199
    
200
    /**
201
     * Write data to the sheet
202
     * @param data Collection of data objects to write
203
     */
204
    public void doWrite(Collection<?> data);
205
    
206
    /**
207
     * Fill template with data
208
     * @param data Object or Map containing fill data
209
     */
210
    public void doFill(Object data);
211
    
212
    /**
213
     * Fill template with collection data
214
     * @param data Collection of objects for filling
215
     */
216
    public void doFill(Collection<?> data);
217
    
218
    /**
219
     * Create a table builder for table-level configuration
220
     * @return ExcelWriterTableBuilder
221
     */
222
    public ExcelWriterTableBuilder table();
223
    
224
    /**
225
     * Create a table builder for specific table
226
     * @param tableNo Table index (0-based)
227
     * @return ExcelWriterTableBuilder
228
     */
229
    public ExcelWriterTableBuilder table(Integer tableNo);
230
}
231
```
232

233
### ExcelWriterTableBuilder Configuration
234

235
Configure table-level writing parameters for advanced scenarios.
236

237
```java { .api }
238
public class ExcelWriterTableBuilder {
239
    /**
240
     * Set table index
241
     * @param tableNo Table index (0-based)
242
     * @return this builder
243
     */
244
    public ExcelWriterTableBuilder tableNo(Integer tableNo);
245
    
246
    /**
247
     * Set head class for this table
248
     * @param head Class with annotations
249
     * @return this builder
250
     */
251
    public ExcelWriterTableBuilder head(Class<?> head);
252
    
253
    /**
254
     * Write data to the table
255
     * @param data Collection of data objects to write
256
     */
257
    public void doWrite(Collection<?> data);
258
}
259
```
260

261
### ExcelWriter Manual Control
262

263
Direct control over the writing process for advanced scenarios.
264

265
```java { .api }
266
public class ExcelWriter implements Closeable {
267
    /**
268
     * Write data to specific sheet
269
     * @param data Collection of data to write
270
     * @param writeSheet Sheet configuration
271
     * @return ExcelWriter for chaining
272
     */
273
    public ExcelWriter write(Collection<?> data, WriteSheet writeSheet);
274
    
275
    /**
276
     * Write data to specific sheet and table
277
     * @param data Collection of data to write  
278
     * @param writeSheet Sheet configuration
279
     * @param writeTable Table configuration
280
     * @return ExcelWriter for chaining
281
     */
282
    public ExcelWriter write(Collection<?> data, WriteSheet writeSheet, WriteTable writeTable);
283
    
284
    /**
285
     * Fill template with data
286
     * @param data Fill data object or Map
287
     * @param writeSheet Sheet configuration
288
     * @return ExcelWriter for chaining
289
     */
290
    public ExcelWriter fill(Object data, WriteSheet writeSheet);
291
    
292
    /**
293
     * Fill template with collection data
294
     * @param data Collection of fill data
295
     * @param fillConfig Fill configuration
296
     * @param writeSheet Sheet configuration
297
     * @return ExcelWriter for chaining
298
     */
299
    public ExcelWriter fill(Collection<?> data, FillConfig fillConfig, WriteSheet writeSheet);
300
    
301
    /**
302
     * Finish writing and flush data
303
     */
304
    public void finish();
305
    
306
    /**
307
     * Close the writer and cleanup resources
308
     */
309
    public void close();
310
}
311
```
312

313
### Sheet and Table Factory Methods
314

315
Static factory methods for creating sheet and table configurations.
316

317
```java { .api }
318
/**
319
 * Create a default sheet configuration
320
 * @return ExcelWriterSheetBuilder
321
 */
322
public static ExcelWriterSheetBuilder writerSheet();
323

324
/**
325
 * Create a sheet configuration by index
326
 * @param sheetNo Sheet index (0-based)
327
 * @return ExcelWriterSheetBuilder
328
 */
329
public static ExcelWriterSheetBuilder writerSheet(Integer sheetNo);
330

331
/**
332
 * Create a sheet configuration by name
333
 * @param sheetName Sheet name
334
 * @return ExcelWriterSheetBuilder
335
 */
336
public static ExcelWriterSheetBuilder writerSheet(String sheetName);
337

338
/**
339
 * Create a sheet configuration with index and name
340
 * @param sheetNo Sheet index (0-based)
341
 * @param sheetName Sheet name
342
 * @return ExcelWriterSheetBuilder
343
 */
344
public static ExcelWriterSheetBuilder writerSheet(Integer sheetNo, String sheetName);
345

346
/**
347
 * Create a default table configuration
348
 * @return ExcelWriterTableBuilder
349
 */
350
public static ExcelWriterTableBuilder writerTable();
351

352
/**
353
 * Create a table configuration by index
354
 * @param tableNo Table index (0-based)
355
 * @return ExcelWriterTableBuilder
356
 */
357
public static ExcelWriterTableBuilder writerTable(Integer tableNo);
358
```
359

360
## Usage Examples
361

362
### Basic Writing
363
```java
364
import com.alibaba.excel.EasyExcel;
365
import java.util.List;
366
import java.util.Arrays;
367

368
// Simple data writing
369
List<UserData> users = Arrays.asList(
370
    new UserData("Alice", 25, "alice@example.com"),
371
    new UserData("Bob", 30, "bob@example.com")
372
);
373

374
EasyExcel.write("users.xlsx", UserData.class)
375
    .sheet("Users")
376
    .doWrite(users);
377

378
// Writing to specific sheet by index
379
EasyExcel.write("workbook.xlsx", UserData.class)
380
    .sheet(0)
381
    .sheetName("UserData")
382
    .doWrite(users);
383
```
384

385
### Writing Multiple Sheets
386
```java
387
import com.alibaba.excel.EasyExcel;
388
import com.alibaba.excel.ExcelWriter;
389
import com.alibaba.excel.write.metadata.WriteSheet;
390

391
// Manual control for multiple sheets
392
try (ExcelWriter excelWriter = EasyExcel.write("multi-sheet.xlsx").build()) {
393
    // Create sheet configurations
394
    WriteSheet userSheet = EasyExcel.writerSheet(0, "Users")
395
        .head(UserData.class)
396
        .build();
397
    
398
    WriteSheet orderSheet = EasyExcel.writerSheet(1, "Orders")
399
        .head(OrderData.class)
400
        .build();
401
    
402
    // Write data to different sheets
403
    excelWriter.write(users, userSheet);
404
    excelWriter.write(orders, orderSheet);
405
}
406
```
407

408
### Template-Based Writing
409
```java
410
import com.alibaba.excel.EasyExcel;
411
import java.util.HashMap;
412
import java.util.Map;
413

414
// Using template for data filling
415
Map<String, Object> fillData = new HashMap<>();
416
fillData.put("name", "John Doe");
417
fillData.put("date", new Date());
418
fillData.put("total", 1500.00);
419

420
EasyExcel.write("report.xlsx")
421
    .withTemplate("report-template.xlsx")
422
    .sheet()
423
    .doFill(fillData);
424

425
// Filling with collection data
426
List<UserData> users = getUserData();
427
EasyExcel.write("user-report.xlsx")
428
    .withTemplate("user-template.xlsx")
429
    .sheet()
430
    .doFill(users);
431
```
432

433
### Advanced Configuration
434
```java
435
import com.alibaba.excel.EasyExcel;
436
import java.nio.charset.StandardCharsets;
437

438
// Advanced writing configuration
439
EasyExcel.write("advanced.xlsx", UserData.class)
440
    .charset(StandardCharsets.UTF_8) // For CSV files
441
    .password("secret123") // Encrypt the file
442
    .inMemory(false) // Use file mode for large datasets
443
    .writeExcelOnException(true) // Write partial data on errors
444
    .sheet("UserData")
445
    .doWrite(users);
446

447
// CSV writing with BOM
448
EasyExcel.write("data.csv", UserData.class)
449
    .charset(StandardCharsets.UTF_8)
450
    .withBom(true)
451
    .sheet()
452
    .doWrite(users);
453
```
454

455
### Streaming Large Datasets
456
```java
457
import com.alibaba.excel.EasyExcel;
458
import com.alibaba.excel.ExcelWriter;
459
import com.alibaba.excel.write.metadata.WriteSheet;
460

461
// Efficient writing of large datasets
462
try (ExcelWriter excelWriter = EasyExcel.write("large-dataset.xlsx", UserData.class)
463
        .inMemory(false) // Use file mode to reduce memory usage
464
        .build()) {
465
    
466
    WriteSheet writeSheet = EasyExcel.writerSheet("Users").build();
467
    
468
    // Write data in batches
469
    int batchSize = 1000;
470
    int totalRecords = getUserCount();
471
    
472
    for (int i = 0; i < totalRecords; i += batchSize) {
473
        List<UserData> batch = getUserBatch(i, batchSize);
474
        excelWriter.write(batch, writeSheet);
475
    }
476
}
477
```
478

479
### Writing with Custom Styling
480
```java
481
import com.alibaba.excel.EasyExcel;
482
import com.alibaba.excel.write.metadata.style.WriteCellStyle;
483
import com.alibaba.excel.write.metadata.style.WriteFont;
484
import com.alibaba.excel.write.style.HorizontalCellStyleStrategy;
485
import org.apache.poi.ss.usermodel.FillPatternType;
486
import org.apache.poi.ss.usermodel.IndexedColors;
487

488
// Custom styling example
489
WriteCellStyle headWriteCellStyle = new WriteCellStyle();
490
headWriteCellStyle.setFillForegroundColor(IndexedColors.LIGHT_BLUE.getIndex());
491
headWriteCellStyle.setFillPatternType(FillPatternType.SOLID_FOREGROUND);
492

493
WriteFont headWriteFont = new WriteFont();
494
headWriteFont.setFontHeightInPoints((short) 14);
495
headWriteFont.setBold(true);
496
headWriteCellStyle.setWriteFont(headWriteFont);
497

498
WriteCellStyle contentWriteCellStyle = new WriteCellStyle();
499
contentWriteCellStyle.setFillForegroundColor(IndexedColors.WHITE.getIndex());
500
contentWriteCellStyle.setFillPatternType(FillPatternType.SOLID_FOREGROUND);
501

502
HorizontalCellStyleStrategy horizontalCellStyleStrategy = 
503
    new HorizontalCellStyleStrategy(headWriteCellStyle, contentWriteCellStyle);
504

505
EasyExcel.write("styled.xlsx", UserData.class)
506
    .registerWriteHandler(horizontalCellStyleStrategy)
507
    .sheet("StyledUsers")
508
    .doWrite(users);
509
```
510

511
### Writing Different Data Types
512
```java
513
import com.alibaba.excel.EasyExcel;
514
import java.util.Map;
515
import java.util.HashMap;
516
import java.util.List;
517
import java.util.ArrayList;
518

519
// Writing Map data when no model class is available
520
List<Map<String, Object>> mapData = new ArrayList<>();
521
Map<String, Object> row1 = new HashMap<>();
522
row1.put("Name", "Alice");
523
row1.put("Age", 25);
524
row1.put("Email", "alice@example.com");
525
mapData.add(row1);
526

527
EasyExcel.write("map-data.xlsx")
528
    .sheet("MapData")
529
    .doWrite(mapData);
530

531
// Writing List<List<Object>> data
532
List<List<Object>> listData = new ArrayList<>();
533
listData.add(Arrays.asList("Name", "Age", "Email")); // Header
534
listData.add(Arrays.asList("Alice", 25, "alice@example.com"));
535
listData.add(Arrays.asList("Bob", 30, "bob@example.com"));
536

537
EasyExcel.write("list-data.xlsx")
538
    .sheet("ListData")
539
    .doWrite(listData);
540
```