NPOI实战：在Word文档中高效插入图片的完整指南

在日常办公自动化中，经常需要将图片嵌入到Word文档中。NPOI作为一款开源的.NET库，完美支持操作Office文档，尤其是Word（.docx）格式。本文将带你深入理解如何使用NPOI在Word中插入图片，从环境搭建到高级技巧，一步到位。

一、准备工作

首先，通过NuGet安装NPOI包：

Install-Package NPOI

确保项目目标框架为.NET Framework 4.5+或.NET Core/5/6/7等。NPOI目前支持XWPF（用于Word 2007+ .docx格式）和HWPF（用于旧版.doc格式），我们重点介绍XWPF。

二、核心步骤

1. 创建或加载文档：使用XWPFDocument类。
2. 获取段落：通过文档的Paragraphs集合或创建新段落。
3. 插入图片：使用XWPFRun.AddPicture()方法。
4. 设置图片属性：宽度、高度、环绕方式等。
5. 保存文档：写入文件流。

三、代码示例

以下是一个完整的控制台程序示例，展示如何插入一张本地图片：

using NPOI.XWPF.UserModel;
using System.IO;

class Program
{
    static void Main(string[] args)
    {
        // 1. 创建文档
        using (var doc = new XWPFDocument())
        {
            // 2. 创建段落
            XWPFParagraph paragraph = doc.CreateParagraph();
            paragraph.Alignment = ParagraphAlignment.CENTER;

            // 3. 创建Run（文本块）
            XWPFRun run = paragraph.CreateRun();
            run.SetText("下方的图片展示了NPOI的强大能力：");
            run.AddBreak();

            // 4. 插入图片
            using (FileStream picStream = new FileStream(@"C:\example.jpg", FileMode.Open, FileAccess.Read))
            {
                // 参数：图片ID（随意），图片宽度（单位：像素），高度，图片流，图片类型
                string id = doc.AddPictureData(picStream, (int)PictureType.JPEG);
                // 在Run中添加图片
                run.AddPicture(new MemoryStream(File.ReadAllBytes(@"C:\example.jpg")), 
                               (int)PictureType.JPEG, "example.jpg", 200, 150);
            }

            // 5. 保存文档
            using (FileStream outStream = new FileStream(@"C:\output.docx", FileMode.Create, FileAccess.Write))
            {
                doc.Write(outStream);
            }
        }
        Console.WriteLine("Word文档生成成功！");
    }
}

注意：上述代码中，AddPicture方法的第三个参数是图片文件名（用于内部索引），并不要求实际文件名。

四、常见问题与解决方案

• 图片无法显示：检查图片流是否有效，以及图片类型枚举是否正确（PictureType）。
• 图片位置偏移：可以使用CT_Picture设置simplePos属性，或者通过XWPFParagraph的对齐方式控制。
• 图片大小控制：AddPicture提供宽度和高度参数（单位：EMU？实际为像素值，但内部会转换）。更精确可借助XWPFPicture对象设置。
• 多张图片：每个Run可以包含多张图片，只需多次调用AddPicture。

五、高级技巧

1. 设置图片环绕方式：通过XWPFRun的CT_R属性操作底层XML，例如设置wrap属性为square或topAndBottom。

// 获取CT_Picture
CT_Picture ctPic = run.GetCTR().GetPictureArray(0);
ctPic.effectExtent = new CT_PositiveSize2D() { cx = 200000, cy = 200000 };
// 更多环绕设置需要操作元素。

2. 从网络插入图片：先下载为字节数组，再转为内存流。

3. 批量插入：循环遍历图片文件夹，将图片逐个插入到表格单元格或段落中。

六、总结

NPOI为.NET开发者提供了接近原生的Word操作能力，插入图片仅是冰山一角。掌握上述方法后，你可以自由组合文本和图像，生成复杂的报告、合同或宣传材料。如果在实践中遇到问题，欢迎查阅NPOI官方文档或社区讨论。

最后，别忘了及时释放流资源，避免内存泄漏。快乐编码！