setting
概要
<#setting name=value>
这里:
-
name
: 设置的名称。不是表达式! -
value
: 设置的新值,是表达式。
描述
为进一步的处理而设置。设置是影响 FreeMarker 行为的值。 新值仅仅在被设置的模板处理时出现,而且不触碰模板本身。 设置的初始值是由程序员设定的 (参考: 程序开发指南/配置(Configuration)/配置设置)。
支持的设置有:
-
locale
:输出的本地化(语言)。 它可以影响数字,日期等显示格式。它的值是由语言编码 (小写两个字母的ISO-639编码)和可选的国家码 (大写的两个字母ISO-3166编码)组成的字符串,它们以下划线相分隔, 如果我们已经指定了国家那么一个可选的不同编码 (不是标准的)会以下划线分隔开国家。合法的值示例:en
,en_US
,en_US_MAC
。 FreeMarker 会尝试使用特定可用的本地化设置,所以如果你指定了en_US_MAC
,但是它不被知道,那么它会尝试en_US
,然后尝试en
, 然后是计算机(可能是由程序员设置的)默认的本地化设置。 -
number_format
: 当没有指定确定的格式化形式时,用来转化数字到字符串形式的数字格式化设置。 可以是下列中的一个预定义值number
(默认的),computer
,currency
, 或percent
。此外,以 Java小数数字格式化语法 书写的任意的格式化形式也可以被指定。 更多格式形式内容:string
内建函数。 -
boolean_format
: 以逗号分隔的一对字符串来分别展示 true 和 false 值, 当没有指定确定的格式时(比如在${booleanValue}
中), 将转换布尔值到字符串。请注意,当前的空格没有从该字符串中移除, 所以不要将空格放在逗号后面。默认值是"true,false"
。 但是 FreeMarker 会拒绝为${booleanValue}
使用特定值,而需要使用${booleanValue?c}
来代替(从 2.3.21 版本开始有效)。对于其它任意值,比如"Y,N"
,${booleanValue}
也是有效的。 请参考:string
内建函数。 -
date_format
,time_format
,datetime_format
:当没有通过string
内建函数(或相反)指定确定的格式时,格式将日期/时间/日期-时间值 (Javajava.util.Date
和它的子类)转换为字符串, 比如${someDate}
。date_format
设置仅仅格式于存储的无时间部分的值,time_format
仅仅格式于存储无日期部分的值,而datetime_format
仅仅格式于日期-时间值。除了当它应用于字符串值时,这些设置也影响进行了?time
,?date
, 和?datetime
操作的格式。可能的设置是(引号标记不是值本身的一部分):
-
Java 的
SimpleDateFormat
接受 的模式,例如"dd.MM.yyyy HH:mm:ss"
(这里"HH"
表示 0-23 时) 或"MM/dd/yyyy hh:mm:ss a"
(如果当前语言是英语,这里"a"
输出 AM 或 PM)。 -
"xs"
就是XML Schema 格式,或"iso"
是 ISO 8601:2004 格式。 这些格式允许多个可选项,由空格分隔开,比如"iso m nz"
(或者使用_
,比如"iso_m_nz"
; 比如设置lastModified?string.iso_m_nz
时就很有用)。 选项和它们的意义是:-
精度选择:
-
ms
:毫秒,通常显示3位数字, 即便它们都是0。例如:13:45:05.800
-
s
:秒(如果非0,小数部分就被丢弃了), 比如13:45:05
-
m
:分,比如13:45
。它不允许用于"xs"
。 -
h
:小时,比如13
。它不允许用于"xs"
。 -
两者皆不:上至毫秒的精度,但是尾部的0毫秒就被移除了,
否则,如果它是0,整个毫秒部分也被移除。比如:
13:45:05.8
-
-
时区偏移可见性选项:
-
fz
: "Force Zone",通常显示时区偏移(也对java.sql.Date
和java.sql.Time
值)。但是, 因为 ISO 8601 不允许日期(也就是没有时间的日期)显示时区偏移, 该选项对使用"iso"
的日期就没有作用。 -
nz
: "No Zone", 从不显示时区偏移 -
两者皆不:除了
java.sql.Date
和java.sql.Time
,还有"iso"
日期值,通常都显示时区偏移。
-
-
时区选项:
-
u
:使用 UTC 来代替time_zone
设置建议的内容。 然而,java.sql.Date
和java.sql.Time
不受它影响 (参考sql_date_and_time_time_zone
去理解为什么) -
fu
: "Force UTC",也就是说,使用 UTC 来代替time_zone
或sql_date_and_time_time_zone
设置建议的内容。这会影响java.sql.Date
和java.sql.Time
值。 -
两者皆不:使用
time_zone
或sql_date_and_time_time_zone
配置设置项建议的时区。
-
来自相同分类的选项是互斥的,比如一起使用
m
和s
就会有错误。选项可以指定一个任意的顺序。
精度和时区偏移可见性选项不影响解析,只影响格式化。例如, 即使使用
"iso m nz"
,"2012-01-01T15:30:05.125+01"
也会被成功解析含有毫秒精度。仅当解析不包含时区偏移的字符串时, 时区选项(比如"u"
) 影响选择的时区。使用
"iso"
解析会理解 "extend format" 和 "basic format",比如20141225T235018
。 它不支持所有的 ISO 8601 字符串:如果有日期部分, 必须使用年,月和日值(不是年中的星期),并且日不能被忽略。"iso"
的输出是有意的, 所以它也是有 XML Schema 格式值的很好表述,除了0和负数的年, 这里是不可能的。也请注意,时区偏移在"iso"
格式中是忽略的,而在"xs"
格式中是保留的。 -
-
"short"
,"medium"
,"long"
,或"full"
,这些由Java平台定义,有本地依赖含义 (参考java.text.DateFormat
的文档)。 对于日期-时间值,可以分别指定日期和时间部分的长度,使用_
将它们分开,比如"short_medium"
。 (对于时间-日期值,"medium"
表示"medium_medium"
。)
-
-
Warning!time_zone
:时区的名称来显示并格式化时间。 默认情况下,使用JVM的时区。也可以是 Java 时区 API 接受的值,或者"JVM default"
(从 FreeMarker 2.3.21 版本开始) 使用JVM默认的时区。比如:"GMT"
,"GMT+2"
,"GMT-1:30"
,"CET"
,"PST"
,"America/Los_Angeles"
。如果修改了该设置的默认值,那么也应该设置
sql_date_and_time_time_zone
为 "JVM default"。在Configurable.setSQLDateAndTimeTimeZone(TimeZone)
的Java API 文档中参考更多内容。 -
sql_date_and_time_time_zone
(从 FreeMarker 2.3.21 版本开始):它控制高度技术性的问题, 所以它应该由程序员在Java代码中来设置。 对于程序员:如果它设置为 非null
,对于来自SQL数据库(更精确地,就是java.sql.Date
和java.sql.Time
对象)的仅日期和仅时间值来说, FreeMarker 会使用该时区来代替由time_zone
设置项指定的时区。在Configurable.setSQLDateAndTimeTimeZone(TimeZone)
的Java API文档中参考更多。 -
url_escaping_charset
: 用来URL转义(比如${foo?url}
)的字符集, 来计算转义(%XX
)的部分。 通常包含 FreeMarker 的框架应该设置它,所以不应该在模板中来设置。(程序员可以在 这里... 阅读更多内容。) -
output_encoding
:告诉 FreeMarker 输出的字符集是什么。因为 FreeMarker 输出 UNICODE 字符集 (写入java.io.Writer
)的流,它不由输出编码所影响, 但是一些宏/函数和内建函数也许想使用这些信息。 -
classic_compatible
:这是对于专家来说的。 它的值应该是布尔值。参考freemarker.template.Configurable
的文档来获取更多信息。
比如:假设初始化的模板本地化是 de_DE (德国)。那么:
${1.2} <#setting locale="en_US"> ${1.2}
将会输出:
1,2 1.2
因为德国人使用逗号作为小数分隔符,而美国人使用点。