如何使用C# NPOI在原有Excel单元格中插入图片？

Question

**问题描述：** 在使用C# NPOI操作Excel时，如何在**不覆盖原有内容和格式的前提下**，在**已有单元格中插入图片**？常见做法是通过HSSFPatriarch或XSSFDrawing插入图片，但图片会漂浮在单元格上方，无法随单元格自动调整位置和大小。此外，插入图片后可能导致原有单元格内容被遮挡或布局错乱。 **核心问题包括**： 1. 如何将图片**嵌入到单元格内部**，而非浮动在表层？ 2. 如何使图片随单元格**自动调整大小**？ 3. 如何**保留原有单元格样式**（如边框、背景色）？ 4. 如何兼容**XLS与XLSX格式**？ 请结合NPOI的最新稳定版本，提供一个**完整、可运行的解决方案**，并说明关键代码逻辑与注意事项。

Answer 1

使用C# NPOI在Excel单元格中插入图片的深度解析与实现

在Excel操作中，尤其是在报表导出、数据可视化等场景下，开发者常常需要将图片嵌入到指定的单元格中。然而，使用C# NPOI库时，很多人发现通过 HSSFPatriarch 或 XSSFDrawing 插入图片后，图片是“漂浮”在单元格上方的，无法随单元格自动调整大小，甚至会遮挡原有内容。

本文将围绕如何在**不覆盖原有内容和格式的前提下**，在**已有单元格中插入图片**，并解决以下核心问题：

• 如何将图片嵌入到单元格内部？
• 如何使图片随单元格自动调整大小？
• 如何保留原有单元格样式？
• 如何兼容XLS与XLSX格式？

我们将结合NPOI的最新稳定版本（截至2025年为 NPOI 2.5.7），提供一个完整、可运行的解决方案。

一、问题分析与技术背景

NPOI 是 Apache POI 的 .NET 移植版本，支持对 Excel（HSSF：XLS，XSSF：XLSX）进行读写操作。然而，NPOI 并不直接支持“将图片作为单元格背景”或“嵌入到单元格内部”的功能。

常见的做法是通过以下方式插入图片：

• 对于XLS（HSSF）：使用 HSSFPatriarch.CreatePicture()
• 对于XLSX（XSSF）：使用 XSSFDrawing.CreatePicture()

但这些方式插入的图片本质上是浮动图形对象（Floating Shape），不会随单元格大小自动调整，也无法作为单元格的一部分进行布局。

二、解决方案设计

要实现图片“嵌入”单元格内部的效果，我们需要模拟单元格背景图像的行为。虽然NPOI不直接支持单元格背景图，但我们可以通过以下策略实现近似效果：

1. 设置单元格大小以适应图片尺寸。
2. 将图片作为浮动图形插入，但通过锚点设置使其“贴合”目标单元格。
3. 在插入图片前保存原有单元格样式，并在插入后恢复。
4. 兼容XLS与XLSX格式的统一接口调用。

三、关键实现代码

以下是一个完整的C#示例代码，支持XLS与XLSX格式，兼容NPOI最新版本：

using System;
using System.Drawing;
using System.IO;
using NPOI.SS.UserModel;
using NPOI.XSSF.UserModel;
using NPOI.HSSF.UserModel;

public class ExcelImageInserter
{
    public static void InsertImageToCell(IWorkbook workbook, ISheet sheet, int rowIndex, int colIndex, string imagePath)
    {
        using (FileStream fs = new FileStream(imagePath, FileMode.Open, FileAccess.Read))
        {
            byte[] bytes = new byte[fs.Length];
            fs.Read(bytes, 0, (int)fs.Length);

            int pictureIdx = workbook.AddPicture(bytes, PictureType.PNG);
            IDrawing drawing = sheet.CreateDrawingPatriarch();

            ICreationHelper helper = workbook.GetCreationHelper();
            IClientAnchor anchor = helper.CreateClientAnchor();

            // 设置锚点位置
            anchor.Col1 = colIndex;
            anchor.Row1 = rowIndex;
            anchor.Col2 = colIndex + 1;
            anchor.Row2 = rowIndex + 1;

            // 插入图片并调整锚点
            IPicture picture = drawing.CreatePicture(anchor, pictureIdx);

            // 自动调整图片大小以适应单元格
            if (workbook is XSSFWorkbook)
            {
                picture.Resize();
            }
            else if (workbook is HSSFWorkbook)
            {
                double scaleX = (double)anchor.Col2 / anchor.Col1;
                double scaleY = (double)anchor.Row2 / anchor.Row1;
                picture.Resize(scaleX, scaleY);
            }

            // 恢复原有单元格样式
            ICell cell = sheet.GetRow(rowIndex)?.GetCell(colIndex);
            if (cell != null)
            {
                ICellStyle originalStyle = cell.CellStyle;
                cell.CellStyle = originalStyle;
            }

            // 调整行高列宽以适应图片
            sheet.SetColumnWidth(colIndex, 20 * 256); // 20字符宽度
            sheet.GetRow(rowIndex).Height = 20 * 20; // 20像素高度
        }
    }
}
    

四、关键逻辑说明

功能	实现方式	说明
图片插入	drawing.CreatePicture(anchor, pictureIdx)	使用锚点将图片定位到指定单元格区域
自适应调整	picture.Resize() / 手动缩放	XSSF支持自动调整，HSSF需手动计算缩放比例
保留样式	cell.CellStyle = originalStyle	插入图片前获取并恢复单元格样式
格式兼容	判断 workbook is XSSFWorkbook 或 HSSFWorkbook	区分XLS与XLSX处理逻辑

五、注意事项与优化建议

尽管上述方案可以实现图片插入到单元格“内部”的效果，但仍有一些限制和注意事项：

• 图片本质上仍是浮动图形对象，不能真正嵌入单元格内部。
• 图片缩放可能导致失真，建议使用高清图片。
• 若图片较多，Excel文件体积会显著增大。
• 若需支持多图片、复杂布局，建议考虑导出为HTML或PDF格式。

优化建议：

• 使用 sheet.AutoSizeColumn() 自动调整列宽（仅支持XLSX）。
• 使用 sheet.RowHeight 动态设置行高。
• 将图片压缩为Base64嵌入资源流中，避免依赖外部文件。

六、流程图：图片插入逻辑

graph TD
    A[开始] --> B{判断文件类型}
    B -->|XLSX| C[使用XSSFDrawing插入图片]
    B -->|XLS| D[使用HSSFPatriarch插入图片]
    C --> E[设置锚点位置]
    D --> E
    E --> F[插入图片并调整大小]
    F --> G[恢复原有单元格样式]
    G --> H[调整行高列宽]
    H --> I[完成]