VTL velocity 参考手册

VTL 参考 - 内容

关于本指南

本指南是速度模板语言 （VTL） 的参考。有关更多信息，另请参阅 Velocity 用户指南。

符号以非常近似的类似 EBNF 的语法给出，目标是保持可读性。

引用

在以下语法引用中，标识符引用：

( 一个。。z | 一个。。Z | _ ） [ （ a..z | 一个。。Z | 0..9 | _ ） ， （ a..z | 一个。。Z | 0..9 | _ ）， ... ]

也就是说，一个字母或下划线后跟任意数量的字母、数字和下划线。

如果配置值设置为 true，则标识符中也允许使用 - 连字符（并且必须用空格包围才能解释为算术减号运算符）。parser.allow_hyphen_in_identifiers

变量

表示法：

$ [ ！ ] [ { ] 标识符 [ [ | 备用值 ] } ]

用法：

• 替代值：引用为 null、空、false 或零时要使用的替代表达式

例子：

• 速记符号：$mudSlinger_9
• 静默速记符号：$!mudSlinger_9
• 正式表示法：${mudSlinger_9}
• 静默形式表示法：$!{mudSlinger_9}
• 备用值：${mudSlinger_9|$otherWheels}

请注意，出于向后兼容性原因，可以在变量标识符中启用“-”作为有效字符，请参阅解析器配置部分。

性能

表示法：

$ [ { ] 标识符 . 标识符 [ [ | 备用值 ] } ]

用法：

• 备用值：在属性为 null、空、false 或零时使用的备用表达式

例子：

• 常规表示法：$customer.Address
• 形式表示法：${purchase.Total}
• 备用值：${person.name|'John Doe'}

方法

表示法：

$ [ { ] 标识符 . 标识符 （ [ 参数列表... ] ） [ [ | 备用值 ] } ]

用法：

• 备用值：在方法返回 null、空、false 或零时使用的替代表达式
• 参数列表：可选的逗号分隔表达式列表

例子：

• 常规表示法：$customer.getAddress()
• 形式表示法：${purchase.getTotal()}
• 带参数列表的常规表示法：$page.setTitle( "My Home Page" )
• 备用值：${page.getTitle()|'Blank Page'}

VTL 属性可用作采用 get 和 set 的 VTL 方法的速记表示法。$object.getMethod（） 或 $object.setMethod（） 都可以缩写为 $object。方法。通常最好在可用时使用属性。属性和方法之间的主要区别在于，您可以为方法指定参数列表。

每个方法参数可以是任何有效的 VTL 表达式。

指令

#set - 建立引用的值

格式：

# [ { ] 集合 [ } ] （ $ref = [ “， ' ] 参数 [ ”， ' ] )

用法：

• $ref - 赋值的 LHS 必须是变量引用或属性引用。
• arg - 赋值的 RHS，如果用双引号括起来，则解析（即内插），如果括在单引号中，则不解析。如果 RHS 的计算结果为空，则不会将其分配给 LHS。

例子：

• 变量参考：#set( $monkey = $bill )
• 字符串文字：#set( $monkey.Friend = 'monica' )
• 属性参考：#set( $monkey.Blame = $whitehouse.Leak )
• 方法参考：#set( $monkey.Plan = $spindoctor.weave($web) )
• 数字文字：#set( $monkey.Number = 123 )
• 范围运算符：#set( $monkey.Numbers = [1..3] )
• 对象列表：#set( $monkey.Say = ["Not", $my, "fault"] )
• 对象映射：#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"})

RHS 也可以是一个简单的算术表达式，例如：

• 加法：#set( $value = $foo + 1 )
• 减法：#set( $value = $bar - 1 )
• 乘法：#set( $value = $foo * $bar )
• 划分：#set( $value = $foo / $bar )
• 剩余：#set( $value = $foo % $bar )

#if/#elseif/#else - 输出条件为陈述的真实性

格式：

# [ { ] 如果 [ } ] （ 条件 ） 输出 [# [ { ] elseif [ } ] （ 条件 ） 输出 ] [ # [ { ] else [ } ] 输出 ] # [ { ] 结束 [ } ]

用法：

• 条件 - 要计算的表达式。当其结果为 null 时，计算结果为 false。否则，请检查向布尔和非空的转换，如下所示：

  • 返回布尔对象的值，或 getAsBoolean（） 方法的结果（如果存在）。
  • 如果 = （默认），则在此处停止并认为它为 true。directive.if.empty_checkfalsetrue
  • 返回数组是否为空。
  • 返回 isEmpty（） 是否为 false（涵盖 String 和所有集合类）。
  • 返回 length（） 是否为零（涵盖 String 以外的 CharSequence 类）。
  • 返回 size（） 是否为零（涵盖所有集合类）。
  • 返回数字是否严格等于零。
  • 如果存在，则返回 getAsString（） 的结果是否为空（对于空结果为 false）。
  • 如果存在，则返回 getAsNumber（） 的结果是否严格等于零（对于空结果为 false）。
  • 考虑条件为true

• 输出 - 可能包含 VTL。

示例（显示不同的运算符）：

笔记：

1. == 运算符可用于比较数字、字符串、同一类的对象或不同类的对象。在最后一种情况下（当对象属于不同的类时），如果两个对象中至少有一个无法转换为数字，则在每个对象上调用 toString（） 方法并比较生成的字符串。
2. 还可以使用括号分隔指令。当文本紧跟在指令之后时，这尤其有用。#else

   #if($foo == $bar)it's true!#{else}it's not!#end 

#foreach - 循环访问对象列表

格式：

# [ { ] foreach [ } ] （ $ref in arg ） 语句 [ # [ { ] else [ } ] 备用语句 ] # [ { ] 结束 [ } ]

用法：

• $ref - 第一个变量引用是项。
• arg - 可以是以下之一：对列表（即对象数组、集合或映射）的引用、数组列表或范围运算符。
• 语句 - 每次 Velocity 在上面表示为 arg 的列表中找到有效项时输出的内容。此输出是任何有效的 VTL，并在循环的每次迭代中呈现。
• 备用语句 - 当 Velocity 未进入循环时（当 arg 为空、为空或没有任何有效的迭代器时）要显示的内容。

#foreach 循环的示例：

• 参考：#foreach ( $item in $items ) $item #else no item #end
• 阵列列表：#foreach ( $item in ["Not", $my, "fault"] ) $item #end
• 范围运算符：#foreach ( $item in [1..3] ) $item #end

在 #foreach 循环中，可以使用以下内容：

• $foreach.count：从 1 开始的循环索引
• $foreach.index：从 0 开始的循环索引
• $foreach.first：在第一次迭代时为 true。
• $foreach.last：在上次迭代时为 true。
• $foreach.hasNext：在上次迭代时为 false。
• $foreach.stop()：存在循环，同义词#break

允许的最大循环迭代次数可通过 在引擎范围内进行控制。默认情况下，没有限制：velocity.properties

# The maximum allowed number of loops. directive.foreach.max_loops = -1 

#include - 呈现 Velocity 未解析的本地文件

格式：

# [ { ] 包括 [ } ] （ arg [ arg2 ...阿恩 ] )

用法：

• arg - 指 TEMPLATE_ROOT 下的有效文件。

例子：

• 字符串：#include( "disclaimer.txt" "opinion.txt" )+
• 变量：#include( $foo $bar )

#parse - 呈现由 Velocity 解析的本地模板

格式：

# [ { ] parse [ } ] （ arg )

用法：

• arg - 指 TEMPLATE_ROOT 下的模板。

例子：

• 字符串：#parse( "lecorbusier.vm" )
• 变量：#parse( $foo )

允许递归。请参阅 directive.parse.max_depth in 以更改解析深度。（默认分析深度为 10。velocity.properties

#stop - 停止模板引擎

格式：

# [ { ] 停 [ } ]

用法：

这将停止当前模板的执行。这适用于调试模板。

#break - 停止当前指令

格式：

# [ { ] 破 [ } ]

用法：

这将中断当前内容指令的执行。这有利于提前退出 #foreach 循环，但也适用于其他范围。您甚至可以传递特定外部作用域的范围控件引用，以将所有作用域的执行向外中断到指定的范围。

#evaluate - 动态计算字符串或引用

格式：

# [ { ] 评估 [ } ] （ 参数 )

用法：

• arg - 要动态计算的字符串文本或引用。

例子：

• 字符串：#evaluate( 'string with VTL #if(true)will be displayed#end' )
• 变量：#evaluate( $foo )

#define - 将 VTL 块分配给引用

格式：

# [ { ] define [ } ] （ $ref ） 语句 # [ { ] end [ } ]

用法：

• $ref - 将 VTL 块作为值分配的引用。
• 语句 - 分配给引用的语句。

例：

• #define( $hello ) Hello $who #end #set( $who = "World!") $hello ## displays Hello World!

#macro - 允许用户根据需要定义速度宏 （VM），即 VTL 模板的重复段

格式：

# [ { ] 宏 [ } ] （ 虚拟机名称 $arg 1 [ = def1 ] [ $arg 2 [ = def2 ] $arg 3 [ = def3 ] ...$argn [ = defn ] ] ） [ VTL 代码 ] # [ { ] 结束 [ } ]

用法：

• vmname - 用于调用 VM 的名称 （#vmname)
• $arg 1 $arg 2 ... - VM 的参数。可以有任意数量的参数，但调用时使用的数字必须与定义中指定的数字匹配，除非为缺少的参数提供了默认值。
• def1， def2， ...- 为宏参数提供的可选默认值。如果为参数提供了默认值，则还必须为所有后续参数提供默认值。
• VTL 代码 - 任何有效的 VTL 代码（可以放入模板的任何内容）都可以放入 VM。

定义后，VM 将像模板中的任何其他 VTL 指令一样使用。

#vmname( $arg1 $arg2 ) 

但是，当您希望使用正文调用 VM 时，必须在 VM 名称前面加上 @。该正文的内容可以通过 $！bodyContent 在宏定义中引用，次数不限。

#@vmname( $arg1 $arg2 ) here is the body#end 

可以在以下两个位置之一定义 VM：

1. 模板库：可以是使用 Velocity 预打包的虚拟机，也可以是定制的、用户定义的、特定于站点的虚拟机;可从任何模板使用
2. 内联：在常规模板中找到，仅在 velocimacro.permissions.allowInline=true 中使用。velocity.properties

从 2.0 开始，当宏参数为 null 或无效时，其呈现将显示其本地名称。以下代码块：

#macro( vmname $foo ) $foo #end #vmname( $null ) 

将显示 。如果您希望恢复到 1.x 行为（即显示），则可以将配置属性设置为 true（从 2.2 开始）。$foo$nullvelocimacro.enable_bc_mode

评论

注释不会在运行时呈现。

单行注释

例：

## This is a comment.** 

多行注释

例：

#*  This is a multiline comment.  This is the second line. *# 

未解析的内容

未分析的内容在运行时呈现，但不会分析或解释。

例：

#[[ This has invalid syntax that would normally need  "poor man's escaping" like:  - #define()  - ${blah ]]#