Java 填充 Word 模板实战：文本、列表与复选框处理

2. 资源准备

将模板文件放入项目的 resources 目录下。如果需要使用 Aspose.Words 且不希望出现水印，需配置有效的 License 文件。

注意： 生产环境请务必使用正版授权文件，避免法律风险。将 License.xml 放在 resources 根路径下。

3. 核心代码

实体类定义

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.io.Serializable;
import java.util.Arrays;
import java.util.List;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class FillWordDTO implements Serializable {
    private String name;
    private String age;
    private String yuyan;
    private String yingyu;
    private String deyu;
    private String fayu;
    private String zhengshu;
    private String yiji;
    private String erji;
    private List<ExperienceList> experienceList;

    public static FillWordDTO create() {
        FillWordDTO fillWordDTO = new FillWordDTO();
        fillWordDTO.setName("小王");
        fillWordDTO.setAge("18");
        // 模拟复选框状态
        fillWordDTO.setYuyan("☑");
        fillWordDTO.setYingyu("☑");
        fillWordDTO.setDeyu("□");
        fillWordDTO.setFayu("☑");
        fillWordDTO.setZhengshu("☑");
        fillWordDTO.setYiji("☑");
        fillWordDTO.setErji("□");
        fillWordDTO.setExperienceList(Arrays.asList(
            new ExperienceList("学校 A", "2020-01-01", "2020-01-01", "备注 A"),
            new ExperienceList("学校 B", "2020-01-01", "2020-01-01", "备注 B")
        ));
        return fillWordDTO;
    }
}

@Data
@AllArgsConstructor
@NoArgsConstructor
class ExperienceList {
    private String school;
    private String startTime;
    private String endTime;
    private String remark;
}

工具类实现

