setting

Page Contents

• Synopsis

• Description

Synopsis

<#setting name=value>

Where:

• name：设置的名称。不是表情！

• value：设置的新值。表达

Description

为后续处理设置设置。设置是影响 FreeMarker 行为的值。新值将仅在设置它的模板处理中出现，并且不会触及模板本身。设置的初始值由程序员设置(请参阅：程序员指南/配置/设置)。

支持的设置为：

• locale：输出的语言环境(语言)。它可以影响数字，日期等的表示格式。该值是一个字符串，由一个语言代码(小写的两个字母的 ISO-639 代码)加上可选的县(大写的两个字母的 ISO-3166 代码)组成，该字符串与带下划线的语言代码，如果我们指定了国家/地区，则使用带下划线的国家/地区分隔的可选变体代码(未标准化)。有效值的示例：en，en_US，en_US_MAC。 FreeMarker 将尝试使用最具体的可用语言环境，因此，如果您指定en_US_MAC，但未知，则它将尝试en_US，然后是en，然后是计算机的默认语言环境(可由程序员设置)。

• number_format：未指定显式格式时用于将数字转换为字符串的数字格式。可以是以下之一：

• Java 平台定义的 sched 义值：number(默认值)，currency或percent

  • computer，其格式类似于内置的 c

  • 用Java 十进制数字格式语法编写的格式模式，例如0.###。 FreeMarker 扩展此格式以允许指定舍入模式，使用的符号等。

  • 以@开头且后跟字母的值是指custom format。例如，"@price"表示以"price"名称注册的自定义格式。自定义格式名称后可能跟空格或_，然后是格式参数，其解释取决于自定义格式。为了向后兼容，如果incompatible_improvements 设置至少为 2.3.24 或定义了任何自定义格式，则初始@仅具有此新含义。如果首字母@后没有字母(任何 UNICODE 字母)，则永远不会将其视为对自定义格式的引用。

• boolean_format：分别用逗号分隔的一对字符串，分别表示真值和假值，用于在未指定显式格式的情况下将布尔值转换为字符串(如${booleanValue})。请注意，当前不会从此字符串中删除空格，因此请勿在逗号后放置空格。默认值为"true,false"，但是 FreeMarker 会拒绝对${booleanValue}使用该特定值，而是要求使用${booleanValue?c}(自 2.3.21 开始有效)。对于任何其他值，例如"Y,N"，${booleanValue}将起作用。另请参阅：string built-in。

• date_format，time_format，datetime_format：在没有通过string built-in(或其他方式)指定显式格式的情况下，用于将日期/时间/日期时间值(Java java.util.Date -s 及其子类)转换为字符串的格式的${someDate}。 date_format设置仅影响不存储任何时间部分的日期值的格式，time_format仅影响不存储任何时间部分的日期格式，并且datetime_format仅影响日期-时间值的格式。这些设置还会影响时间，日期和日期时间应用于字符串值时期望的格式。

可能的设置值为(引号不是值本身的一部分)：

• 模式被 Java 的 SimpleDateFormat 接受，例如"dd.MM.yyyy HH:mm:ss"(其中"HH"表示 0-23 小时)或"MM/dd/yyyy hh:mm:ss a"(其中"a"如果当前语言是英语，则"a"打印 AM 或 PM)。

• "xs"用于 XML 模式格式，或"iso"用于 ISO 8601：2004 格式。这些格式允许各种其他选项，以空格分隔，例如"iso m nz"(或_，例如"iso_m_nz"；在lastModified?string.iso_m_nz的情况下很有用)。选项及其含义是：

• Accuracy options:

• ms：毫秒，即使全为 0，也始终显示所有 3 位数字。示例：13:45:05.800

   - `s` : Seconds \(fraction seconds are dropped even if non\-0\), like  `13:45:05`
  
   - `m` : Minutes, like  `13:45` \. This isn't allowed for  `"xs"` \.
  
   - `h` : Hours, like  `13` \. This isn't allowed for  `"xs"` \.
  
   - Neither: Up to millisecond accuracy, but trailing millisecond 0\-s are removed, also the whole milliseconds part if it would be 0 otherwise\. Example:  `13:45:05.8`
  

  • 时区偏移量可见性选项：

