制作ftl文件通过FreeMarke生成PDF文件（含图片处理）

FreeMarker模板文件(FTL)全面指南：创建与使用实践

一、FTL文件概述

FTL(FreeMarker Template Language)是FreeMarker模板引擎使用的文件格式，后缀名为.ftl。它是一种基于模板生成文本输出的技术，核心思想是将数据模型与展示模板分离，实现MVC架构中的视图层渲染

1.1 FTL文件特点

分离表现层与业务逻辑‌：模板只负责数据展示，不包含业务逻辑代码，使美工和程序员各司其职
‌提高开发效率‌：无需等待界面设计完成即可开始开发，模板修改后无需重新编译
‌支持多种输出格式‌：可生成HTML、XML、Java代码、配置文件等多种文本格式
轻量级模板引擎‌：不依赖Servlet环境，可轻松嵌入各种应用程序

1.2 核心工作原理

FTL文件本质是包含占位符(如${variable})和指令(如<#if>、<#list>)的文本文件。FreeMarker引擎将数据模型(如Java的Map或POJO)与模板结合，替换占位符并执行指令，最终输出目标文件。

二、FTL文件创建方法

2.1 从Word模板创建FTL文件

‌编辑Word模板‌：

在Word中设计模板，将动态内容用变量名标记图片处理：将Base64编码的图片替换为{变量名}标记图片处理：将Base64编码的图片替换为变量名标记图片处理：将Base64编码的图片替换为{变量名}

‌另存为XML格式‌：

点击"文件" > "另存为"

保存类型选择"Word XML文档(*.xml)"

‌修改文件后缀名‌：

将.xml文件重命名为.ftl(如template.ftl)

‌格式化处理‌：

使用文本编辑器(如Notepad++)或IDE格式化XML内容

添加必要的FreeMarker指令(如<#list>)

2.2 直接创建FTL文件

‌在Eclipse/IDEA中创建‌：

新建File，命名为filename.ftl

或新建HTML文件后重命名为.ftl

‌设置语法高亮‌：

在IDE中配置.ftl文件使用HTML编辑模式

安装FreeMarker插件获得更好的编辑体验

三、FreeMarker配置与使用

3.1 项目配置

‌Maven依赖‌：

xml 复制代码

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.31</version>
</dependency>

‌Spring Boot配置‌(application.yml)：

yaml 复制代码

spring:
  freemarker:
    template-loader-path: classpath:/templates
    suffix: .ftl
    cache: false
    charset: UTF-8
    content-type: text/html;charset=UTF-8

3.2 核心代码示例

java 复制代码

import freemarker.template.Configuration;
import freemarker.template.Template;
import java.io.FileWriter;
import java.util.HashMap;
import java.util.Map;

public class FreeMarkerDemo {
    public static void main(String[] args) throws Exception {
        // 1. 创建配置对象
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_31);
        
        // 2. 设置模板路径
        cfg.setDirectoryForTemplateLoading(new File("src/main/resources/templates"));
        
        // 3. 设置编码
        cfg.setDefaultEncoding("UTF-8");
        
        // 4. 加载模板
        Template template = cfg.getTemplate("demo.ftl");
        
        // 5. 准备数据模型
        Map<String, Object> data = new HashMap<>();
        data.put("name", "张三");
        data.put("items", Arrays.asList("项目A", "项目B", "项目C"));
        
        // 6. 生成输出
        try (FileWriter writer = new FileWriter("output.html")) {
            template.process(data, writer);
        }
    }
}

四、FTL模板语法详解

4.1 基本语法元素

语法类型示例说明

变量替换 ${name} 输出数据模型中的变量值

注释 <#-- 注释内容 --> 模板中不执行的注释

插值 ${expression} 表达式求值输出

FTL指令 <#if ...>...</#if> 流程控制指令

4.2 常用指令示例

‌条件判断‌：

html 复制代码

<#if score >= 60>
    及格
<#else>
    不及格
</#if>

‌循环遍历‌：

xml 复制代码

<#list users as user>
    ${user.name} - ${user.email}
</#list>

‌包含指令‌：

xml 复制代码

<#include "header.ftl">

‌宏定义‌：

xml 复制代码

<#macro table>
    <table>
        <#list rows as row>
            <tr>
                <td>${row}</td>
            </tr>
        </#list>
    </table>
</#macro>

五、最佳实践与常见问题

5.1 最佳实践建议

‌模板管理‌：将通用组件拆分为独立模板文件

‌错误处理‌：在process方法中添加异常捕获

‌性能优化‌：生产环境中启用模板缓存

‌编码规范‌：统一使用UTF-8编码避免乱码

5.2 常见问题解决

‌模板文件找不到‌：

确认.ftl文件存放在resources/templates目录

检查template-loader-path配置是否正确

‌中文乱码问题‌：

统一使用UTF-8编码

在Configuration中设置setDefaultEncoding("utf-8")

‌空值处理‌：

xml 复制代码

${empty!defaultValue} 或 全局配置classic_compatible=true

六、应用场景

‌动态页面生成‌：分离网页设计与业务逻辑开发

‌文档生成‌：通过模板生成报表、合同等格式文件

‌代码生成‌：自动生成Entity、DAO等重复性代码

‌邮件模板‌：动态生成个性化邮件内容