import com.aspose.words.*;
import com.aspose.words.net.System.Data.DataRow;
import com.aspose.words.net.System.Data.DataTable;
import java.awt.*;
import java.awt.geom.AffineTransform;
import java.awt.image.BufferedImage;
import java.beans.PropertyDescriptor;
import java.io.*;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class ContractUtil {
    private ContractUtil() {}

    /**
     * 调整 BufferedImage 大小
     */
    public static BufferedImage resizeBufferedImage(BufferedImage source, int targetW, int targetH, boolean flag) {
        int type = source.getType();
        BufferedImage target = null;
        double sx = (double) targetW / source.getWidth();
        double sy = (double) targetH / source.getHeight();
        if (flag && sx > sy) {
            sx = sy;
            targetW = (int) (sx * source.getWidth());
        } else if (flag && sx <= sy) {
            sy = sx;
            targetH = (int) (sy * source.getHeight());
        }
        if (type == BufferedImage.TYPE_CUSTOM) {
            ColorModel cm = source.getColorModel();
            WritableRaster raster = cm.createCompatibleWritableRaster(targetW, targetH);
            boolean alphaPremultiplied = cm.isAlphaPremultiplied();
            target = new BufferedImage(cm, raster, alphaPremultiplied, null);
        } else {
            target = new BufferedImage(targetW, targetH, type);
        }
        Graphics2D g = target.createGraphics();
        g.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY);
        g.drawRenderedImage(source, AffineTransform.getScaleInstance(sx, sy));
        g.dispose();
        return target;
    }

    /**
     * 填充 Word 模板（Object 数据格式）
     */
    public static byte[] fillWordDataByDomain(byte[] modelWordByte, Object obj) {
        try {
            Class<?> aClass = obj.getClass();
            Field[] fields = aClass.getDeclaredFields();
            Map<String, Object> data = new HashMap<>(fields.length);
            for (Field field : fields) {
                PropertyDescriptor pd = new PropertyDescriptor(field.getName(), aClass);
                Method method = pd.getReadMethod();
                String key = field.getName();
                Object value = method.invoke(obj);
                if (value != null) {
                    data.put(key, value);
                }
            }
            return fillWordDataByMap(modelWordByte, data);
        } catch (Exception e) {
            e.printStackTrace();
            return new byte[0];
        }
    }

    /**
     * 填充 Word 模板（Map 数据格式）
     */
    public static byte[] fillWordDataByMap(byte[] file, Map<String, Object> data) throws Exception {
        byte[] ret = null;
        if (data == null || data.isEmpty()) {
            return ret;
        }
        try (InputStream is = new ByteArrayInputStream(file);
             ByteArrayOutputStream out = new ByteArrayOutputStream()) {
            Document doc = new Document(is);
            DocumentBuilder builder = new DocumentBuilder(doc);
            Map<String, String> toData = new HashMap<>();
            for (Map.Entry<String, Object> entry : data.entrySet()) {
                String key = entry.getKey();
                Object value = entry.getValue();
                // 处理表格数据
                if (value instanceof List && !key.equals("checkboxOptions")) {
                    DataTable dataTable = fillListData((List) value, key, builder);
                    doc.getMailMerge().executeWithRegions(dataTable);
                }
                // 图片插入
                else if (value instanceof BufferedImage) {
                    builder.moveToMergeField(key);
                    builder.insertImage((BufferedImage) value);
                }
                // 其他普通字段正常填充
                else {
                    String valueStr = String.valueOf(value);
                    if (value != null && !"null".equals(valueStr)) {
                        toData.put(key, valueStr);
                    }
                }
            }
            // 执行普通字段合并
            String[] fieldNames = new String[toData.size()];
            String[] values = new String[toData.size()];
            int i = 0;
            for (Map.Entry<String, String> entry : toData.entrySet()) {
                fieldNames[i] = entry.getKey();
                values[i] = entry.getValue();
                i++;
            }
            doc.getMailMerge().execute(fieldNames, values);
            doc.save(out, SaveOptions.createSaveOptions(SaveFormat.DOCX));
            ret = out.toByteArray();
        }
        return ret;
    }

    /**
     * 勾选段落中的复选框字段
     */
    private static void checkTheCheckbox(Paragraph paragraph) throws Exception {
        FieldCollection fields = paragraph.getRange().getFields();
        int count = fields.getCount();
        for (int i = 0; i < count; i++) {
            com.aspose.words.Field field = fields.get(i);
            if (field.getType() == FieldType.FIELD_FORM_CHECK_BOX) {
                setCheckboxChecked(field, true);
            }
        }
    }

    private static void setCheckboxChecked(com.aspose.words.Field field, boolean checked) throws Exception {
        if (checked) {
            field.setResult("✓");
        } else {
            field.setResult("□");
        }
    }

    /**
     * 封装 list 数据到 Word 模板中（Word 表格）
     */
    private static DataTable fillListData(List<Object> list, String tableName, DocumentBuilder builder) throws Exception {
        DataTable dataTable = new DataTable(tableName);
        for (Object obj : list) {
            DataRow dataRow = dataTable.newRow();
            Class<?> objClass = obj.getClass();
            Field[] fields = objClass.getDeclaredFields();
            for (int i = 0; i < fields.length; i++) {
                Field field = fields[i];
                dataTable.getColumns().add(fields[i].getName());
                PropertyDescriptor pd = new PropertyDescriptor(field.getName(), objClass);
                Method method = pd.getReadMethod();
                dataRow.set(i, method.invoke(obj));
            }
            dataTable.getRows().add(dataRow);
        }
        return dataTable;
    }

    /**
     * 加载 License
     * 由于 Aspose 是收费软件，若没有有效 License，则会出现水印。
     */
    static {
        try {
            InputStream is = ContractUtil.class.getResourceAsStream("/License.xml");
            if (is != null) {
                License license = new License();
                license.setLicense(is);
            }
        } catch (Exception e) {
            // 忽略异常，若无 License 文件则保留默认行为
        }
    }
}

三、测试

在 main 方法中调用，实际场景可改为返回 Response 或上传至 OSS 后返回链接。

public static void main(String[] args) throws IOException {
    FillWordDTO fillWordDTO = FillWordDTO.create();
    // 读取模板文件
    byte[] modelByte = Files.readAllBytes(Paths.get("src/main/resources/templates/test.docx"));
    // 调用工具类
    byte[] resultByte = ContractUtil.fillWordDataByDomain(modelByte, fillWordDTO);
    // 输出结果
    File resultFile = new File("demo.docx");
    FileOutputStream fos = new FileOutputStream(resultFile);
    fos.write(resultByte);
    fos.close();
}

四、注意事项

编辑 Word 域代码时，有时隐藏代码会导致填充失败，报错信息如： Found end of mail merge region 'experienceList' that does not match start of mail merge region 'jlList'.

排查方法： 在 Word 中依次点击「文件→选项→高级」，在「显示文档内容」区域勾选「显示域代码而非域值」。找到报错的域代码后删除，重新添加正确的域即可解决。