• fz：“强制区域”，始终显示时区偏移(即使对于java.sql.Date和java.sql.Time值也是如此)。但是，由于 ISO 8601 不允许日期(无日期的平均日期)显示区域偏移，因此此选项对于带有日期的"iso"无效。

   - `nz` : "No Zone", never show time zone offset
  
   - Neither: Always show time zone offset, except for  `java.sql.Date`  and  `java.sql.Time` , and for  `"iso"`  date values\.
  

  • 时区选项：

• u：使用 UTC 而不是time_zone设置所建议的内容。但是，java.sql.Date和java.sql.Time不受此影响(请参阅sql_date_and_time_time_zone了解原因)

   - `fu` : "Force UTC", that is, use UTC instead of what the  `time_zone`  or the  `sql_date_and_time_time_zone`  setting suggests\. This also effects  `java.sql.Date`  and  `java.sql.Time`  values
  
   - Neither: Use the time zone suggested by the  `time_zone`  or the  `sql_date_and_time_time_zone`  configuration setting
  

来自同一类别的选项是互斥的，例如一起使用m和s是错误。

可以以任何 Sequences 指定选项。

准确性和时区偏移可见性选项不影响解析，仅影响格式。例如，即使您使用"iso m nz"，也将成功解析"2012-01-01T15:30:05.125+01"且精度为毫秒。时区选项(如"u")仅在解析不包含时区偏移量的字符串时影响选择哪个时区。

使用"iso"进行解析可以理解“扩展格式”和“基本格式”，例如20141225T235018。但是，它不支持所有类型的 ISO 8601 字符串的解析：如果有日期部分，则必须使用年，月和月中的日期值(而不是一年中的星期)，并且日期不能被省略。

"iso"的输出是有意的，因此它也是 XML Schema 格式的值的良好表示形式，除了 0 和负数年份(这是不可能的)之外。另请注意，对于"iso"格式的日期值，时区偏移量被省略，而对于"xs"格式则保留时区偏移量。

• "short"，"medium"，"long"或"full"，它们具有 Java 平台定义的与语言环境相关的含义(请参见java.text.DateFormat 的文档)。对于日期时间值，您可以独立指定日期和时间部分的长度，用_分隔它们，例如"short_medium"。 ("medium"表示"medium_medium"表示日期时间值.)

• 以@开头且后跟字母的值表示custom format，例如"@worklog"表示以"worklog"名称注册的自定义格式。格式名称后可能跟空格或_，然后是格式参数，其解释取决于自定义格式。为了向后兼容，如果incompatible_improvements 设置至少为 2.3.24 或定义了任何自定义格式，则初始@仅具有此新含义。如果首字母@后没有字母(任何 UNICODE 字母)，则永远不会将其视为对自定义格式的引用。

• time_zone：用于格式化显示时间的时区名称。与所有设置一样，程序员在设置 FreeMarker 时(通过Configuration类)选择了默认值，但这通常是 JVM 的默认时区。可以是Java TimeZone 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(自 FreeMarker 2.3.21 起)：这处理了一个技术性很强的问题，因此通常应由程序员从 Java 代码进行设置。对于程序员：如果将其设置为非null，则对于来自 SQL 数据库的仅日期和仅时间值(更准确地说，对于java.sql.Date和java.sql.Time对象)，FreeMarker 将使用该时区而不是time_zone指定的时区。 FreeMarker 设置。参见Configurable.setSQLDateAndTimeTimeZone(TimeZone)的 Java API 文档中的更多内容。

• url_escaping_charset：用于 URL 转义(例如${foo?url})的字符集，以计算转义的(%XX)部分。通常，包含 FreeMarker 的框架应该对其进行设置，因此几乎不需要在模板中进行设置。 (程序员可以阅读有关此here...的更多信息)

• output_encoding：告诉 FreeMarker 输出的字符集是什么。由于 FreeMarker 输出 UNICODE 字符流(它写入java.io.Writer)，因此不受输出编码的影响，但是某些宏/函数和内置函数可能希望使用此信息。

• classic_compatible：用于与非常旧的 FreeMarker 版本(主要是 1.7.x)更好地兼容。有关更多信息，请参见freemarker.template.Configurable.isClassicCompatible()的文档。

示例：假设模板的初始语言环境为de_DE(德语)。然后这样：

${1.2}
<#setting locale="en_US">
${1.2}

将输出以下内容：

1,2
1.2

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