Freemarker 教程(一)-模板开发手册

本文是Freemarker系列的第一篇，面向模板开发人员，主要介绍 FreeMarker 所使用的 FTL(FreeMarker Template Language) 语法，了解 Freemarker 的基本概念，介绍基本的 FTL 术语及内置函数，内置指令，方便作为开发手册速查（文中演示所用版本为 2.3.30，实际使用中请根据自己项目版本自查官网）。

本文不会罗列官网API，只在必要时演示其语法，代码工程中有课代表整理的 freemarker api 思维导图，配合此文食用可使功力大增！请到课代表的 github自取。

1.FreeMarker 是什么

Freemarker是一款纯 Java编写的模板引擎软件，可以用来生成各种文本，包括但不限于：HTML，E-Mail以及各种源代码等等。

它的主要任务就是：把模板和数据组装在一起，生成文档，这个过程又叫渲染(Render)。流程如图：

由于大部分模板开发人员都是用它来生成HTML页面，所以本文将基于 SpringBoot(2.4.1)+Freemarker(2.3.30)+SpringWeb演示 HTML 页面的渲染

2.最简单的模板

假设我想要一个简单页面用来欢迎当前用户，模板代码：

<html>
<head>
  <title>index</title>
</head>
<body>
    <p>你好，${userName}</p>
</body>
</html>

${userName}是 FTL 的插值语法，他会把userName的值替换到生成的 HTML 中，从而根据当前登录者，显示不同的用户名，这个值由后端代码放到Model中，对应的 Controlelr 代码：

@Controller
public class HelloWorld {
    @GetMapping("hello")
    public String hello(Model model) {
        model.addAttribute("userName","Java 课代表");
        // 返回模板名称
        return "index";
    }
}

访问页面：

数据由后端代码通过数据模型（Model）传递，模板只关心数据如何展示（View），二者的关联关系由 Controller 来控制，这就是 MVC。

3.数据模型(data-model)

Controller中添加到 model 中的数据是如何组织的呢？这就需要了解一下FTL的数据模型(data-model)。

FTL 的数据模型在结构上是一个树形：

(root)
  |
  +- animals
  |   |
  |   +- mouse
  |   |   |
  |   |   +- size = "small"
  |   |   |
  |   |   +- price = 50
  |   |
  |   +- elephant
  |   |   |
  |   |   +- size = "large"
  |   |   |
  |   |   +- price = 5000
  |   |
  |   +- python
  |       |
  |       +- size = "medium"
  |       |
  |       +- price = 4999
  |
  +- message = "It is a test"
  |
  +- misc
      |
      +- foo = "Something"

其中的root 可以理解为 Controller 中的 model ，通过 model.addAttribute("userName","Java 课代表");就可以往数据模型中添加数据。

数据模型中可以像目录一样展开的变量，如：root, animals, mouse, elephant, python, misc称之为哈希(hash)。哈希的 key 就是变量名，value 就是变量存储的值，通过.分隔的路径可以访问变量值，比如访问 mouse 的 price :animals.mouse.price.

像animals.mouse.price这样存储单个值的变量叫做标量(scalar)，标量有四种具体类型：string，boolean，date-like，number；

还有一种变量叫做序列(sequence),可以类比为 Java 中的数组，序列中的每个项没有名字，可以通过遍历，或者下标的方式访问（后面会演示序列的访问），它的数据结构看起来是这样的：

(root)
  |
  +- animals
  |   |
  |   +- (1st)
  |   |   |
  |   |   +- name = "mouse"
  |   |   |
  |   |   +- size = "small"
  |   |   |
  |   |   +- price = 50
  |   |
  |   +- (2nd)
  |   |   |
  |   |   +- name = "elephant"
  |   |   |
  |   |   +- size = "large"
  |   |   |
  |   |   +- price = 5000
  |   |
  |   +- (3rd)
  |       |
  |       +- name = "python"
  |       |
  |       +- size = "medium"
  |       |
  |       +- price = 4999
  |
  +- misc
      |
      +- fruits
          |
          +- (1st) = "orange"
          |
          +- (2nd) = "banana"

FTL 里常用的数据类型就这三类：哈希（hashe）,标量（scalar），序列（sequence）。

有了数据，还要有语法来组织这些数据，下面介绍 FTL 中的常用语法。

4.FTL 语法

FreeMarker 只认如下三种语法：

