freeMarker（三）——模板开发指南之数值、类型

学习笔记，选自freeMarker中文文档，译自 Email: ddekany at users.sourceforge.net

模板开发指南——数值、类型

1.基本内容

1.1 什么是数值？

　　正如你知道的，来自于每天所使用的数字，比如16，0.5等这些用语就是 数值 的示例，也就是数字。在计算机语言中， 这些用语有着更广泛的含义，比如数值并不一定是数字类型值，比如面这个数据模型：

(root)
 |
 +- user = "Big Joe"
 |
 +- today = Jul 6, 2007
 |
 +- todayHoliday = false
 |
 +- lotteryNumbers
 |   |
 |   +- (1st) = 20
 |   |
 |   +- (2st) = 14
 |   |
 |   +- (3rd) = 42
 |   |
 |   +- (4th) = 8
 |   |
 |   +- (5th) = 15
 |
 +- cargo
     |
     +- name = "coal"
     |
     +- weight = 40

　　变量 user 的 value 是"Big Joe"(字符串), today 的 value 是 Jul 6, 2007 (日期)，todayHoliday 的 value 是false(布尔值，比如yes/no等值)。 lotteryNumbers 的 value 是包含20,14, 42, 8, 15的序列。当然在这种意义上， lotteryNumbers 是多值类型。它 包含 多个值(比如，其中的第二项的 value 是14)，但是 lotteryNumbers 本身还是单值。它就像一个装有其它很多东西的盒子 (或称之为容器，译者注)，但盒子作为整体还是视作单独的。最后还有一个数值 cargo，它的 value 是一个哈希表 (也是类似盒子一样的东西)。所以说，数值就是存储在变量中的(比如，在 user 或 cargo 或 cargo.name 中)的那个东西。但是， 不需要存储于变量之中的数值也可以称之为数值，比如下面的数字100：

<#if cargo.weight < 100>Light cargo</#if>

　　当模板被执行时，计算出的临时结果也称为数值，比如这里的20和120(它会打印120)：

${cargo.weight / 2 + 100}

　　这里针对最后一种表示进行解释：有两个数，40(货物的重量)和2， 相除的结果是20，这是一个新计算出来的数值。然后，把它和100相加， 那么120就计算出来了，接着就打印出来。 (${...})，之后模板继续向下执行， 直到所有结果都计算出来。

　　现在你应该能体会到数值这个词的含义了。

1.2 什么是类型？

　　数值中非常重要的一个概念就是类型。比方说，变量 user 的类型是字符串，变量 lotteryNumbers 的类型是序列。数值的类型这个概念非常的重要，因为它决定了这些数值可以在哪里使用的最大限度。 比如说，使用 ${user / 2} 就是错误的，但是使用 ${cargo.weight / 2} 就能计算出结果，为20， 因为算术中的除法仅对数字类型的值有效，而不能用于字符串。 仅当 cargo 是一个哈希表变量时，表达式 cargo.name 才可以使用点。也可以用 <#list ...> 指令来遍历序列。而 <#if ...> 指令的条件只能是布尔值等。

注意:

　　这里说一点点的术语：称 "布尔" 或 "布尔值" 或 "布尔类型" 都是相同的含义。

　　数值同时也可以含有多种类型，尽管很少这么使用。看一下下面这个数据模型 mouse 它本身就又是字符串，又是哈希表：

(root)
 |
 +- mouse = "Yerri"
     |
     +- age = 12
     |
     +- color = "brown"

　　如果用上面的数据模型合并到下面的模板中：

 ${mouse}       <#-- uses mouse as a string -->
 ${mouse.age}   <#-- uses mouse as a hash -->
 ${mouse.color} <#-- uses mouse as a hash -->

　　将会输出：

 Yerri
 12
 brown

1.3 数据模型是哈希表

　　注意观察每个数据模型的例子你也许能发现：被"(root)"所标识的内容就是哈希表类型的值。 当编写如 user 这样的代码时，那就意味着要把"user"变量存储在哈希表的根上。 就像编写 root.user一样，这里但并没有名"root"为的变量， 那么这就起不到任何作用了。

