FreeMarker 手册
用于 FreeMarker 2.3.16
Translated By Nan Lei
南磊 译
Copyright：
The Chinese translation of the FreeMarker Manual by Nan Lei is licensed under a Creative
Commons Attribution 3.0 Unported License (see http://creativecommons.org/licenses/by/3.0/ ).
This licence only applies to the Chinese translation, not to the original (English) FreeMarker
Manual.
版权说明：
FreeMarker 中文版手册由南磊翻译，本文档基于 Creative Commons Attribution 3.0
Unported 授权许可（参见 http://creativecommons.org/licenses/by/3.0/deed.zh ）
本许可仅应用于中文版，不对原版英文手册。
（译者联系方式为：nanlei1987@gmail.com ）
目录
目录................................................................................................................................. 2
前言................................................................................................................................. 5
什么是 FreeMarker？ ................................................................................................. 5
我们应该阅读什么内容？ .......................................................................................... 5
文档规约................................................................................................................... 6
联系我们................................................................................................................... 6
几点说明................................................................................................................... 6
第一部分 模板开发指南 ................................................................................................... 7
第一章 模板开发入门 ............................................................................................... 7
1.1 简介 ............................................................................................................ 7
1.2 模板 + 数据模型 = 输出 ............................................................................. 7
1.3 数据模型一览 .............................................................................................. 9
1.4 模板一览 ................................................................................................... 11
第二章 数值和类型 ................................................................................................. 17
2.1 基本内容 ................................................................................................... 17
2.2 类型 .......................................................................................................... 20
第三章 模板 ........................................................................................................... 24
3.1 总体结构 ................................................................................................... 24
3.2 指令 .......................................................................................................... 25
3.3 表达式 ....................................................................................................... 26
3.4 插值 .......................................................................................................... 41
第四章 其它 ........................................................................................................... 44
4.1 自定义指令 ................................................................................................ 44
4.2 在模板中定义变量 ..................................................................................... 50
4.3 命名空间 ................................................................................................... 52
4.4 空白处理 ................................................................................................... 56
4.5 替换（方括号）语法 ................................................................................... 59
第二部分 程序开发指南 ................................................................................................. 61
第一章 程序开发入门 ............................................................................................. 61
1.1 创建配置实例 ............................................................................................ 61
1.2 创建数据模型 ............................................................................................ 61
1.3 获得模板 ................................................................................................... 62
1.4 合并模板和数据模型 .................................................................................. 63
1.5 将代码放在一起 .......................................................................................... 63
第二章 数据模型 .................................................................................................... 65
2.1 基本内容 ................................................................................................... 65
2.2 标量 .......................................................................................................... 66
2.3 容器 .......................................................................................................... 67
2.4 方法 .......................................................................................................... 68
2.5 指令 .......................................................................................................... 69
2.6 节点变量 ................................................................................................... 76
2.7 对象包装 ................................................................................................... 76
第三章 配置 ........................................................................................................... 80
3.1 基本内容 ................................................................................................... 80
3.2 共享变量 ................................................................................................... 81
3.3 配置信息 ................................................................................................... 81
3.4 模板加载 ................................................................................................... 83
3.5 错误控制 ................................................................................................... 86
第四章 其它 ........................................................................................................... 90
4.1 变量 .......................................................................................................... 90
4.2 字符集问题 ................................................................................................ 91
4.3 多线程 ....................................................................................................... 92
4.4 Bean 的包装 ................................................................................................ 93
4.5 日志 .......................................................................................................... 99
4.6 在 servlets 中使用 FreeMarker ..................................................................... 99
4.7 为 FreeMarker 配置安全策略......................................................................106
4.8 遗留的 XML 包装实现 ................................................................................107
4.9 和 Ant 一起使用 FreeMarker.......................................................................110
4.10 Jython 包装器 ..........................................................................................111
第三部分 XML 处理指南................................................................................................113
前言.......................................................................................................................113
第一章 揭示 XML 文档 ...........................................................................................113
1.1 节点树 ......................................................................................................113
1.2 将 XML 放到数据模型中 ............................................................................115
第二章 必要的 XML 处理 ........................................................................................116
2.1 通过例子来学习 ........................................................................................116
2.2 形式化描述 ...............................................................................................124
第三章 声明的 XML 处理 ........................................................................................127
3.1 基础内容 ..................................................................................................127
3.2 详细内容 ..................................................................................................130
第四部分 参考文档 .......................................................................................................133
第一章 内建函数参考文档 .....................................................................................133
1.1 处理字符串的内建函数 .............................................................................133
1.2 处理数字的内建函数 .................................................................................146
1.3 处理日期的内建函数 .................................................................................150
1.4 处理布尔值的内建函数 .............................................................................153
1.5 处理序列的内建函数 .................................................................................153
1.6 处理哈希表的内建函数 .............................................................................159
1.7 处理节点（XML）的内建函数....................................................................159
1.8 很少使用的和专家级的内建函数 ...............................................................161
第二章 指令参考文档 ............................................................................................164
2.1 if，else，elseif 指令 ...................................................................................164
2.2 switch，case，default，break 指令..............................................................166
2.3 list，break 指令 .........................................................................................167
2.4 include 指令 ...............................................................................................168
2.5 import 指令 ...............................................................................................171
2.6 noparse 指令 ..............................................................................................172
2.7 compress 指令 ............................................................................................173
2.8 escape，noescape 指令...............................................................................174
2.9 assign 指令 ................................................................................................176
2.10 global 指令 ..............................................................................................178
2.11 local 指令 ................................................................................................179
2.12 setting 指令 .............................................................................................179
2.13 用户自定义指令（<@...>） ......................................................................181
2.14 macro，nested，return 指令 ....................................................................183
2.15 function，return 指令...............................................................................188
2.16 flush 指令 ................................................................................................189
2.17 stop 指令.................................................................................................190
2.18 ftl 指令 ....................................................................................................190
2.19 t，lt，rt 指令 ..........................................................................................192
2.20 nt 指令 ....................................................................................................193
2.21 attempt，recover 指令 .............................................................................193
2.22 visit，recurse，fallback 指令 .....................................................................195
第三章 特殊变量参考文档 .....................................................................................199
第四章 FTL 中的保留名称.......................................................................................200
第五章 废弃的 FTL 结构 .........................................................................................200
5.1 废弃的指令列表 ........................................................................................200
5.2 废弃的内建函数列表 .................................................................................200
5.3 老式的 macro 和 call 指令 ..........................................................................201
5.4 转换指令 ..................................................................................................202
5.5 老式 FTL 语法 ............................................................................................204
5.6 #{…}式的数字插值 ......................................................................................205
前言
什么是 FreeMarker？
FreeMarker 是一款模板引擎：一种基于模板的、用来生成输出文本(任何来自于 HTML
格式的文用本来自动生成源代码)的通用工具。它是为 Java 程序员提供的一个开发包或者说
是类库。它不是面向最终用户，而是为程序员提供的嵌入他们开发产品的一款应用程序。
FreeMarker 实际上是被设计用来生成 HTML 网页，尤其是通过基于实现了 MVC(Model
View Controller，模型-视图-控制器)模式的 Servlet 应用程序。使用 MVC 模式的动态网页的构
思是使得你可以将前端设计者(编写 HTML)从程序员中分离出来。所有人各司其职，发挥其
擅长的一面。网页设计师可以改写页面的显示效果而不受程序员编译代码的影响，因为应用
程序的逻辑(Java 程序)和页面设计(FreeMarker 模板)已经分开了。页面模板代码不会受到复
杂的程序代码的影响。这种分离的思想即便对一个程序员和页面设计师是同一个人来说的项
目都是非常有用的，因为分离使得代码保持简洁而且便于维护。
尽管 FreeMarker 也有编程的能力，但它也不是像 PHP 那样的一种全面的编程语言。反
而，Java 程序准备数据来显示(比如 SQL 查询)，FreeMarker 仅仅使用模板生成文本页面来呈
现已经准备好的数据。
FreeMarker 不是 Web 应用框架。它是 Web 应用框架中的一个适用的组件，但是
FreeMarker 引擎本身并不知道 HTTP 协议或 Servlet。它仅仅来生成文本。即便这样，它也非
常适用于非 Web 应用环境。要注意的是，我们使用 FreeMarker 作为视图层组件为如 Struts
这样的 Model 2 框架提供现成的解决方案。
FreeMarker 是免费的，基于 BSD 风格的许可。它是 OSI 认证的开源软件。OSI 认证是开
源倡议的认证标识。
我们应该阅读什么内容？
如果你是一名…
前端设计师，那么你应该阅读模板开发指南，然后如果需要的话可以参阅参考手册来获
取更多技术细节。
程序员，那么你应该先阅读模板开发指南，然后是程序开发指南，最后如果需要的话可
以参阅参考手册来获取更多技术细节。
