setting

优质

小牛编辑

129浏览

2023-12-01

概要

<#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 内建函数(或相反)指定确定的格式时，格式将日期/时间/日期-时间值 (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.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"。)
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.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

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