FreeMarker生成word文档

简介

最近项目中有需要根据模版生成对应的 word 文档的需求，这里使用 FreeMarker 来快速生成。

主要步骤为：

1. 将 word 中需要填充的数据用占位符${变量名}替换。
2. 将该 word 另存为 .xml 的格式，并检查看格式是否有误（主要看占位符有没被分割开来）。
3. 将后缀.xml改成.ftl后，再调用相关 API 即可生成 word 文档。

创建模版文件

我们最终要生成的 word 效果图如下：

首先制作模版文件，将要填写的数据位置用占位符替代，勾选框这里需要将 2 种情况的框框都加上去，如下图所示：

其次，另存为 .xml 文件，可用文本编辑器查看该文件，看是否有占位符被分隔开的情况，如果有，只需将中间多余的部分删除即可。

最后保存为.ftl 文件。

处理普通文本

处理文本比较简单，在原文件中直接用占位符 ${} 替换即可。

处理表格

处在生成 word 表格时，FreeMarker 是利用列表一行一行循环填充的，而表头只会生成一次，因此我们还需手动改动一下 .ftl 文件。

注意：<w:tbl> 表示一个表格 、<w: tr> 表示一行、<w: tc> 表示一列，我们先找到第一行填充数据的那行，在前后分别加上如下语句即可：

<#list itemList as item>
</#list>

另一种情况：还有一种情况，即需要进行单元格的合并操作，前面和上面都差不多，不过还要加上另一种标签：

<w:vMerge w:val='restart'/>
<w:vMerge/>

我们先用 ${item.startMerge}（开始合并）和 ${item.endMerge}（结束合并）分别替换上面2行。

回过头再看下效果图，我们可以看到第一列分组是有合并单元格存在的，因此，找到第一列的 <w: tc> 那，如下图所示：

这里需结合下面 java 代码一起看，较好理解。

处理勾选框

有勾选框的情况，我们要用到 Freemarker 中的 if else 标签，如下图所示，我们在模版中加了一个有勾选的框，一个没有勾选的框，所以，在这里会有2种不同的格式，我们用 if else 标签区分开来。

以上就是 Freemarker 对几种类型的处理了，接下来就创建 Java 项目来生成 Word 文档。

创建Java项目

1.导入相关依赖

我们主要用到了 FreeMarker，在这里，只需要导入以下依赖即可：

 <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>

2.生成 word 的工具类

import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.Version;

import java.io.BufferedWriter;
import java.io.FileOutputStream;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.util.Map;

public class WordUtils {

    /**
     * 生成 word 文档方法
     *
     * @param dataMap      要填充的数据
     * @param templateName 模版名称
     * @param fileName     要输出的文件路径
     * @throws Exception 抛出的异常
     */
    public static void generateWord(Map<String, Object> dataMap, String templateName, String fileName) throws Exception {

        // 设置FreeMarker的版本和编码格式
        Configuration configuration = new Configuration(new Version("2.3.28"));
        configuration.setDefaultEncoding("UTF-8");

        // 设置FreeMarker生成Word文档所需要的模板的路径
        // configuration.setDirectoryForTemplateLoading(new File("/Users/xxx/Desktop/"));
        // 此处把模版文件都放在 resources 下的 templates 中
        configuration.setClassForTemplateLoading(WordUtils.class, "/templates");

        // 设置FreeMarker生成Word文档所需要的模板
        Template tem = configuration.getTemplate(templateName, "UTF-8");
        // 创建一个Word文档的输出流
        Writer out = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(new File(fileName)), StandardCharsets.UTF_8));
        // FreeMarker使用Word模板和数据生成Word文档
        tem.process(dataMap, out);
        out.flush();
        out.close();
    }
}

3.准备填充所需的数据

一般来说，我们的数据可能是从数据库中查询出来的各种对象，这里为了方便，就直接利用 HashMap 存储数据了。

 public static Map<String,Object> initData(){
        // 对应单元格的合并
        final String startMerge = "<w:vMerge w:val='restart'/>";
        final String endMerge = "<w:vMerge/>";
        
        final LocalDate nowDate = LocalDate.now();
        Map<String, Object> data = new HashMap<>();
        data.put("userName", "张三");
        data.put("gender", "男");
        data.put("birthday", nowDate);

        List<Item> itemList = new ArrayList<>();
        Item item1 = new Item();
        item1.setGroup("分组A")
                .setName("张三")
                .setSubject("数学")
                .setScore(90)
                .setStartMerge(startMerge);
        itemList.add(item1);

        Item item2 = new Item();
        item2.setGroup("分组A")
                .setName("李四")
                .setSubject("语文")
                .setScore(85)
                .setEndMerge(endMerge);
        itemList.add(item2);

        Item item3 = new Item();
        item3.setGroup("分组B")
                .setName("王五")
                .setSubject("英语")
                .setScore(90);
        itemList.add(item3);
        data.put("itemList", itemList);

        // 对应勾选框的数据
        data.put("check", "true");
        return data;
    }

Item 类如下：

最终的目录结构如下：

4.生成 word 文档

@Test
void testDemo() throws Exception {
    Map<String, Object> data = WordUtils.initData();
    String templateName = "demo.ftl";
    WordUtils.generateWord(data, templateName, "/tmp/demo.docx");
    
}

最终，则会在 /tmp目录下生成一个名为 demo 的 word 文档。