easyexcel-fill

name	easyexcel-fill
description	基于 Alibaba EasyExcel（com.alibaba:easyexcel:4.0.3）的 Excel 模板填充技能。覆盖简单对象填充、列表填充（{.}+forceNewRow）、横向多列组合填充（FillWrapper+WriteDirectionEnum.HORIZONTAL）、复杂填充（含合计行/统计行/先 fill 后 write）、Spring Boot 集成、模板设计规范、转义字符、03版/07版差异、性能优化（分次 fill、文件缓存）。当用户需要把 Java 对象或 Map 数据按预制 .xlsx 模板（变量语法 {var}、{.}、{prefix.}）填充生成报表（工资条/合同/对账单/发票/财务报表/统计表/汇总表）时使用此技能，不适用于不基于模板的"程序生成 Excel"场景（改用 easyexcel-write）。
license	Apache-2.0

EasyExcel 模板填充（Fill）

官方文档：https://easyexcel.opensource.alibaba.com/docs/current/quickstart/fill 官方示例：https://github.com/alibaba/easyexcel/blob/master/easyexcel-test/src/test/java/com/alibaba/easyexcel/test/demo/fill/FillTest.java 当前版本：com.alibaba:easyexcel:4.0.3（Apache-2.0，仓库已归档，仅做 Bug 修复）

本技能专注于 "按预制模板填充" 场景。当用户给出一份已经画好样式的 .xlsx 模板，要求把数据库/接口里的数据填进去（工资条、合同、发票、报表、统计单等），应当使用本技能。

Capability Boundaries

✅ 强项

1. 简单对象填充（Map / 单个 DTO）
2. 列表填充（模板 {.} 语法，单向纵向）
3. 复杂填充（list 后还有内容 → forceNewRow=true）
4. 大数据量复杂填充（list 必须放最后一行，后续统计行用 write 追加）
5. 横向多列组合填充（WriteDirectionEnum.HORIZONTAL + FillWrapper）
6. 模板转义字符处理（\{ \}）
7. Spring Boot 集成（模板文件可来自 resources/ 或 OSS）

⚠️ 限制

1. 仅支持 .xlsx（07 版），03 版（.xls）不支持复杂/大数据量填充
2. forceNewRow=true 会全量驻内存，数据量大时慎用
3. withTemplate 模板会全量加载到内存，模板文件过大（>几十 MB）会 OOM
4. Map 填充 list 时必须包含所有 list 的 key，否则报 NPE

❌ Out of Scope（不该用本技能的场景，请改用其它技能）

1. 不基于模板的程序化生成 Excel（无预制模板）→ 不适用本技能，使用 easyexcel-write
2. 读取 Excel 数据 → 不适用本技能，使用 easyexcel-read
3. CSV 文件处理 → 不适用本技能，自行使用 commons-csv / OpenCSV
4. Word/PPT → 不适用本技能，使用 Apache POI / Apache POI-XML

Data Privacy

本技能不收集、存储或传输任何用户数据。所有代码示例仅用于本地开发参考。

When to use this skill

• 用户说"按模板生成 Excel"、"填充 Excel 模板"、"导出工资条/合同/发票"
• 用户提供 .xlsx 模板文件，要求把数据写进变量占位符
• 报表存在固定格式，需要保留样式/合并单元格/函数/图表
• 业务上有"先 fill 列表，再追加合计行/统计行"的需求

Quick Start

典型调用方式（4 选 1，按文件大小递增）：

// 方案 A：最简单的对象填充（since 2.1.1）
String fileName = "output_simple.xlsx";
EasyExcel.write(fileName).withTemplate("templates/simple.xlsx")
    .sheet().doFill(fillData);

// 方案 B：列表填充（一次放入内存）
EasyExcel.write(fileName).withTemplate("templates/list.xlsx")
    .sheet().doFill(list);

// 方案 C：列表分次填充（文件缓存，省内存）
try (ExcelWriter excelWriter = EasyExcel.write(fileName)
        .withTemplate("templates/list.xlsx").build()) {
    WriteSheet writeSheet = EasyExcel.writerSheet().build();
    excelWriter.fill(list, writeSheet);  // 多次 fill，自动文件缓存
    excelWriter.fill(list, writeSheet);
}

