如何使用BufferedImage或URL替换DOCX模板中的图片占位符

在Java中处理DOCX模板的图片替换，核心是用Apache POI操作DOCX的内部结构，识别占位符图片后替换其二进制数据。以下是具体实现方案：

1. 准备依赖 #

确保项目引入Apache POI及相关依赖（以Maven为例）：

<dependencies>
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi</artifactId>
        <version>5.2.5</version>
    </dependency>
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml</artifactId>
        <version>5.2.5</version>
    </dependency>
    <!-- 若需生成条形码，引入ZXing库 -->
    <dependency>
        <groupId>com.google.zxing</groupId>
        <artifactId>core</artifactId>
        <version>3.5.1</version>
    </dependency>
    <dependency>
        <groupId>com.google.zxing</groupId>
        <artifactId>javase</artifactId>
        <version>3.5.1</version>
    </dependency>
</dependencies>

2. 核心实现逻辑 #

工具方法：图片格式转换 #

先封装两个工具方法，用于将URL图片转为BufferedImage，以及将BufferedImage转为字节数组（DOCX图片存储的格式）：

import org.apache.poi.xwpf.usermodel.*;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.net.URL;

// 将BufferedImage转为字节数组
private static byte[] bufferedImageToBytes(BufferedImage image, String format) throws IOException {
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    ImageIO.write(image, format, baos);
    return baos.toByteArray();
}

// 从URL读取图片为BufferedImage
private static BufferedImage getImageFromUrl(String imageUrl) throws IOException {
    URL url = new URL(imageUrl);
    return ImageIO.read(url);
}

替换占位符的主逻辑 #

通过遍历DOCX中的所有图片数据，根据文件名/ALT文本识别占位符，替换为目标图片：

import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFPictureData;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;

public static void replaceTemplateImages(String templatePath, String outputPath) throws IOException {
    // 加载DOCX模板
    XWPFDocument doc = new XWPFDocument(new FileInputStream(templatePath));

    // 遍历文档中所有图片资源
    for (XWPFPictureData pictureData : doc.getAllPictures()) {
        String picFileName = pictureData.getFileName();
        byte[] newImageBytes = null;

        // 方式1：通过文件名识别占位符（建议模板中给占位符图片命名为固定名称）
        if ("logo_placeholder.png".equals(picFileName)) {
            // 从URL获取logo图片并转换
            BufferedImage logoImage = getImageFromUrl("https://your-domain.com/your-logo.png");
            newImageBytes = bufferedImageToBytes(logoImage, "png");
            // 更新图片数据和文件名
            pictureData.setData(newImageBytes);
            pictureData.setFileName("custom-logo.png");
        } 
        // 替换条形码占位符
        else if ("barcode_placeholder.png".equals(picFileName)) {
            // 生成条形码BufferedImage（示例用ZXing）
            BufferedImage barcodeImage = generateBarcode("1234567890");
            newImageBytes = bufferedImageToBytes(barcodeImage, "png");
            pictureData.setData(newImageBytes);
            pictureData.setFileName("order-barcode.png");
        }

        // 方式2：通过ALT文本识别占位符（如果模板中给图片设置了ALT描述）
        // for (XWPFParagraph para : doc.getParagraphs()) {
        //     for (XWPFRun run : para.getRuns()) {
        //         for (XWPFPicture pic : run.getEmbeddedPictures()) {
        //             String altText = pic.getCTPicture().getPic().getNonVisualPicProps().getNonVisualDrawingProps().getDescr();
        //             if ("logo-placeholder".equals(altText)) {
        //                 // 替换逻辑同上
        //             }
        //         }
        //     }
        // }
    }

    // 保存修改后的文档
    try (FileOutputStream fos = new FileOutputStream(outputPath)) {
        doc.write(fos);
    }
    doc.close();
}

// 示例：用ZXing生成条形码BufferedImage
private static BufferedImage generateBarcode(String code) {
    try {
        com.google.zxing.Writer writer = new com.google.zxing.oned.Code128Writer();
        com.google.zxing.common.BitMatrix matrix = writer.encode(
            code,
            com.google.zxing.BarcodeFormat.CODE_128,
            300, 100
        );
        return com.google.zxing.client.j2se.MatrixToImageWriter.toBufferedImage(matrix);
    } catch (Exception e) {
        throw new RuntimeException("生成条形码失败", e);
    }
}

3. 关键注意事项 #

• 占位符识别：优先给模板中的占位符图片设置固定文件名，或设置ALT文本，方便精准识别；
• 图片格式兼容：替换的图片格式需与原占位符一致（如原是PNG则用PNG），避免DOCX渲染异常；
• POI版本：使用5.x以上的POI版本，API更稳定，避免旧版本的兼容性问题；
• 资源释放：操作完成后务必关闭XWPFDocument和流资源，避免内存泄漏。

内容的提问来源于stack exchange，提问作者javalove