问题：如何使用POI将图片精确插入Excel指定单元格？

Question

在使用 Apache POI 操作 Excel 时，如何将图片精确插入到指定单元格是一个常见难题。POI 提供了插入图片的 API，但默认以像素为单位定位，难以直接与单元格行列对齐。开发者常遇到图片位置偏移、覆盖多个单元格或无法精确定位等问题。解决该问题的关键在于理解 POI 的绘图机制和锚点设置，特别是通过 `ClientAnchor` 控制图片的位置和大小。需要合理设置起始和结束行列、调整偏移量，并结合 `XSSFClientAnchor`（针对 .xlsx 格式）或 `HSSFClientAnchor`（针对 .xls 格式）实现精准定位。此外，还需处理图片缩放、单元格合并等复杂场景，确保导出的 Excel 文件在不同分辨率和窗口缩放下显示正常。

Answer 1

Apache POI 操作 Excel 中图片插入的精确定位策略

1. 图片插入的基本机制

Apache POI 提供了对 Excel 文件（.xls 和 .xlsx）的读写能力。在插入图片时，POI 使用 ClientAnchor 来控制图片的位置和大小。该类的子类 XSSFClientAnchor（用于 .xlsx）和 HSSFClientAnchor（用于 .xls）决定了图片插入的锚点。

图片插入的基本步骤如下：

1. 加载图片文件为字节数组；
2. 通过 Workbook 的 addPicture 方法将图片添加到工作簿；
3. 创建 ClientAnchor 实例，并设置锚点行列位置；
4. 通过 Sheet 的 createDrawingPatriarch 方法创建绘图对象；
5. 调用 drawPicture 方法插入图片。

2. ClientAnchor 的结构与参数详解

ClientAnchor 的构造方法通常接受以下参数（以 XSSFClientAnchor 为例）：

参数名	说明
dxa1	左上角在起始单元格中的横向偏移量（单位：1/1024 单元格宽度）
dya1	左上角在起始单元格中的纵向偏移量（单位：1/256 单元格高度）
dxa2	右下角在结束单元格中的横向偏移量
dya2	右下角在结束单元格中的纵向偏移量
col1	起始列索引（从0开始）
row1	起始行索引（从0开始）
col2	结束列索引
row2	结束行索引

例如，若希望图片完全占据 A1 单元格，可设置 col1=0, row1=0, col2=1, row2=1，并设置偏移量为 0。

3. 精确定位的实现方法

以下为插入图片到 A1 单元格的示例代码：

FileInputStream fis = new FileInputStream("logo.png");
byte[] pictureData = IOUtils.toByteArray(fis);
int pictureIdx = workbook.addPicture(pictureData, Workbook.PICTURE_TYPE_PNG);
CreationHelper helper = workbook.getCreationHelper();
Drawing drawing = sheet.createDrawingPatriarch();

ClientAnchor anchor = helper.createClientAnchor();
anchor.setCol1(0);
anchor.setRow1(0);
anchor.setCol2(1);
anchor.setRow2(1);
anchor.setDx1(0);
anchor.setDy1(0);
anchor.setDx2(0);
anchor.setDy2(0);

Picture picture = drawing.createPicture(anchor, pictureIdx);
picture.resize(); // 自动适应锚点区域

其中 resize() 方法会根据锚点区域自动调整图片大小。如需自定义缩放比例，可使用 resize(double scaleX, double scaleY)。

4. 处理复杂场景：合并单元格与缩放适配

当图片插入到合并单元格时，需确保 col1, row1, col2, row2 与合并区域一致。例如，若 A1:D4 被合并，锚点应设为 col1=0, row1=0, col2=4, row2=4。

此外，图片在 Excel 中的显示可能受窗口缩放影响。为保证显示一致性，建议：

• 使用 setAnchorType 设置图片锚定方式（如随单元格移动或固定位置）；
• 在导出前设置单元格大小（行高、列宽）以匹配图片尺寸；
• 避免使用绝对像素偏移，尽量使用相对偏移（如单元格宽度的百分比）。

5. 图片插入流程图

graph TD A[准备图片数据] --> B[添加图片到工作簿] B --> C[创建绘图对象] C --> D[创建 ClientAnchor 锚点] D --> E[设置锚点行列与偏移量] E --> F[绘制图片] F --> G[调整图片大小] G --> H[完成插入]