// 方案 D：先 fill 列表 + 后 write 追加合计行（推荐：复杂报表 + 大数据量）
try (ExcelWriter excelWriter = EasyExcel.write(fileName)
        .withTemplate("templates/complex.xlsx").build()) {
    WriteSheet writeSheet = EasyExcel.writerSheet().build();
    excelWriter.fill(list, writeSheet);          // 1. 填列表
    excelWriter.fill(headerMap, writeSheet);     // 2. 填头部变量
    excelWriter.write(totalListList, writeSheet);// 3. 手动追加合计行
}

Workflow

Step 1. 确认场景 — 用户是否提供了 .xlsx 模板？模板里是否有 {var} {.} {prefix.} 占位符？ Step 2. 评估数据量 — < 1 万行：方案 A/B；> 1 万行：方案 C/D（list 必须放最后一行） Step 3. 选择填充模式 — 单对象 / 列表 / 复杂 / 横向多列 Step 4. 构造数据 — Map / DTO / List；Map 填充 list 必须包含所有 key Step 5. 执行填充 — try-with-resources 关闭 ExcelWriter Step 6. 验证输出 — 打开生成的 .xlsx 检查占位符是否被替换、有无残留 {.} {}

Critical: 模板语法速查

模板占位符	含义	Java 数据结构
{name} {number} {date}	单值占位符	Map.put("name", value) 或 DTO 字段
{.}	列表占位符（默认纵向）	List<DTO> 整体作为 fill 第一个参数
{data1.} {data2.}	带前缀的列表（多列表区分）	new FillWrapper("data1", list)
\{ \}	转义：当模板中真有 { } 字符时	——

官方原文："{} 普通变量，{.} list 的变量。如果本来就有'{'、'}' 特殊字符 用'\{'、'\}' 代替。{.前缀可以区分不同的list。"

Critical: 4 种填充场景完整示例

场景 1：简单对象填充

DTO：

@Getter
@Setter
@EqualsAndHashCode
public class FillData {
    private String name;
    private double number;
    private Date date;
}

模板（templates/simple.xlsx）：单元格含 {name} {number} {date}

代码：

@Test
public void simpleFill() {
    String templateFileName = "templates/simple.xlsx";
    String fileName = "output_simpleFill_" + System.currentTimeMillis() + ".xlsx";

    // 方案 1：根据对象填充
    FillData fillData = new FillData();
    fillData.setName("张三");
    fillData.setNumber(5.2);
    EasyExcel.write(fileName).withTemplate(templateFileName).sheet().doFill(fillData);

    // 方案 2：根据 Map 填充
    Map<String, Object> map = new HashMap<>();
    map.put("name", "张三");
    map.put("number", 5.2);
    EasyExcel.write(fileName).withTemplate(templateFileName).sheet().doFill(map);
}

场景 2：列表填充（模板 {.} 占位一行）

模板（templates/list.xlsx）：一行单元格含 {.} 表示 list 起点

代码：

@Test
public void listFill() {
    String templateFileName = "templates/list.xlsx";
    String fileName = "output_listFill_" + System.currentTimeMillis() + ".xlsx";

    // 方案 1：一次性放入内存
    EasyExcel.write(fileName).withTemplate(templateFileName).sheet().doFill(data());

    // 方案 2：分次填充（文件缓存，省内存，推荐）
    try (ExcelWriter excelWriter = EasyExcel.write(fileName)
            .withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = EasyExcel.writerSheet().build();
        excelWriter.fill(data(), writeSheet);
        excelWriter.fill(data(), writeSheet);
    }
}

官方提示："分多次 填充 会使用文件缓存"

场景 3：复杂填充（list 后还有合计行/总计行）

场景特征：模板中 {.} 列表行下面还有非列表内容（如"总计：xxx"）。

@Test
public void complexFill() {
    String templateFileName = "templates/complex.xlsx";
    String fileName = "output_complexFill_" + System.currentTimeMillis() + ".xlsx";

    try (ExcelWriter excelWriter = EasyExcel.write(fileName)
            .withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = EasyExcel.writerSheet().build();
        // ⚠️ 关键：forceNewRow=true 才能让 list 后面再追加内容
        FillConfig fillConfig = FillConfig.builder().forceNewRow(Boolean.TRUE).build();

        excelWriter.fill(data(), fillConfig, writeSheet);
        excelWriter.fill(data(), fillConfig, writeSheet);

        Map<String, Object> map = new HashMap<>();
        map.put("date", "2019年10月9日13:28:28");
        map.put("total", 1000);
        excelWriter.fill(map, writeSheet);
    }
}

