动态生成带图片的Excel报表：EasyExcel 3.x实战指南
每次手动在Excel里调整图片位置时，我都忍不住想摔键盘——直到发现EasyExcel的模板填充功能。上周公司HR部门提出新需求：要为300名新员工批量生成带照片的工牌Excel，如果手动操作至少需要两天。而用下面这个方法，我们只用了20分钟就完成了全部报表生成。
1. 环境准备与模板设计
1.1 依赖配置要点
在Spring Boot项目中引入关键依赖时，版本兼容性是个隐形杀手。推荐使用以下组合：
<dependency> <groupId>com.alibaba</groupId> <artifactId>easyexcel</artifactId> <version>3.1.1</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>5.2.3</version> </dependency>注意：POI 4.x以上版本与EasyExcel 3.x存在图片写入兼容性问题，实测5.2.3版本最稳定
1.2 智能模板设计技巧
设计模板时，这些细节能让后续开发事半功倍：
- 使用
${variable}作为文本占位符 - 图片位置预留空白单元格并添加批注
<!-- image:fieldName --> - 固定行高列宽避免图片挤压变形
推荐尺寸参数：
| 内容类型 | 行高(px) | 列宽(字符) |
|---|---|---|
| 证件照 | 120 | 15 |
| 产品图 | 200 | 25 |
| 二维码 | 60 | 10 |
2. 动态图片写入核心逻辑
2.1 图片定位算法解析
通过相对位置计算实现智能排版，这段代码可处理多图片自动排列：
public WriteCellData<Void> calculateImagePosition(List<ImageData> images, int columns) { WriteCellData<Void> cellData = new WriteCellData<>(); for (int i = 0; i < images.size(); i++) { ImageData image = images.get(i); int rowGroup = i / columns; int colIndex = i % columns; // 动态计算位置 image.setRelativeFirstRowIndex(rowGroup * 6); image.setRelativeLastRowIndex(rowGroup * 6 + 5); image.setRelativeFirstColumnIndex(colIndex * 4); image.setRelativeLastColumnIndex(colIndex * 4 + 3); } return cellData; }2.2 性能优化实践
处理大批量图片时，这三个技巧将执行时间缩短70%：
- 内存优化：使用ByteArrayOutputStream缓冲图片数据
- 并行处理：对图片分组后使用并行流处理
- 缓存机制：重复图片只读取一次
// 并行处理示例 List<CompletableFuture<ImageData>> futures = imagePaths.stream() .parallel() .map(path -> CompletableFuture.supplyAsync(() -> loadImage(path))) .collect(Collectors.toList()); List<ImageData> images = futures.stream() .map(CompletableFuture::join) .collect(Collectors.toList());3. Spring Boot集成方案
3.1 控制器层最佳实践
这个RESTful接口可直接生成并返回Excel流：
@GetMapping("/export/employee-cards") public void exportEmployeeCards(HttpServletResponse response) throws IOException { response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setHeader("Content-Disposition", "attachment; filename=employee_cards.xlsx"); List<Employee> employees = employeeService.listWithPhotos(); ExcelWriter writer = EasyExcel.write(response.getOutputStream()) .withTemplate(ResourceUtils.getFile("classpath:templates/employee_card.xlsx")) .build(); employees.forEach(emp -> { WriteSheet sheet = EasyExcel.writerSheet("Page " + emp.getDept()).build(); writer.fill(convertToMap(emp), sheet); }); writer.finish(); }3.2 常见坑点解决方案
这些报错你肯定遇到过：
- 图片变形：设置固定宽高比
imageData.setAnchor(new ClientAnchor(0, 0, 0, 0, col, row, col+2, row+4)); - 内存溢出：分批次写入并及时清理缓存
- 格式错乱：统一使用PNG格式图片
4. 高级应用场景拓展
4.1 混合内容报表生成
结合文本、图片、条形码的复合报表解决方案：
- 使用
Map<String, Object>混合不同类型数据 - 分层填充策略：先文本后图片
- 动态调整模板样式
Map<String, Object> data = new HashMap<>(); data.put("title", "产品质检报告"); data.put("items", productList); // 文本列表 data.put("signature", getSignatureImage()); // 签名图片 data.put("barcode", generateBarcode()); // 条形码4.2 云端文件处理方案
当图片存储在OSS等云端服务时，这样处理最优雅：
public ImageData loadFromOSS(String ossUrl) { OSS ossClient = new OSSClientBuilder().build(endpoint, accessKey, secretKey); try (InputStream stream = ossClient.getObject(bucketName, objectName).getObjectContent()) { ImageData image = new ImageData(); image.setImage(IOUtils.toByteArray(stream)); return image; } finally { ossClient.shutdown(); } }报表生成后自动上传到云存储的完整流程：
- 本地生成临时文件
- 使用断点续传分片上传
- 清理本地临时文件
- 返回下载链接
String uploadId = ossClient.initiateMultipartUpload(bucketName, objectName).getUploadId(); List<PartETag> partETags = new ArrayList<>(); // 分片上传逻辑... ossClient.completeMultipartUpload(new CompleteMultipartUploadRequest( bucketName, objectName, uploadId, partETags));