插值：${...} ，Freemarker 会将里面的变量替换为实际值
FTL 标签(tags)：结构上类似HTML的标签，都是用<>包裹起来，普通标签以<#开头，用户自定义标签以<@开头，如<#if true>true thing<#/if>，<@myDirect></@myDirect>

你会看到两种叫法，1：标签（tags），2：指令（directive）。举个例子：<#if></#if>叫标签；标签里面的if是指令，可以类比于html中的标签（如：<table></table>）和元素（如：table）。不过，把标签和指令认为是同义词也没有问题。

注释(Comments)：FTL 中的注释是这样的：<#-- 被注释掉的内容 -->，对于注释，FTL会自动跳过，所以不会显示在生成的文本中（这点有别于 HTML 的注释）

注意：除以上三种语法之外的所有内容，皆被 FreeMarker 视为普通文本，普通文本会被原样输出

插值就是单纯的替换变量的值，注释更没啥好说的，下面主要介绍几个最常用的 FTL 标签（指令）并结合代码演示其用法。

if 指令

if 可以根据条件跳过模板中的某块代码，以前文为例，当 userName 值为 "Java课代表" 或zhengxl5566时，用特殊样式展示，相关模板代码如下：

<p>你好，
    <#if userName == "Java 课代表">
        <strong>${userName}</strong>
    <#elseif userName == "zhengxl5566">
        <h1>${userName}</h1>
    <#else>
        ${userName}
    </#if>
</p>

list 指令

list用来遍历序列，其语法为：

<#list sequence as loopVariable>
    repeatThis
</#list>

比如后台往 model 里放入一个 allUsers 的集合

model.addAttribute("allUsers",userService.getAllUser());

可以直接使用下标访问集合中的某个元素：${allUsers[0].name}

也可以在模板中直接遍历展示：

<ol>
<#list allUsers as user>
    <li>
        姓名：${user.name}，年龄：${user.age}
    </li>
</#list>
</ol>

实际渲染出来的 HTML：

<ol>
  <li>
    姓名：zxl，年龄：18
  </li>
  <li>
    姓名：ls，年龄：19
  </li>
  <li>
    姓名：zs，年龄：16
  </li>
</ol>

注意：假设 allUsers 是空的，渲染出来的页面会是<ol></ol>，如果需要规避这个情况，可以使用 items 标签

<#list allUsers>
    <ol>
        <#items as user>
            <li>
                姓名：${user.name}，年龄：${user.age}
            </li>
        </#items>
    </ol>
</#list>

此时，假设 allUsers是空的，list 标签中的 html 内容就不会被渲染出来。

include 指令

include 指令可以把一个模板的内容插入到另一个模板中（官方建议使用 import 代替，参见下文的最佳实践）。
假设我们每个页面都需要一个 footer，可以写一个公共的footer.ftlh模板，其余需要footer的页面只需要引用footer.ftlh模板即可：

<#include "footer.ftlh">

import 指令

import 可以将模板中定义的变量引入当前模板，并在当前模板中使用。它和 include 的主要区别就是 import 可以将变量封装到新的命名空间中（后文会介绍 import 和 include 的对比）。

例如：模板 /libs/commons.ftl 里面写了很多公共方法，想在其他模板里引用，只需要在其他模板的开头写上：

<#import "/libs/commons.ftl" as com>

后续想使用/libs/commons.ftl 中的 copyright 方法，可以直接使用：

<@com.copyright date="1999-2002"/>

assign 指令

assign 可以用来创建新的变量并为其赋值，语法如下：

<#assign name1=value1 name2=value2 ... nameN=valueN>
or
<#assign name1=value1 name2=value2 ... nameN=valueN in namespacehash>
or
<#assign name>
  capture this
</#assign>
or
<#assign name in namespacehash>
  capture this
</#assign>

举例：

<#--创建字符串-->
<#assign myStr = "Java 课代表">
<#--使用插值语法显示字符串-->
myStr:${myStr}

macro 指令

macro 用来从模板上创建用户自定义指令（Java后端可以通过实现TemplateDirectiveModel接口自定义指令，将在下一篇：《Freemarker 教程(二)-后端开发指南》中介绍）

macro 创建的也是变量，该变量可以做为用户自定义指令使用，比如下面的模板定义了 greet指令：

<#macro greet>
  <h1>hello 课代表</h1>
</#macro>