官方原文："在 02 版上面 模板 list 不是最后一行 下面还有数据 需要设置 forceNewRow=true 但是有一个缺点 就是他会把所有的数据都放到内存了 慎用" 官方原文："如果数据量大 list不是最后一行 参照下一个（complexFillWithTable）"

场景 4：数据量大的复杂填充（list 放最后一行 + write 追加）

最佳实践模板设计：删除模板中 list 之后的"合计行"占位行，让 list 占最后一行；后续"统计行"用 write 手动追加。

@Test
public void complexFillWithTable() {
    String templateFileName = "templates/complexFillWithTable.xlsx";
    String fileName = "output_complexFillWithTable_" + System.currentTimeMillis() + ".xlsx";

    try (ExcelWriter excelWriter = EasyExcel.write(fileName)
            .withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = EasyExcel.writerSheet().build();

        // 1. 写入 list 数据
        excelWriter.fill(data(), writeSheet);
        excelWriter.fill(data(), writeSheet);

        // 2. 写入 list 之前的变量
        Map<String, Object> map = new HashMap<>();
        map.put("date", "2019年10月9日13:28:28");
        excelWriter.fill(map, writeSheet);

        // 3. list 后面手动 write 统计行
        List<List<String>> totalListList = new ArrayList<>();
        List<String> totalList = new ArrayList<>();
        totalListList.add(totalList);
        totalList.add(null);
        totalList.add(null);
        totalList.add(null);
        totalList.add("统计:1000");
        excelWriter.write(totalListList, writeSheet);
    }
}

官方原文："这里是write 别和fill 搞错了"

场景 5：横向填充（多列横向并列）

@Test
public void horizontalFill() {
    String templateFileName = "templates/horizontal.xlsx";
    String fileName = "output_horizontalFill_" + System.currentTimeMillis() + ".xlsx";

    try (ExcelWriter excelWriter = EasyExcel.write(fileName)
            .withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = EasyExcel.writerSheet().build();
        // 横向：列方向展开
        FillConfig fillConfig = FillConfig.builder()
            .direction(WriteDirectionEnum.HORIZONTAL).build();
        excelWriter.fill(data(), fillConfig, writeSheet);
        excelWriter.fill(data(), fillConfig, writeSheet);

        Map<String, Object> map = new HashMap<>();
        map.put("date", "2019年10月9日13:28:28");
        excelWriter.fill(map, writeSheet);
    }
}

场景 6：多列表组合填充（同时填多个 list）

模板：包含 {data1.} {data2.} {data3.} 三种带前缀的列表

@Test
public void compositeFill() {
    String templateFileName = "templates/composite.xlsx";
    String fileName = "output_compositeFill_" + System.currentTimeMillis() + ".xlsx";

    try (ExcelWriter excelWriter = EasyExcel.write(fileName)
            .withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = EasyExcel.writerSheet().build();
        FillConfig fillConfig = FillConfig.builder()
            .direction(WriteDirectionEnum.HORIZONTAL).build();

        // ⚠️ 关键：多个 list 必须用 FillWrapper 包裹，prefix 必须与模板占位符前缀一致
        excelWriter.fill(new FillWrapper("data1", data()), fillConfig, writeSheet);
        excelWriter.fill(new FillWrapper("data2", data()), writeSheet);  // data2 纵向
        excelWriter.fill(new FillWrapper("data3", data()), writeSheet);

        Map<String, Object> map = new HashMap<>();
        map.put("date", new Date());
        excelWriter.fill(map, writeSheet);
    }
}

官方原文："多个 list 必须用 FillWrapper 包裹；{前缀.} 前缀可以区分不同的 list；不同 list 可以指定不同方向（HORIZONTAL/VERTICAL）"

Critical: Spring Boot 集成

1) 模板放在 resources/templates/

@Service
public class SalaryFillService {

    public void fillSalary(String employeeId, OutputStream out) {
        InputStream templateIn = getClass()
            .getResourceAsStream("/templates/salary.xlsx");
        SalaryDTO data = salaryMapper.findByEmployee(employeeId);

        // 模板以流方式加载，避免临时文件
        try (ExcelWriter writer = EasyExcel.write(out)
                .withTemplate(templateIn).build()) {
            WriteSheet sheet = EasyExcel.writerSheet().build();
            writer.fill(data, sheet);
        }
    }
}

2) Controller 返回