　　某些人也许会被这种数据模型的例子所困惑，也就是说，根哈希表包含更多的哈希表或序列 (lotteryNumbers and cargo)。其它就没有更特殊的内容了。 哈希表包含其他变量，那些变量包含其它值，这些数值可以是字符串，数字等变量， 当然也可以是哈希表或序列变量。最初我们解释过的，就像字符串和数字， 序列或哈希表也是一种值的表示形式。

2.类型

2.1 标量

　　标量是最基本，最简单的数值类型，它们可以是：

• 字符串：表示简单的文本，例如：产品的名称。

  如果想在模板中直接给出字符串值，而不是使用数据模型中的变量， 那么将文本内容写在引号内即可，比如 "green mouse" 或 'green mouse'。

• 数值：比如说，产品的价格。 整数和非整数是不区分的；只有单一的数字类型。比如使用了计算器， 计算3/2的结果是1.5而不是1。

  如果要在模板中直接给出数字的值，那么可以这么来写： 150 或 -90.05 或 0.001。

• 布尔值：布尔值代表了逻辑上的对或错(是或否)。比如：用户是否登录了。 典型的应用是使用布尔值作为 if 指令的条件， 比如 <#if loggedIn >...</#if> 或者 <#if price == 0>...</#if>； 后面这个 price == 0 部分的结果就是布尔值。

  在模板中可以使用保留字 true 和 false 来指定布尔值。

• 日期：日期变量可以存储和日期/时间相关的数据。 一共有三种变化：

  • 日期：精确到天的日期，没有时间部分。比如April 4, 2003。

  • 时间：精确到毫秒，没有日期部分。比如10:19:18 PM。

  • 日期-时间(有时也被称为"时间戳")，比如April 4,2003 10:19:18 PM。 有日期和时间两部分，时间部分的存储精确到毫秒。

  不幸的是，受到Java平台的限制，FreeMarker 有时是不能决定日期的部哪分被使用 (也就是说，是日期-时间格式，日期格式还是时间格式)。 这个问题的解决方法是一个的高级话题，将会在 后续章节讨论。

  模板中直接定义日期数值是可以的，但这也是高级话题，将会在 后续章节 中进行解释。

　　要记住，FreeMarker区别字符串，数字，布尔值和日期类型的值。比如， 字符串 "150" 看起来很像数字 150， 字符串只是字符的任意序列，不能将它用于计算目的，也不能和其它数字进行比较等等。

2.2 容器

　　这些值存在的目的是为了包含其他变量；它们只是容器。 它们包含的变量通常视为 subvariables (子变量)。容器的类型有：

• 哈希表：每个子变量都可以通过一个唯一的名称来查找。 这个名称是不受限制的字符串。哈希表 并不确定其中子变量的顺序。 也就是说没有第一个子变量，第二个子变量这样的说法等；变量仅仅是通过名称来访问的。 (就像Java语言中的HashMap一样，是实现了Hash算法的Map，不记录内部元素的顺序， 仅仅通过名称来访问。)

• 序列：每个子变量通过一个整数来标识。第一个子变量的标识符是0， 第二个是1，第三个是2，这样来类推，而且子变量是有顺序的。这些数次通常被称为 indexes(索引)。序列通常比较密集，也就是所有的索引， 包括最后一个子变量的，它们和子变量都是相关联的，但不是绝对必要的。 子变量的类型也并不需要完全一致。

• 集合：从模板设计者角度来看，集合是有限制的序列。不能获取集合的大小， 也不能通过索引取出集合中的子变量，但是它们仍然可以通过 list 指令来遍历。

　　请注意，一个值也可有多种类型，对于一个值可能同时存在哈希表和序列这两种类型，这时， 该变量就支持索引和名称两种访问方式。 不过容器基本是当作哈希表或者序列来使用的，而不是两者同时使用。

　　尽管存储在哈希表，序列(集合)中的变量可以是任意类型的， 这些变量也可以是哈希表，序列(或集合)。这样就可以构建任意深度的数据结构。

　　数据模型本身(最好说成是它的根root)也是哈希表。

2.3 子程序

2.3.1方法和函数

　　当一个值是方法或函数的时候，那么它就可以计算其他值，结果取决于传递给它的参数。