使用 greet 指令

<@greet></@greet>
或者
<@greet/>

指令还可以附带参数：

<#macro greet person>
  <h1>hello ${person}</h1>
</#macro>

使用时传入 person 变量：

<@greet person="Java课代表"/> and <@greet person="zhengxl5566"/>

5.内置函数（Built-ins）

所谓内置函数，就是 FreeMarker 针对不同数据类型为我们提供的一些内置方法，有了这些方法，可以让数据在模板中的展示更加方便。使用内置函数时，只需要在变量后面使用?加相应函数名即可。篇幅有限，这里不打算罗列所有内置函数，只挑几个简单例子展示其语法。

例子一：字符串的内置函数

<#--创建字符串-->
<#assign myStr = "Java 课代表">
<#--首字母小写-->
${myStr?uncap_first}
<#--保留指定字符后面的字符串-->
${myStr?keep_after("Java")}
<#--替换指定字符-->
${myStr?replace("Java","Freemarker")}

例子二：时间类型内置函数

<#--获取当前时间(如果是后端将时间传入data-model，只需要传Date类型即可)-->
<#assign currentDateTime = .now>
<#--展示日期部分-->
${currentDateTime?date}<br>
<#--展示时间部分-->
${currentDateTime?time}<br>
<#--展示日期和时间部分-->
${currentDateTime?datetime}<br>
<#--按指定格式展示时间日期-->
${currentDateTime?string("yyyy-MM-dd HH:mm a")}<br>

例子三：序列的内置函数

<#--序列类型内置函数样例-->
<#assign mySequence = ["Java 课代表","张三","李四","王五"]>
<#--将所有元素以指定分隔符分割，输出字符串-->
${mySequence?join(",")}<br>
<#--取序列中的第一个元素-->
${mySequence?first}<br>
<#--将序列排序后使用逗号分割输出为字符串-->
${mySequence?sort?join(",")}<br>

通过以上三个例子的简单演示，相信你已经能掌握内置函数的使用技巧了，就是在变量后面用 ?加变量数据类型所支持的函数。FTL 的内置函数极其丰富，官网按数据类型详细罗列了各自支持的内置函数及其用法，可自行查看官网的内置函数参考。

为了方便大家快速查阅相关内置函数(built-ins)和指令(directives)，课代表从官网翻译，并使用 xmind 做了个思维导图，每个函数(指令)都可以点进去查看功能描述和样例，可以极大提高模板开发效率：

原始 xmind 文件放在课代表的github上，读者可以按需自取。

课代表划重点！这个思维导图是全文精华，一定要下载下来看看！

6.命名空间(Namespaces)

所谓命名空间，就是在同一个模板里，所有使用 assign，macro，function 指令所创建的变量集合，它的主要作用就是唯一标识一个变量。

有两种方式可以创建命名空间：

1、同一个模板中的变量在同一个命名空间中。

以如下的index.ftlh为例，这里面创建的变量都在一个命名空间下，同名变量的值会相符覆盖

<#assign myName = "Java 课代表">
<#assign myName = "课代表">
<#--实际输出的是“课代表”-->
${myName}

2、不同模板中的变量可以通过 import 指令来区分不同的命名空间变量

模板A中想使用模板B中的变量，可以使用 import 指令，给引入的模板定义一个新的命名空间，通过 as 后面指定的 key 访问该新命名空间。

比如模板 lib/example.ftlh中定义了copyright：

<#macro copyright date>
  <p>Copyright (C) ${date} Someone. All rights reserved.</p>
</#macro>

<#assign mail = "user@example.com">

在另一个模板index.ftlh中使用copyright：

<#import "lib/example.ftlh" as e>
<@e.copyright date="1999-2002"/>
${e.mail}

命名空间的生命周期（The life-cycle of namespaces）

命名空间由 import 指令中的 path 确定（绝对路径），如果相同的 path 引入了多次，只有第一次调用 import 的时候才会触发相应命名空间的创建。后面对于相同模板路径的 import，指代的都是同一个命名空间，举例：

<#import "/lib/example.ftl" as e>
<#import "/lib/example.ftl" as e2>
<#import "/lib/example.ftl" as e3>
${e.mail}, ${e2.mail}, ${e3.mail}
<#assign mail="other@example.com" in e>
${e.mail}, ${e2.mail}, ${e3.mail}