@GetMapping("/export/salary/{employeeId}")
public void exportSalary(@PathVariable String employeeId,
                         HttpServletResponse response) throws IOException {
    response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
    response.setCharacterEncoding("utf-8");
    String fileName = URLEncoder.encode("工资条", "UTF-8").replaceAll("\\+", "%20");
    response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx");

    salaryFillService.fillSalary(employeeId, response.getOutputStream());
}

3) 复杂场景：工资条批量打包

public void batchExportSalary(List<String> employeeIds, OutputStream zipOut) {
    try (ZipOutputStream zos = new ZipOutputStream(zipOut);
         ExcelWriter writer = EasyExcel.write(/* unused */).build()) {  // 实际逐个写入临时文件
        for (String id : employeeIds) {
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            fillSalary(id, baos);
            ZipEntry entry = new ZipEntry("salary_" + id + ".xlsx");
            zos.putNextEntry(entry);
            zos.write(baos.toByteArray());
            zos.closeEntry();
        }
    }
}

Critical: 业务模板设计规范

业务场景	推荐模板设计	关键代码
工资条	单对象 {name} {base} {bonus} {total}	简单填充 方案 1
员工合同	头部 {company} {name} {id} + 列表 {items.}	简单 + 列表
对账单	头部 {date} {account} + 列表 {details.} + 底部"合计"	complexFillWithTable（先 fill 列表再 write 合计行）
财务报表	横向多列 {months.} + 纵向 {rows.}	compositeFill（多个 FillWrapper）
发票	单对象 + 函数 =SUM()	简单填充（公式由模板预置）
商品清单	列表 {products.} + 图片	列表 + 图片（图片需读为 byte[]）
汇总表（按月）	头部 {year} + 列表 {data1.}（横向多列展开）	horizontalFill

Gotchas（常见错误）

#	错误	正确做法
1	Map 填充 list 漏掉某些 key	Map 填充时必须 put 所有 list 的 key（可 value=null）
2	模板有 { } 字符未转义	用 \{ \} 转义
3	复杂填充忘记 forceNewRow=true	list 下面还有内容时必须设置
4	forceNewRow=true 用在百万级数据	改用 complexFillWithTable（list 放最后一行）
5	03 版（.xls）做复杂填充	改用 07 版（.xlsx）
6	list 后追加合计行用 fill	用 write（"这里是write 别和fill 搞错了"）
7	横向多列忘了 FillWrapper	多 list 必须用 new FillWrapper("prefix", list)
8	横向多列方向忘了配	必须 FillConfig.builder().direction(HORIZONTAL)
9	模板文件 withTemplate(InputStream) 用完未关	模板流是缓存的，try-with-resources 关闭
10	关闭 ExcelWriter 时漏掉 finish()	用 try-with-resources 让 ExcelWriter.close() 触发 finish
11	模板文件 > 几十 MB	改用多个小模板分批填充
12	模板变量写错（大小写 / 漏 { }）	模板变量名必须与 Map key / DTO 字段完全一致

Key Classes / Methods

类型	名称	用途
入口	EasyExcel.write(path).withTemplate(template)	指定模板路径或流
入口	EasyExcel.write(OutputStream).withTemplate(stream)	Web 输出流场景
核心	ExcelWriter	多次 fill 的容器，需 try-with-resources
核心	WriteSheet	单个 sheet 配置
配置	FillConfig.builder().forceNewRow(true)	复杂填充（list 后还有内容）
配置	FillConfig.builder().direction(HORIZONTAL)	横向填充
包装	FillWrapper("prefix", list)	多列表分组，前缀匹配模板 {prefix.}
工具	EasyExcel.writerSheet().build()	创建默认 WriteSheet
工具	EasyExcel.writerSheet(0, "sheet名").build()	指定 sheetNo 和名称

References

• 官方文档：https://easyexcel.opensource.alibaba.com/docs/current/quickstart/fill
• 官方示例：https://github.com/alibaba/easyexcel/blob/master/easyexcel-test/src/test/java/com/alibaba/easyexcel/test/demo/fill/FillTest.java
• 项目主页：https://easyexcel.opensource.alibaba.com/
• GitHub：https://github.com/alibaba/easyexcel
• API 参考：https://easyexcel.opensource.alibaba.com/docs/current/api/
• references/api-reference.md — 完整 API 与注解索引
• references/template-design.md — 模板设计规范与真实业务模板
• references/business-scenarios.md — 工资条/合同/对账单/发票等真实案例
• examples/real-cases.md — 6 种填充模式完整可复制代码
• examples/spring-boot-integration.md — Spring Boot 集成完整示例