浅谈FreeMarker基础使用

最新推荐文章于 2026-04-02 20:57:51 发布

原创最新推荐文章于 2026-04-02 20:57:51 发布 · 423 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#java #编程语言 #freemarker

学习小结专栏收录该内容

2 篇文章

订阅专栏

本文深入解析FreeMarker模板引擎的功能和用法，包括数据模型、指令（如if、list）、内建函数及变量处理，展示如何高效生成动态文本。

简介

FreeMarker 是一款模板引擎：即一种基于模板和要改变的数据，并用来生成输出文本(HTML网页，电子邮件，配置文件，源代码等)的通用工具。它不是面向最终用户的，而是一个Java类库，是一款程序员可以嵌入他们所开发产品的组件。在模板中，你可以专注于如何展现数据，而在模板之外可以专注于要展示什么数据。
在这里插入图片描述
例如一个html页面要展示用户信息和商品信息，这些数据都来自数据库。我门每次都重新定义页面的话会很费时费力，这时我们就可以使用模板将数据做动态改变，减少重读代码的编写，如下面的Jhon 和 product可以用 ${user}和$ {latestProduct.name}来代替

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome John !</h1>
  <p>Our latest product:
  <a href="products/product.html">product</a>!
</body>
</html>

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>Welcome ${user}!</h1>
  <p>Our latest product:
  <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>

数据模板

为模板准备的数据整体被称作为数据模型。模板作者要关心的是，数据模型是树形结构(就像硬盘上的文件夹和文件)，在视觉效果上，数据模型可以是：

(root)
  |
  +- user = "Big Joe"
  |
  +- latestProduct
      |
      +- url = "products/greenmouse.html"
      |
      +- name = "green mouse"

上面只是一个形象化显示；数据模型不是文本格式，它来自于Java对象。对于Java程序员来说，root就像一个有 getUser() 和 getLatestProduct() 方法的Java对象，也可以有 “user” 和 “latestProducts” 键值的Java Map对象。相似地，latestProduct 就像是有 getUrl() 和 getName() 方法的Java对象。

模板和数据模型是FreeMarker来生成输出(比如第一个展示的HTML)所必须的：

模板 + 数据模型 = 输出

if指令

使用 if 指令可以有条件地跳过模板的一些片段。比如，假设在最初的示例中，想向你的老板Big Joe特别地问好，可其他人不同：

<html>
<head>
  <title>Welcome!</title>
</head>
<body>
  <h1>
    Welcome ${user}<#if user == "Big Joe">, our beloved leader</#if>!
  </h1>
  <p>Our latest product:
  <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>

此时，告诉 FreeMarker，当和 “Big Joe” 相同时 “, our beloved leader” 才是if条件中那唯一的 user 变量的值。通常来讲，如果 condition 是false(布尔值)，那么介于 <#if condition> 和 </#if> 标签中的内容会被略过

list指令

当需要列表显示内容时，list指令是必须的。比如：如果合并该模板到前面描述序列的数据模型中:

<p>We have these animals:
<table border=1>
  <#list animals as animal>
    <tr><td>${animal.name}<td>${animal.price} Euros
  </#list>
</table>

那么输出结果将会是这样的：

<p>We have these animals:
<table border=1>
    <tr><td>mouse<td>50 Euros
    <tr><td>elephant<td>5000 Euros
    <tr><td>python<td>4999 Euros
</table>

list 指令的一般格式为： <#list sequence as loopVariable>repeatThis</#list>。 repeatThis 部分将会在给定的 sequence 遍历时在每一项中重复，从第一项开始，一个接着一个。在所有的重复中， loopVariable 将持有当前遍历项的值。这个变量仅存在于 <#list …> 和 </#list> 标签内。
sequence 可以是任意表达式，比如我们可以列表显示示例数据模型中的水果，就像这样：

<ul>
<#list misc.fruits as fruit>
  <li>${fruit}
</#list>
</ul>

上面示例中的一个问题是如果我们有0个水果，它仍然会输出一个空的 ul标签，而不是什么都没有。要避免这样的情况，可以这么来使用 list：

<#list misc.fruits>
  <ul>
    <#items as fruit>
      <li>${fruit}
    </#items>
  </ul>
</#list>

此时， list 指令将列表视为一个整体，在 items 指令中的部分才会为每个水果重复。如果我们有0个水果，那么在 list 中的所有东西都被略过了，因此就不会有 ul 标签了。

另一个列表相关的常见任务是：使用一些分隔符来列出水果，比如逗号：

<p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, </#list>

<p>Fruits: orange, banana

