Java 填充 Word 模板工具类实现

前言

最近有个 Java 填充 Word 模板的需求，包括文本、列表和复选框勾选，写一个工具类，以此记录。

一、设置 word 模板

选择文档中要填充的地方点击 -> 选择插入 -> 文档部件 -> 域 -> 域名 (mergeField) -> 填写变量名称。

普通字段

[图片]

填充完毕： [图片]

列表字段

操作和普通字段一样，区别是需要在首行第一列插入列表开始域，首行最后一列插入结束域，中间正常字段。格式为：StartTable:<数组字段名>，EndTable:<数组字段名> [图片]

复选框

复选框找了好多种方法尝试没有成功，最后取巧，和普通字段一样设置占位符，通过代码逻辑处理。 [图片]

二、代码

1. 引入依赖

poi/hutool/aspose-words/gson：

<!-- hutool 工具类 -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.7.14</version>
</dependency>
<!-- word 模板数据解析 -->
<dependency>
    <groupId>com.deepoove</groupId>
    <artifactId>poi-tl</artifactId>
    <version>1.9.0-beta</version>
</dependency>
<!-- word/pdf 操作 -->
<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-words</artifactId>
    <version>18.8</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.9</version>
</dependency>

2. 模板放入项目

这里是放在项目里，也可以放在云上存储。 [图片]

License 文件放入 resources，否则会有水印。Aspose.Words 在 Maven 仓库中如果没有 License 包，需要下载后安装在本地仓库。

安装命令

mvn install:install-file -Dfile=路径/aspose-words-18.8.jar -DgroupId=com.aspose -DartifactId=aspose-words -Dversion=18.8 -Dpackaging=jar

引入 License 配置 注意：Aspose.Words 需要有效 License 文件，此处省略具体配置内容，请确保拥有合法授权。

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("小王", "2020-01-01", "2020-01-01", "小王"),
            new ExperienceList("小王", "2020-01-01", "2020-01-01", "小王")
        ));
        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.DataRow;
import com.aspose.words.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 大小
     * @param source BufferedImage 原始 image
     * @param targetW int 目标宽
     * @param targetH int 目标高
     * @param flag boolean 是否同比例调整
     * @return BufferedImage 返回新 image
     */
    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 数据格式）
     *
     * @param modelWordByte word 模版二进制文件
     * @param obj 要填充的数据
     * @return 组合数据之后的 word 二进制
     */
    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 数据格式）
     *
     * @param file word 二进制
     * @param data 要填充的数据
     * @return 组合数据之后的 word 二进制
     */
    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;
    }

    /**
     * 勾选段落中的复选框字段（适用于 Aspose.Words 18.8）
     */
    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 表格）
     *
     * @param list 数据
     * @param tableName 表格列表变量名称
     * @return word 表格数据 DataTable
     */
    private static DataTable fillListData(List<Object> list, String tableName, DocumentBuilder builder) throws Exception {
        //创建 DataTable，并绑定字段
        DataTable dataTable = new DataTable(tableName);
        for (Object obj : list) {
            //创建 DataRow，封装该行数据
            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");
            License license = new License();
            license.setLicense(is);
        } catch (Exception e) {
            throw new RuntimeException("自动加载 aspose 证书文件失败!");
        }
    }
}

三、测试

main 方法测试，可以根据实际需求改为 response 输出或者上传到存储服务器后返回链接地址。

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 中依次点击「文件→选项→高级」，在「显示文档内容」区域勾选「显示域代码而非域值」，找到报错域代码后删除，重新添加域就解决了。