FreeMarker 中文文档

FreeMarker 介绍

FreeMarker 是一款 模板引擎： 即一种基于模板和要改变的数据， 并用来生成输出文本(HTML网页，电子邮件，配置文件，源代码等)的通用工具。 它不是面向最终用户的，而是一个Java类库，是一款程序员可以嵌入他们所开发产品的组件。
模板编写为FreeMarker Template Language (FTL)。它是简单的，专用的语言， 不是 像PHP那样成熟的编程语言。 那就意味着要准备数据在真实编程语言中来显示，比如数据库查询和业务运算， 之后模板显示已经准备好的数据。在模板中，你可以专注于如何展现数据， 而在模板之外可以专注于要展示什么数据。

FreeMarker 注释

  2. <!-- HTML 注释, 页面渲染 -->
  4. <#-- FreeMarker 注释, 页面不渲染 -->

FreeMarker 数据类型

布尔类型

布尔类型不能够直接在页面进行输出,需要进行转为字符串,转为字符串有三种方式

  1. ?c
  2. ?string
  3. ?string(‘’,’’)

  4. ?then(‘Y’,’N’)

    1. ${flag?c} <br>
    2. ${flag?string} <br>
    3. ${flag?string("确定","取消")}
    4. ${flag?then("Y","N")}

    日期类型

    Freemarker 中日期类型不能够直接输出,需要转为日期类型或者字符串类型

    1. ${createDate?date} <br>
    2. ${createDate?time} <br>
    3. ${createDate?datetime} <br>
    4. ${createDate?string("yyyy-MM-dd HH:mm:ss")} <br>

    数值类型

    FreeMarker 中数值类型可以直接输出, 也可以转为字符串, 浮点数等…

  5. 转为字符串

    1. 普通字符串 ?c
    2. 货币类型字符串 ?string.currency
    3. 百分比型字符串 ?string.percent

  6. 保留浮点数值, 指定小数位 (# 个数表示小数位数)

    1. ?string[0.##] 保留两位小数

      字符串类型

      FreeMarker 中字符串类型可以直接输出, 也可以格式化操作

  7. 截取字符串(左闭右开) ?substring(str,end)

  8. 首字母小写输出 ?uncap_first
  9. 首字母大写输出 ?cap_first
  10. 字母转小写输出 ?lower_case
  11. 字母转大写输出 ?upper_case
  12. 获取字符串长度 ?length
  13. 是否以指定字符开头(boolean类型) ?starts_with(“abc”)?string
  14. 是否以指定字符结尾(boolean类型) ?ends_with(“abc”)?string
  15. 获取指定字符索引 ?index_of(“ok”)
  16. 去除字符串前后空格 ?trim

  17. 替换指定字符 ?replace(“abc”,”bca”)

    字符串空值情况处理

    FreeMarker 的变量必须赋值, 否则就会抛出异常. 而对于 FreeMarker 来说, null 值和不存在的变量是完全一样的, 因为 FreeMarker 无法理解 null 值.
    FreeMarker 提供两种运算符来避免空值

  18. ! 指定缺失变量的默认值

    1. ${value!} 如果value值为空, 则默认值是空字符串
    2. ${value!”默认值”} 如果value 值为空, 则默认字符串是”默认值”

  19. ?? 判断是否存在

    1. 如果变量存在, 返回 true , 否则返回 false
    2. ${(value??)?string}

      sequence 类型

      序列类型 (数组, List, Set) , 通过 list 指令输出序列
      1. <#list 序列名 as 元素名 >
      2. ${元素名}
      3. </#list>

  20. ${元素名?size} 获取序列长度

  21. ${元素名?index} 获取序列元素的下标
  22. ${元素名?first} 获取序列中第一个元素
  23. ${元素名?last} 获取序列中最后一个元素
  24. ${元素名?reverse} 序列倒序输出
  25. ${元素名?sort} 序列升序输出
  26. ${元素名?sort?reverse} 降序输出
  27. ${元素名?sort_by(“字段名”)} 指定字段名排序

注意: 如果是 JavaBean 集合, 对应字段需要提供get方法

hash 类型

  1. Map<String,String> map = new HashMap<>();
  2. map.put("sh","上海");
  3. map.put("bj","北京");
  4. map.put("nj","南京");
  5. map.put("tj","天津");
  6. map.put("cq","重庆");
  1. <#list map?keys as key>
  2.   ${key} --- ${map[key]} <br>
  3. </#list>
  5. <#list map?values as value>
  6.  ${value} <br>
  7. </#list>

FreeMarker 常见指令

assign 定义变量指令

assign 指令可以在页面中定义自己需要的变量, 然后在页面进行取值等操作.

  1. <#assign name1=value1 name2=value2 ... nameN=valueN>
  2. 或
  3. <#assign same as above... in namespacehash>
  4. 或
  5. <#assign name>
  6.   capture this
  7. </#assign>
  8. 或
  9. <#assign name in namespacehash>
  10.   capture this
  11. </#assign>
  • name：变量的名字。 它不是表达式。而它可以写作是字符串，如果变量名包含保留字符这是很有用的， 比如 <#assign “foo-bar” = 1>。 请注意这个字符串没有展开插值(如”${foo}”)； 如果需要赋值一个动态创建的名字，那么不得不使用 这个技巧。
  • =：赋值操作符。 它也可以是一个简写的赋值操作符(从 FreeMarker 2.3.23 版本开始)： ++，—， +=，-=， *=，/= 或 %=。比如 <#assign x++> 和 <#assign x = x + 1> 是一样的，并且 <#assign x += 2> 和 <#assign x = x + 2> 是相同的。 请注意， ++ 通常意味着算术加法 (对于非数字将会失败)，不像 + 或 += 可以进行字符连接等重载操作。
  • value： 存储的值。是表达式。
  • namespacehash：(通过 import) 为命名空间创建的哈希表。是表达式。 ```html <#assign str=”hello”> ${str}

<#assign num=1 names=[“张三”,”李四”,”王五”,”赵六”]> ${num} —- ${names?join(“,”)}

  1. <a name="KrVB1"></a>
  2. ## if elseif else 逻辑判断指令
  3. ```html
  4. <#--
  5.    if, else, elseif 逻辑判断指令
  6.      格式:
  7.          <#if condition>
  8.              ...
  9.             <#elseif condition2>
  10.        ...
  11.       <#elseif codition3>
  12.         ...
  13.       <#else>
  14.        ...
  15.       </#if>
  16. -->
  17. <#assign scroe = 80>
  19. <#if score lt 60 >
  20.       你是一个小渣渣
  21. <#elseif score == 60>
  22.       分不在高, 及格就行
  23. <#elseif score ge 60 && score lt 80>
  24.   哎哟不错哟
  25. <#else>
  26.   你很棒棒哟
  27. </#if>
  29. <hr/>
  31. <#assign list="">
  33. <#if lsit??>
  34.   数据存在
  35. <#else>
  36.   数据不存在
  37. </#if>

注意: FreeMarker 中 if else 语句中 else 是写在 if 内部

list 循环指令

  1. <#--
  2.     list指令
  3.      格式1:
  4.     <#1ist sequence as item>
  6.         </#1ist>
  8.     格式2:
  9.     <#1ist sequence as item>
  11.     <#else>
  12.             当没有选项时，执行e1se指令
  13.     </#1ist>
  14.     注:
  15.     1. else 部分是可选的
  16.     2. sequence:想要迭代的项，可以是序列或集合的表达式3. item:循环变量的名称
  17.     4．当没有迭代项时，才使用else 指令，可以输出一些特殊的内容而不只是空在那里
  19. <#assign users =["张三","李四", "王五"]>
  21. <#--遍历序列-->
  22. <#1ist users as user>
  23.     ${user}
  24. </#1ist>
  26. <!-- 判断数据是否为空在进行遍历 -->
  27. <#if user2??>
  28.   <#1ist user2 as user>
  29.     ${user}
  30.   </#1ist>
  31. </#if>
  33. <!-- 当序列没有数据项时, 使用默认信息 -->
  34. <#assign user3=[]>
  35. <#list user3 as user>
  36.   ${user}
  37. <#else>
  38.   用户数据不存在...
  39. </#list>

macro 自定义指令(宏)

可以使用 macro 指令来自定义一些自定义指令

  1. <#--
  2.   macro自定义指令(宏0
  3.   1．基本使用
  4.     格式:
  5.     <#macro 指令名>
  6.           指令内容
  7.         </#macro>
  8.     使用:
  9.       <@指令名></@指令名>
  11.   2．有参数的自定义指令
  12.   格式:
  13.          <#macro 指令名 参数名1 参数名2>
  14.               指令内容
  15.       </#macro>
  16.     使用:
  17.       <@指令名 参数名1=参数值1 参数名2=参数值2></@指令名>
  18.   注:
  19.     1．指令可以被多次使用。
  20.     2．自定义指令中可以包含字符串，也可包含内置指令
  21. -->
  23. <#-―定义基本的自定义指令-->
  24. <#macro address>
  25.     1999-2015 The FreeMarker Project. A17 rights reserved.
  26. </#macro>
  28. <@address></@address>
  31. <#-- 自定义有参数的指令 -->
  32. <#macro queryUserByName uname>
  33.     通过用户名查询用户对象 - ${uname})
  34. </ #macro>
  36. <@queryUserByName uname="admin"></@queryUserByName><br>
  38. <#macro queryUserByName02 uname upwd phone>
  39.     多条件查询用户对象- ${uname} - ${upwd} - ${phone})
  40. </ #macro>
  42. <@queryUserByWame02 uname="zhangsan" upwd="123456" phone="1587656789"></@queryUserByName02>
  45. <#-- 自定义指令中包含内置指令-->
  46. <#macro cfb>
  47.     <#list 1..9 as i>
  48.         <#list 1..i as j>
  49.             ${j} * ${[i} = ${j*i}&nbsp;
  50.         </#list>
  51.         <br>
  52.     </#list>
  53. </#macro>
  55. <@cfb></@cfb>

nested 占位指令

nested指令执行自定义指令开始和结束标签中间的模板片段。嵌套的片段可以包含模板中任意合法的内容。

  1. <#--
  2. nested 占位指令
  3.     nested 相当于占位符，—般结合macro指令一起使用。
  4.     可以将自定义指令中的内容通过nested指令占位，当使用自定义指令时，会将占位内容显示。
  5. -->
  6. <#macro test>
  7.     这是一段文本!
  8.     <#nested>
  9.     <#nested>
  10. </ #macro>
  12. <@test>
  13.     <h4>这是文本后面的内容!</h4>
  14. </@test>

import 导入指令

import指令可以引入一个库。也就是说，它创建一个新的命名空间，然后在那个命名空间中执行给定路径的模板。可以使用引入的空间中的指令。

  1. commons.ftl
  2. <#macro cfb>
  3.     <#list 1..9 as i>
  4.         <#list 1..i as j>
  5.             ${j}*${i}=${j*i}&nbsp;
  6.         </#1ist>
  7.             <br>
  8.     </#1ist>
  9. </ #macro>
  11. 在其他ftl页面中通过import导入commons.ftl的命名空间，使用该命名空间中的指令
  13. test.ftl
  14. <#--导入命名空间-->
  15. <#import "commons.ftl" as common>
  17. <#--使用命名空间中的指令-->
  18. <@common.cfb></@common.cfb>

include 包含指令

可以使用inc1ude指令在你的模板中插入另外一个FreeMarker模板文件。被包含模板的输出格式是在inc1ude标签出现的位置插入的。被包含的文件和包含它的模板共享变量，就像是被复制粘贴进去的一样。

  1. <#--包含指令(引入其他页面文件) include-->
  2. <#--htm1文件-->
  3. <#include "test.html">
  5. <#--freemarker文件-->
  6. <#include "test.ft7">
  8. <#--text文件-->
  9. <#include "test.txt">

include 可以包含 html, ftl, txt 文件

switch

  1. <#switch value>
  2.   <#case refValue1>
  3.     ...
  4.     <#break>
  5.   <#case refValue2>
  6.     ...
  7.     <#break>
  8.   ...
  9.   <#case refValueN>
  10.     ...
  11.     <#break>
  12.   <#default>
  13.     ...
  14. </#switch>
  • value， refValue1，等： 表达式将会计算成相同类型的标量。
  • break 和 default 是可选的。

    FreeMarker 页面静态化

    通过上述介绍可知Freemarker是一种基于模板的、用来生成输出文本的通用工具,所以我们必须要定制符合自己业务的模板，然后生成自己的html页面。Freemarker是通过freemarker.template.Configuration这个对象对模板进行加载的（它也处理创建和缓存预解析模板的工作)，然后我们通过getTemplate方法获得你想要的模板，有一点要记住freemarker.template.Configuration在你整个应用必须保证唯一实例。

FreeMarker 运算符