被 sep 覆盖的部分只有当还有下一项时才会被执行。因此最后一个水果后面不会有逗号。
list 指令，也像 if 指令那样，可以有 else 部分，如果列表中有0个元素时就会被执行：

<p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, <#else>None</#list>

所有的这些指令(list, items, sep, else)可以联合起来使用：

<#list misc.fruits>
  <p>Fruits:
  <ul>
    <#items as fruit>
      <li>${fruit}<#sep> and</#sep>
    </#items>
  </ul>
<#else>
  <p>We have no fruits.
</#list>

include指令

使用 include 指令，我们可以在模板中插入其他文件的内容。
假设要在一些页面中显示版权声明的信息。那么可以创建一个文件来单独包含这些版权声明，之后在需要它的地方插入即可。比方说，我们可以将版权信息单独存放在页面文件 copyright_footer.html 中：

<hr>
<i>
Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,
<br>
All Rights Reserved.
</i>

当需要用到这个文件时，可以使用 include 指令来插入：

<html>
<head>
  <title>Test page</title>
</head>
<body>
  <h1>Test page</h1>
  <p>Blah blah...
  <#include "/copyright_footer.html">
</body>
</html>

此时，输出的内容为：

<html>
<head>
  <title>Test page</title>
</head>
<body>
  <h1>Test page</h1>
  <p>Blah blah...
<hr>
<i>
Copyright (c) 2000 <a href="http://www.acmee.com">Acmee Inc</a>,
<br>
All Rights Reserved.
</i>
</body>
</html>

联合使用指令

在页面上也可以多次使用指令，而且指令间也可以很容易地相互嵌套。比如，在 list 指令中嵌套 if 指令：

<#list animals as animal>
      <div<#if animal.protected> class="protected"</#if>>
        ${animal.name} for ${animal.price} Euros
      </div>
</#list>

使用内建函数

内建函数很像子变量(也可以说像方法)，它们并不是数据模型中的东西，是 FreeMarker 在数值上添加的。为了清晰子变量是哪部分，使用 ?(问号)代替 .(点)来访问它们。常用内建函数的示例：

user?html 给出 user 的HTML转义版本， 比如 & 会由 &amp; 来代替。

user?upper_case 给出 user 值的大写版本 (比如 "JOHN DOE" 来替代 "John Doe")

animal.name?cap_first 给出 animal.name 的首字母大写版本(比如 "Mouse" 来替代 "mouse")

user?length 给出 user 值中 字符的数量(对于 "John Doe" 来说就是8)

animals?size 给出 animals 序列中 项目 的个数(我们示例数据模型中是3个)

如果在 <#list animals as animal> 和对应的 </#list> 标签中：

animal?index 给出了在 animals 中基于0开始的 animal的索引值

animal?counter 也像 index， 但是给出的是基于1的索引值

animal?item_parity 基于当前计数的奇偶性，给出字符串 "odd" 或 "even"。在给不同行着色时非常有用，比如在 <td class="${animal?item_parity}Row">中。

一些内建函数需要参数来指定行为，比如：

animal.protected?string("Y", "N") 基于 animal.protected 的布尔值来返回字符串 "Y" 或 "N"。

animal?item_cycle('lightRow','darkRow') 是之前介绍的 item_parity 更为常用的变体形式。

fruits?join(", ") 通过连接所有项，将列表转换为字符串， 在每个项之间插入参数分隔符(比如 "orange,banana")

user?starts_with("J") 根据 user 的首字母是否是 "J" 返回布尔值true或false。

内建函数应用可以链式操作，比如user?upper_case?html 会先转换用户名到大写形式，之后再进行HTML转义。(这就像可以链式使用 .(点)一样)

处理不存在的变量

数据模型中经常会有可选的变量(也就是说有时并不存在)。除了一些典型的人为原因导致失误外，FreeMarker 绝不能容忍引用不存在的变量，除非明确地告诉它当变量不存在时如何处理。这里来介绍两种典型的处理方法。

这部分对程序员而言: 一个不存在的变量和一个是 null 值的变量， 对于FreeMarker来说是一样的，所以这里所指的"丢失"包含这两种情况。

不论在哪里引用变量，都可以指定一个默认值来避免变量丢失这种情况，通过在变量名后面跟着一个 !(叹号，译者注)和默认值。就像下面的这个例子，当 user 不存在于数据模型时, 模板将会将 user 的值表示为字符串 “visitor”。(当 user 存在时，模板就会表现出 ${user} 的值)：

<h1>Welcome ${user!"visitor"}!</h1>

也可以在变量名后面通过放置 ?? 来询问一个变量是否存在。将它和 if 指令合并，那么如果 user 变量不存在的话将会忽略整个问号后的代码段：

<#if user??><h1>Welcome ${user}!</h1></#if>