FreeMarker学习（内建函数参考）

Posted 2021-11-28 lpob

一、字符串内建函数

boolean：

　　字符串转为布尔值。字符串必须是 true 或 false (大小写敏感！)。

cap_first：

　　字符串中的首单词的首字母大写。

capitalize：

　　字符串中所有单词的首字母大写。

chop_linebreak：

　　在末尾没有换行符的字符串， 那么可以换行，否则不改变字符串。

contains：

　　如果函数中的参数指定的子串出现在源字符串中， 那么返回true。

date, time, datetime：

　　字符串转换成日期值，时间或日期-时间值。需要一个由 date_format， time_format 和 datetime_format 设置指定的格式。 如果字符串不是适当的格式，那么当访问该内建函数时， 就会发生错误中止模板的处理。

ends_with：

　　是否以某个字符串结尾，返回布尔值。

ensure_ends_with：

　　如果字符串没有以第一个参数指定的子串结尾， 那么就会将它加到字符串后面，否则返回原字符串。比如， "foo"?ensure_ends_with("/") 和 "foo/"?ensure_ends_with("/") 返回 "foo/"。

ensure_starts_with：

　　如果字符串没有以第一个参数指定的子串开头， 那么就会将它加到字符串开头，否则返回原字符串。比如， "foo"?ensure_starts_with("/") 和 "/foo"?ensure_starts_with("/") 返回 "/foo"。

groups：

　　这个函数只作用于内建函数 matches 的结果。

html：字符串按照HTML标记输出。

index_of：

　　返回第一次字符串中出现子串时的索引位置。

j_string：

　　根据Java语言字符串转义规则来转义字符串， 所以它很安全的将值插入到字符串类型中。要注意它 不会 在被插入的值的两侧添加引号； 你需要在字符串值 内部 来使用。　

<#assign beanName = ‘The "foo" bean.‘>
String BEAN_NAME = "${beanName?j_string}";   --  String BEAN_NAME = "The \"foo\" bean."; 

js_string：

　　根据javascript语言字符串转义规则来转义字符串， 所以它很安全的将值插入到字符串类型中。

json_string：

　　根据JSON语言的字符串规则来转义字符串， 所以在字符串中插入值是安全的。 要注意它 不会 在被插入的值两侧添加引号； 你需要在字符串值 内部 来使用。

keep_after：

　　移除字符串中的一部分内容，该部分是给定子串第一次出现之前的部分，保留移除后的部分。

keep_after_last：

　　和 keep_after 相同， 但是它会保留参数最后一次出现后的部分，而不是第一次。

keep_before：

　　移除字符串的一部分，该部分是从给定子串开始的部分。

keep_before_last：

　　和 keep_before 相同， 但是保留参数最后一次出现之前的部分，而不是第一次出现之前。

last_index_of：

　　返回最后一次(最右边)字符串中出现子串时的索引位置。

left_pad：

　　如果它仅仅用1个参数，那么它将在字符串的开始插入空白， 直到整个串的长度达到参数指定的值。 如果字符串的长度达到指定数值或者比指定的长度还长， 那么就什么都不做了。如果用两个参数，则用第二个参数当作空白符进行填充。

length：

　　字符串中字符的数量。

lower_case：

　　字符串的小写形式。比如 "GrEeN MoUsE"?lower_case 将会是 "green mouse"。

matches：

　　字符串是否精确匹配模式，会返回匹配子串的列表。 返回值是多类型值；布尔值：如果字符串整体匹配了模式，就是 true， 否则就是 false。序列：字符串匹配的子串的列表。很有可能是长度为0的序列

number：

　　字符串转化为数字格式。识别科学记数法(比如 "1.23E6"，"1.5e-8") 。

replace：

　　在源字符串中，用另外一个字符串来替换原字符串中出现它的部分

right_pad：

　　它和 left_pad 相同， 但是它从末尾开始插入字符而不是从开头。如果用两个参数，则用第二个参数当作空白符进行填充。

remove_beginning：

　　从字符串的开头移除参数中的子串，如果它不以参数中的子串开头， 那么就或者返回原字符串。