将/lib/example.ftl import 后赋给 e,e2,e3三个命名空间，修改e中的 mail，对e2,e3同样生效

输出：

user@example.com, user@example.com, user@example.com
other@example.com, other@example.com, other@example.com

import 和 include 的区别

<#import "lib/example.ftlh" as e> 会创建一个全新的命名空间，并把lib/example.ftlh中定义的变量封装到新命名空间中，提供访问，如：<@e.copyright date="1999-2002"/>。

<#include "lib/example.ftlh"> 只是单纯把example.ftlh的内容插入到当前模板，并不会对命名空间产生影响

Freemarker官方建议：
所有使用 include 的地方都应该被 import 替代

使用 import 好处如下：

import 引入的模板只会被执行一次，重复引用多次并不会重复执行模板。而对于 include 而言，每次 include 都会执行一次模板内容；
import 可以创建该模板的命名空间，引用变量时可以清晰表达出变量来源，减少命名冲突概率；
如果定义了很多通用方法，可以将auto-import配置为懒加载，用到哪个加载哪个。而auto-include无法实现懒加载，必须全量加载；
import 指令不会有任何输出，而 include 可能会根据模板内容输出相应字符。

7.最佳实践

1.空值处理

变量空值的处理

对于不存在的变量和值为 null 的变量，freemarker 统一认为是不存在的值，对其调用将会报错。为了避免这种情况，可以设置默认值，示例：<h1>Welcome ${user!"visitor"}!</h1>，当user不存在时，将显示visitor字符串。

另一种方式是在变量后面使用 ??表达式，如：user??如果user存在，则返回 true，否则返回 false，示例：<#if user??><h1>Welcome ${user}!</h1></#if>，当user不存在时，就不展示欢迎标语了。

list中的空值处理

遍历序列的时候，假设序列中有空值，freemarker并不会直接报错或显示空值，而是像更上一级作用域去搜索同名变量值，这种行为可能会导致错误的输出，举例：

<#assign x = 20>
<#list xs as x>
  ${x!'Missing'}
</#list>

本意是当遇到序列 xs 中的空元素是显示“missing” 字符串，但由于 freemarker 向上查找的特性，这里的空值将会显示为 20。要关闭这个特性，可以在服务端配置：configuration.setFallbackOnNullLoopVariable(false);

2.使用 import 代替 include

前文在介绍到 include 的时候提到过，官方建议应该将所有用到 include 的地方都用 import 实现

我们平时用到 include 指令，主要就是用来把一段内容插入到当前模板，那如何用 import 实现 include 的功能呢？

很简单，把需要插入的内容封装成自定义指令就好了。

比如我们从common.ftlh 里定义一个自定义指令 myFooter

<#macro myFooter>
    <hr>
    <p>这里是 footer</p>
</#macro>

在需要使用的地方，引入 common.ftlh 并调用 myFooter 指令

<#import "lib/common.ftlh" as common>
<#--将include使用import代替-->
<#--<#include "footer.ftlh">-->
<@common.myFooter/>

3.隔行变色

数据展示的时候经常遇到使用表格展示数据的情况，为了增加辨识度，一般会让奇数行和偶数行颜色不同以区分，这就是隔行变色

下面以遍历序列为例：

<#assign mySequence = ["Java 课代表","张三","李四","王五"]>
<#list mySequence as name>
    <span style="color:  ${name?item_cycle("red","blue")}">   ${name}<br/> </span>
</#list>

这里的 item_cycle 是循环变量的内置函数，至于他的详细用法，再次推荐你去看一下课代表整理的思维导图。

8.总结

本文介绍了 Freemarker 的基本概念和基础语法，意在让刚接触的萌新能对 Freemarker 有个全局性认识，了解Freemarker的数据模型、内置函数、指令。只要能区分这几个概念，实际开发中现用现查即可，不要一开始就迷失在海量的API中。

总体来说，Freemarker 是一个比较简单，容易上手的模板引擎，只要掌握了本文所提及的基本概念，直接上手开发是完全没问题的。

在本文写作过程中，课代表意识到纯文字表达的局限性，又不能全文罗列和翻译API，于是整理了一个思维导图，将Freemarker 的各类指令，内置函数及其官网示例全都翻译整理了进去。在平时开发过程中极大提升了开发效率，需要的同学请到课代表的 github自取。

👇关注 Java课代表，获取最新 Java 干货👇