概要

<#setting name=value>

这里:

  • name: 设置的名称。不是表达式!
  • value: 设置的新值,是表达式。

描述

为进一步的处理而设置。设置是影响 FreeMarker 行为的值。 新值仅仅在被设置的模板处理时出现,而且不触碰模板本身。 设置的初始值是由程序员设定的 (参考: 程序开发指南/配置(Configuration)/配置设置)

支持的设置有:

  • locale:输出的本地化(语言)。 它可以影响数字,日期等显示格式。它的值是由语言编码 (小写两个字母的ISO-639编码)和可选的国家码 (大写的两个字母ISO-3166编码)组成的字符串,它们以下划线相分隔, 如果我们已经指定了国家那么一个可选的不同编码 (不是标准的)会以下划线分隔开国家。合法的值示例:enen_USen_US_MAC。 FreeMarker 会尝试使用特定可用的本地化设置,所以如果你指定了 en_US_MAC,但是它不被知道,那么它会尝试 en_US,然后尝试 en, 然后是计算机(可能是由程序员设置的)默认的本地化设置。

  • number_format: 当没有指定确定的格式化形式时,用来转化数字到字符串形式的数字格式化设置。 可以是下列中的一个预定义值 number(默认的), computercurrency, 或 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 内建函数(或相反)指定确定的格式时,格式将日期/时间/日期-时间值 (Java java.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.Datejava.sql.Time 值)。但是, 因为 ISO 8601 不允许日期(也就是没有时间的日期)显示时区偏移, 该选项对使用 "iso" 的日期就没有作用。
        • nz: "No Zone", 从不显示时区偏移
        • 两者皆不:除了 java.sql.Datejava.sql.Time,还有 "iso" 日期值,通常都显示时区偏移。
      • 时区选项:

        • u:使用 UTC 来代替 time_zone 设置建议的内容。 然而,java.sql.Datejava.sql.Time 不受它影响 (参考 sql_date_and_time_time_zone 去理解为什么)
        • fu: "Force UTC",也就是说,使用 UTC 来代替 time_zonesql_date_and_time_time_zone 设置建议的内容。这会影响 java.sql.Datejava.sql.Time 值。
        • 两者皆不:使用 time_zonesql_date_and_time_time_zone 配置设置项建议的时区。

      来自相同分类的选项是互斥的,比如一起使用 ms 就会有错误。

      选项可以指定一个任意的顺序。

      精度和时区偏移可见性选项不影响解析,只影响格式化。例如, 即使使用 "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"。)

  • time_zone:时区的名称来显示并格式化时间。 默认情况下,使用JVM的时区。也可以是 Java 时区 API 接受的值,或者 "JVM default" (从 FreeMarker 2.3.21 版本开始) 使用JVM默认的时区。比如: "GMT""GMT+2""GMT-1:30""CET""PST""America/Los_Angeles"

    Warning!

    如果修改了该设置的默认值,那么也应该设置 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.Datejava.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

因为德国人使用逗号作为小数分隔符,而美国人使用点。