remove_ending：

　　从字符串的结尾移除参数中的子串，如果它不以参数中的子串结尾， 那么就或者返回原字符串。

rtf：

　　字符串作为富文本(RTF 文本)，也就是说，下列字符串：(\ 替换为 \\)、({替换为\{)、(}替换为\})

split：

　　切割字符串。

starts_with：

　　判断字符串是否以指定字符串开头。

string：

　　当被用作是字符串值时什么也不做，仅仅返回和其内容一致的字符串。例外的是， 如果值是一个多类型的值(比如同时有字符串和序列两种)， 那么结果就只是一个简单的字符串，而不是多类型的值。 这可以被用来防止人为多输入

substring：

　　截取字符串，已废弃，使用字符串切分进行截取，如：str[from..<toExclusive]。

trim：

　　去掉字符串首尾的空格。

uncap_first：

　　和 cap_first 相反。 字符串中所有单词的首字母小写。

upper_case：

　　字符串全部转大写。

url：

　　在URL之后的字符串进行转义，支持添加字符集参数。这意味着， 所有非US-ASCII的字符和保留的URL字符将会被 %XX 形式转义。

url_path：

　　它和 url 内建函数 相同，只是它不转义斜杠 (/)字符。

word_list：

　　以空白字符切割字符串，返回值是一个序列，顺序为出现在字符串中的顺序。 单词是不间断的字符序列，包含了任意字符，但是没有空白。

xhtml：

　　字符串作为XHTML格式文本。

xml：

　　字符串作为XML格式文本。

通用标志：

　　多字符串内建函数接受可选的字符串参数， 它们被称为"标志"。在这个字符串中，每个字母影响内建函数一个特定方面的行为。 比如，字母 i 说明内建函数不应该区别相同字母的小写和大写变化。 标志字符串中的字母顺序是不重要的。

• i：大小写敏感： 不区别相同字母的小写和大写变化。
• f：只是第一个。也就是说， 替换/查找/等...，只是第一个出现的地方。
• r：查找的子串是 正则表达式。 FreeMarker 使用的正则表达式变量可以在 http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html 中找到(请注意，一些模式规则特性的出现基于所使用的Java版本)。
• m：正则表达式的多行模式。在多行正则表达式 ^ 和 $ 仅仅匹配之后或之前， 各自匹配行终止符或字符串结尾。默认情况下，这些表达式仅仅匹配完整字符串的开头和结尾。 请注意，^ 和 $ 不匹配换行符字符本身。
• s：开启正则表达式的dot-all模式 (和Perl的单行模式相同)。在dot-all模式下，表达式 . 匹配任意字符串，包含行终止符。 默认情况下，该表达式不匹配行终止符。
• c： 允许正则表达式中的空白和注释。

　　　　下表是支持使用这些通用标志的内建函数：

内建函数	i (忽略大小写)	r (正则表达式)	m (多行模式)	s (dot-all模式)	c (空白和注释)	f (仅第一个)
replace	是	是	仅 r	仅 r	仅 r	是
split	是	是	仅 r	仅 r	仅 r	否
matches	是	忽略	是	是	是	否
keep_after	是	是	是	是	是	忽略
keep_after_last	是	是	是	是	是	忽略
keep_before	是	是	是	是	是	忽略
keep_before_last	是	是	是	是	是	忽略
ensure_starts_with	是	忽略	是	是	是	忽略

二、数字内建函数

abs：

　　给出数字的绝对值。比如 x?abs ，如果 x 是 -5，会得到5。

c：

　　将将 "计算机语言" 的数字转换成字符串，也对布尔值起作用。

is_infinite：

　　辨别数字是否是无限浮点数，结果是 true 或 false。

is_nan：

　　辨别数字是否是浮点数NaN，结果是 true 或 false。

lower_abc：

　　将 1， 2， 3，等...，转换为字符串 "a"， "b"， "c"，等... 当到达 "z"时，那么会继续转换成如 "aa"， "ab"等。
round：

　　返回最近的整数，四舍五入。

floor：

　　返回小于该值的最大整数。

ceiling：

　　返回大于该值的最小整数。