　　这部分是对程序员来说的：方法/函数是一等类型值， 就像函数化的编程语言。也就是说函数/方法也可以是其他函数/方法的参数或者返回值， 并可以把它们定义成变量等。

　　假设程序员在数据模型中放置了一个方法变量 avg， 该变量用来计算数字的平均值。如果给定3和5作为参数，访问 avg 时就能得到结果4。

　　方法的使用将会在 后续章节 中进行解释， 下面这个示例会帮助我们理解方法的使用：

 The average of 3 and 5 is: ${avg(3, 5)}
 The average of 6 and 10 and 20 is: ${avg(6, 10, 20)}
 The average of the price of a python and an elephant is:
 ${avg(animals.python.price, animals.elephant.price)}

　　将会输出：

 The average of 3 and 5 is: 4
 The average of 6 and 10 and 20 is: 12
 The average of the price of a python and an elephant is:
 4999.5

　　那么方法和函数有什么区别呢？这是模板作者所关心的， 它们没有关系，但也不是一点关系都没有。 方法是来自于数据模型 (它们反射了Java对象的方法) 而函数是定义在模板内的 (使用 function 指令 -- 也是高级话题)，但二者可以用同一种方式来使用。

2.3.2 用户自定义指令

　　这种类型的值可以作为用户自定义指令(换句话说，就是FreeMarker的标签) 用户自定义指令是一种子程序，一种可以复用的模板代码段。但这也是一个高级话题， 将会在 后续章节 中进行解释。

　　这部分是对程序员来说的： 用户自定义指令(比如宏)也是一等值类型，就像函数/方法一样。

　　这里仅仅对用户自定义指令有一个认识即可(如果现在还不能理解可以先忽略它)。 假设现在有一个变量 box，它的值是用户自定义的指令， 用来打印一些特定的HTML信息，包含标题和一条信息。那么， box 变量就可以在模板中使用(示例如下)：

 <@box title="Attention!">
   Too much copy-pasting may leads to
   maintenance headaches.
 </@box>

2.3.3 函数/方法和用户自定义指令的比较

　　 如果要使用函数/方法或自定义指令去实现一些东西的时候， 二者之间的选择是两难的。按经验来说，如果能够实现需求， 请先用自定义指令而不要用函数/方法。如果：

• ... 输出(返回值)的是标记(HTML,XML等)。 主要原因是函数的返回结果可以自动进行XML转义(这是因为 ${...} 的特性)， 而用户自定义指令的输出则不是 (这是因为 <@...> 的特性所致; 它的输出假定是标记，因此已经转义过了)。

• ... 副作用也是很重要的一点，它没有返回值。 例如一个指令的目的是往服务器日志中添加一条。 (事实上不能得到自定义指令的返回值， 但有些反馈的类型是有可能设置非本地变量的。)

• ... 会进行流程的控制(就像 list 或 if 指令那样)。但是不能在函数/方法上这么做。

　　在模板中，FreeMarker不知道的Java对象的方法通常是可以作为方法来使用的， 而不用考虑Java对象方法本身的特性，因为在这里没有其他的选择。

2.4 其它

2.4.1 结点

　　结点变量代表了树状结构中的一个结点，而且通常是配合 XML 处理的，这是专业而且更高级的话题。

　　这里我们仅对 高级用户 进行一个概要说明： 结点和存储在其他结点中的序列很相似，通常也被当作为子结点。结点存储它所在的容器结点的引用， 也就是父结点。结点的主要作用是拓扑信息；其它数据必须通过使用多类型的值来存储。 就像一个值可以同时是一个结点和一个数字，这样它存储的数字可以作为如支付额来使用。 除了拓扑信息，结点也可以存储一些元信息(即metadata，译者注)：如结点名称，它的类型(字符串), 命名空间(字符串)。若一个结点象征XHTML文档中的 h1 元素， 那么它的名字可以是 "h1"，类型可以是 "element"， 命名空间可以是 "http://www.w3.org/1999/xhtml"。但对于数据模型设计者来说， 这些元信息，还有如何来使用它们又有什么意义呢。检索拓扑信息和元信息的方法将会在 后续章节 中来说明(这里可以先不用理解它们)。

译自 Email: ddekany at users.sourceforge.net