序列内建函数

chunk

Note:

该内建函数从 FreeMarker 2.3.3 版本开始存在。

该内建函数将序列分隔为多个序列，长度为第一个参数给定的值 (比如 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 - -

该内建函数通常在输出的序列中使用表格/柱状的格式。当被用于HTML表格时，第二个参数通常是"\xA0" (也就是不换行的空格代码，也就是我们所知的"nbsp")，所以空TD的边界就不会不丢失。

第一个参数必须是一个数字，而且至少是1。如果这个数字不是整数，那么它会被静默地去掉小数部分(也就是说3.1和3.9都会被规整为3)。第二个参数可以是任意类型的值。

first

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

join

使用给定的分隔符来连接序列中的项为一个独立的字符串，例如：

<#assign colors = ["red", "green", "blue"]>
${colors?join(", ")}

将会输出：

red, green, blue

序列中不是字符串的项会被转换为字符串，使用 ${...} 相同的转换规则 (当然这里不会应用自动转义)。

?join(...) 最多可以有3个参数：

分隔符，是必须的:插入到每一项中间的字符串
空值，默认是 "" (空字符串)：如果序列为空，使用该值。
列表结尾，默认是 "" (空字符串): 如果列表序列不为空，该值在最后一个值后面输出。

所以 (这里 [] 意味着空序列)：

${colors?join(", ", "-")}
${[]?join(", ", "-")}

${colors?join(", ", "-", ".")}
${[]?join(", ", "-", ".")}

将会输出：

red, green, blue
-

red, green, blue.
-

来自Java的序列可能会包含 null 值。那些值会被该内建函数忽略，就像它们从列表中被移除了。

last

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

reverse

序列的反序形式。

seq_contains

Note:

该内建函数从 FreeMarker 2.3.1 版本开始可用。而在 2.3 版本中不存在。

Note:

seq_ 前缀在该内建函数名字中是需要的，用来和 contains 内建函数区分开。contains 用来在字符串中查找子串 (因为变量可以同时当作字符串和序列)。

辨别序列中是否包含指定值。它包含一个参数，就是来查找的值。比如：

<#assign x = ["red", 16, "blue", "cyan"]>
"blue": ${x?seq_contains("blue")?string("yes", "no")}
"yellow": ${x?seq_contains("yellow")?string("yes", "no")}
16: ${x?seq_contains(16)?string("yes", "no")}
"16": ${x?seq_contains("16")?string("yes", "no")}

将会输出：

"blue": yes
"yellow": no
16: yes
"16": no

为了查找值，该内建函数使用了 FreeMarker 的比较规则 (就像使用 == 操作符)，除了比较两个不同类型的值，或 FreeMarker 不支持的类型来比较，其他都不会引起错误，只是会评估两个值不相等。因此，你可以使用它来查找标量值 (也就是字符串，数字，布尔值，或日期/时间类型)。对于其他类型结果通常都是 false。

对于容错性，该内建函数还对 collection 起作用。

seq_index_of

Note:

该内建函数从 FreeMarker 2.3.1 版本开始可用。而在 2.3 版本中不存在。

Note:

seq_ 前缀在该内建函数名字中是需要的，用来和 index_of 内建函数区分开。index_of 用来在字符串中查找子串 (因为变量可以同时当作字符串和序列)。

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

<#assign colors = ["red", "green", "blue"]>
${colors?seq_index_of("blue")}
${colors?seq_index_of("red")}
${colors?seq_index_of("purple")}

将会输出：

2
0
-1

为了查找值，该内建函数使用了FreeMarker 的比较规则 (就像使用了 == 操作符)，除了比较两个不同类型的值，或 FreeMarker 不支持的类型来比较，其他都不会引起错误，只是会评估两个值不相等。因此，你可以使用它来查找标量值 (也就是字符串，数字，布尔值，或日期/时间类型)。对于其他类型结果通常是 -1。

搜索开始的索引值可以由第二个可选参数来确定。如果在同一个序列中相同的项可以多次出现时，这是很有用的。第二个参数的数值没有什么限制：如果它是负数，那么就和它是零的效果一样，而如果它是比序列长度还大的数，那么就和它是序列长度值的效果一样。小数值会被切成整数。比如：

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
No 2nd param: ${names?seq_index_of("Joe")}
-2: ${names?seq_index_of("Joe", -2)}
-1: ${names?seq_index_of("Joe", -1)}
 0: ${names?seq_index_of("Joe", 0)}
 1: ${names?seq_index_of("Joe", 1)}
 2: ${names?seq_index_of("Joe", 2)}
 3: ${names?seq_index_of("Joe", 3)}
 4: ${names?seq_index_of("Joe", 4)}

将会输出：

No 2nd param: 0
-2: 0
-1: 0
 0: 0
 1: 2
 2: 2
 3: -1
 4: -1

seq_last_index_of

Note:

该内建函数从 FreeMarker 2.3.1 版本开始可用。而在2.3版本中不存在。

Note:

seq_ 前缀在该内建函数名字中是需要的，用来和 last_index_of 内建函数区分开。last_index_of 用来在字符串中查找子串 (因为变量可以同时当作字符串和序列)。

返回序列中最后一次出现值的索引位置，如果序列不包含指定的值时返回 -1。也就是说，和 seq_index_of 相同，只是在序列中从最后一项开始向前搜索。它也支持可选的第二个参数来确定从哪里开始搜索的索引位置。比如：

<#assign names = ["Joe", "Fred", "Joe", "Susan"]>
No 2nd param: ${names?seq_last_index_of("Joe")}
-2: ${names?seq_last_index_of("Joe", -2)}
-1: ${names?seq_last_index_of("Joe", -1)}
 0: ${names?seq_last_index_of("Joe", 0)}
 1: ${names?seq_last_index_of("Joe", 1)}
 2: ${names?seq_last_index_of("Joe", 2)}
 3: ${names?seq_last_index_of("Joe", 3)}
 4: ${names?seq_last_index_of("Joe", 4)}

将会输出：

No 2nd param: 2
-2: -1
-1: -1
 0: 0
 1: 0
 2: 2
 3: 2
 4: 2

size

序列中子变量的数量(作为数字值)。假设序列中至少有一个子变量，那么序列 s 中最大的索引是 s?size - 1 (因为第一个子变量的序列是0)。

sort

以升序方式返回序列。(要使用降序排列时，使用它之后使用 reverse 内建函数。) 这仅在子变量都是字符串时有效，或者子变量都是数字，或者子变量都是日期值 (日期，时间，或日期+时间)，或者所有子变量都是布尔值时(从2.3.17版本开始)。如果子变量是字符串，它使用本地化(语言)的具体单词排序(通常是大小写不敏感的)。比如：

<#assign ls = ["whale", "Barbara", "zeppelin", "aardvark", "beetroot"]?sort>
<#list ls as i>${i} </#list>

将会输出(至少是US区域设置)：

aardvark Barbara beetroot whale zeppelin

sort_by

返回由给定的哈希表子变量来升序排序的哈希表序列。 (要降序排列使用该内建函数后还要使用 reverse 内建函数。) 这个规则和 sort 内建函数是一样的，除了序列中的子变量必须是哈希表类型，而且你不得不给哈希变量的命名，那会用来决定排序顺序。比如：

<#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>

将会输出(至少是US区域设置)：

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>

将会输出(至少是US区域设置)：

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

Previous Next