string：

　　当用作是数字类型时，将一个数字转换成字符串。它使用程序员通过 number_format 和 locale 设置的默认格式。也可以明确地用这个内建函数再指定一个数字格式。

　　有四种预定义的数字格式：computer， currency，number 和 percent。这些格式的明确含义是本地化(国家)指定的， 受Java平台安装环境所控制，而不是FreeMarker，除了 computer，用作和 c 内建函数是相同的格式。可以这样来使用预定义的格式：

<#assign x=42>
${x}
${x?string}  <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}
${x?string.computer}

　　如果你本地是US English，将会输出：

42
42
42
$42.00
4,200%
42

　　前三个表达式的输出是相同的，因为前两个表达式是默认格式， 这里是"数字"。可以使用一个设置来改变默认设置：

<#setting number_format="currency">
<#assign x=42>
${x}
${x?string}  <#-- the same as ${x} -->
${x?string.number}
${x?string.currency}
${x?string.percent}

　　输出

$42.00
$42.00
42
$42.00
4,200%

　　因为默认的数字格式被设置成了"货币"。

　　除了这三种预定义格式，还可以使用 Java 数字格式语法 中的任意数字格式：

<#assign x = 1.234>
${x?string["0"]}
${x?string["0.#"]}
${x?string["0.##"]}
${x?string["0.###"]}
${x?string["0.####"]}

${1?string["000.00"]}
${12.1?string["000.00"]}
${123.456?string["000.00"]}

${1.2?string["0"]}
${1.8?string["0"]}
${1.5?string["0"]} <-- 1.5, rounded towards even neighbor
${2.5?string["0"]} <-- 2.5, rounded towards even neighbor

${12345?string["0.##E0"]}

　　输出

1
1.2
1.23
1.234
1.234

001.00
012.10
123.46

1
2
2 <-- 1.5, rounded towards even neighbor
2 <-- 2.5, rounded towards even neighbor

1.23E4

　　请注意，在 FreeMarker 中，foo.bar 和 foo["bar"] 是相同的，也可以将 x?string.currency 写为 x?string["currency"]，当然实际中不这么用。 但是在上述示例中，我们不得不使用方括号语法，因为在语法上， 使用的字符(数字，点，#)不允许在点操作符之后。

　　由于历史原因，也可以编写如下代码 x?string("0.#")，它和 x?string["0.#"] 完全相同。

　　在金融和统计学实践中，四舍五入都是根据所谓的一半原则， 这就意味着对最近的"邻居"进行四舍五入，除非离两个邻居距离相等， 这种情况下，它四舍五入到偶数的邻居。如果你注意看1.5和2.5的四舍五入的话， 这在上面的示例中是可以看到的，两个都被四舍五入到2，因为2是偶数，但1和3是奇数。

　　正如之前展示的预定义格式，数字的默认格式可以在模板中设置：

<#setting number_format="0.##">
${1.234}   -- 1.23

　　请注意，数字格式是本地化敏感的，本地化设置在格式化中起作用：

<#setting number_format=",##0.00">
<#setting locale="en_US">
US people write:     ${12345678}
<#setting locale="hu">
German people write: ${12345678}

　　输出

US people write:     12,345,678.00
German people write: 12.345.678,00

upper_abc：

　　和 lower_abc 相同， 但是它转换成大写字母，比如 "A"， "B"， "C"，… ， "AA"， "AB"， 等...

 

三、日期内建函数

date, time, datetime：

　　当用于日期/时间/日期-时间值时，这些内建函数用来指定日期变量中的哪些部分被使用：

• date：仅日期部分，没有一天当中的时间部分。
• time：仅一天当中的时间部分，没有日期部分。
• datetime：日期和时间都在

　　可以用来将日期-时间值转换成日期或时间，如果 ? 左边是字符串，那么这些内建函数 将字符串转换成日期/时间/日期时间。

string

　　当用于日期/时间/日期-时间值时，这个内建函数以指定的格式转换日期类型到字符串类型。

四、布尔值内建函数 

c：

　　当用于布尔值时，该内建函数将布尔值转换为字符串，针对 "计算机语言" 而不是用户。

string：

　　当用于布尔值时，该内建函数的所有用法已经废弃。将布尔值转换为字符串。可以两种方式来使用：

• foo?string("yes", "no")： 从 FreeMarker 2.3.23 版本开始废弃：使用 ?then("yes", "no") 来替代。
• foo?string： 从 FreeMarker 2.3.20 版本开始废弃：使用 ?c 来代替，或者设置 boolean_format 设置项，比如像 "yes,no"，之后转换会自动发生。

then：

　　根据true或者false返回不同的表现形式，如“yes”或“no”，“0”或“1”。

 五、序列的内建函数

chunk：

　　该内建函数将序列分隔为多个序列，长度为第一个参数给定的值 (比如 mySeq?chunk(3))。结果是包含这些序列的一个序列。 最后一个序列可能比给定的长度要小，除非第二个参数也给定了 (比如 比如 mySeq?chunk(3, ‘-‘))， 这就是用来填充最后一个序列，以达到给定的长度。例如：

<#assign seq = [‘a‘, ‘b‘, ‘c‘, ‘d‘, ‘e‘, ‘f‘, ‘g‘, ‘h‘, ‘i‘, ‘j‘]>

<#list seq?chunk(4) as row>
  <#list row as cell>${cell} </#list>
</#list>

<#list seq?chunk(4, ‘-‘) as row>
  <#list row as cell>${cell} </#list>
</#list>

　　输出

  a b c d 
  e f g h 
  i j 

  a b c d 
  e f g h 
  i j - - 

first：

　　序列的第一个子变量。如果序列为空，那么模板处理将会中止。

join：

　　使用给定的分隔符来连接序列中的项为一个独立的字符串。最多可以有3个参数：分隔符、空值、列表结尾。

last：

　　序列的最后一个子变量。如果序列为空，那么模板处理将会中止。

reverse：

　　序列的反序形式。

seq_contains：

　　序列中是否包含某个值，返回布尔值。

seq_index_of：

　　返回序列中第一次出现该值时的索引位置， 如果序列不包含指定的值时返回 -1。要查找的值作为第一个参数。

seq_last_index_of：

　　返回序列中最后一次出现值的索引位置， 如果序列不包含指定的值时返回 -1。也就是说，和 seq_index_of 相同， 只是在序列中从最后一项开始向前搜索。

size：

　　序列的长度。

sort：

　　以升序方式返回序列。

sort_by：

　　返回由给定的哈希表子变量来升序排序的哈希表序列。

<#assign ls = [
  {"name":"whale", "weight":2000},
  {"name":"Barbara", "weight":53},
  {"name":"zeppelin", "weight":-200},
  {"name":"aardvark", "weight":30},
  {"name":"beetroot", "weight":0.3}
]>
Order by name:
<#list ls?sort_by("name") as i>
- ${i.name}: ${i.weight}
</#list>

Order by weight:
<#list ls?sort_by("weight") as i>
- ${i.name}: ${i.weight}
</#list>

　　输出

Order by name:
- aardvark: 30
- Barbara: 53
- beetroot: 0.3
- whale: 2000
- zeppelin: -200

Order by weight:
- zeppelin: -200
- beetroot: 0.3
- aardvark: 30
- Barbara: 53
- whale: 2000

　　如果你用来排序的子变量的层次很深 (也就是说，它是子变量的子变量的子变量，以此类推)， 那么你可以使用序列来作为参数，它指定了子变量的名字， 来向下引导所需的子变量。比如：

<#assign members = [
    {"name": {"first": "Joe", "last": "Smith"}, "age": 40},
    {"name": {"first": "Fred", "last": "Crooger"}, "age": 35},
    {"name": {"first": "Amanda", "last": "Fox"}, "age": 25}]>
Sorted by name.last: 
<#list members?sort_by([‘name‘, ‘last‘]) as m>
- ${m.name.last}, ${m.name.first}: ${m.age} years old
</#list>

　　输出

Sorted by name.last: 
- Crooger, Fred: 35 years old
- Fox, Amanda: 25 years old
- Smith, Joe: 40 years old