内置日期/时间/日期时间值

Page Contents

• 日期，时间，日期时间(当与日期/时间/日期时间值一起使用时)

• date_if_unknown，time_if_unknown，datetime_if_unknown

• iso_...

• 字符串(与日期/时间/日期时间值一起使用时)

日期，时间，日期时间(当与日期/时间/日期时间值一起使用时)

这些内置函数可用于指定使用类似日期的变量的哪些部分：

• date：仅日期，一天中没有时间。

• time：只有一天中的时间，没有日期部分

• datetime：日期和时间

理想情况下，您不需要使用这些内置插件。不幸的是，由于 Java 平台的技术局限性，FreeMarker 有时无法找出类似日期的值的哪些部分是日期，时间或日期时间。问程序员哪些变量有此问题。如果 FreeMarker 必须在需要此信息的位置执行操作(例如，将值显示为文本)，但不知道正在使用哪些部件，它将停止并出现错误。这是您必须使用这些内置功能的时间。例如，假设openingTime是这样的问题变量：

<#assign x = openingTime> <#-- no problem can occur here -->
${openingTime?time} <#-- without ?time it would fail -->
<#-- For the sake of better understanding, consider this: -->
<#assign openingTime = openingTime?time>
${openingTime} <#-- this will work now -->

这些内置函数也可以用于将日期时间值转换为日期或时间。例如：

Last updated: ${lastUpdated} <#-- assume that lastUpdated is a date-time value -->
Last updated date: ${lastUpdated?date}
Last updated time: ${lastUpdated?time}

将输出类似：

Last updated: 04/25/2003 08:00:54 PM
Last updated date: 04/25/2003
Last updated time: 08:00:54 PM

如果?的左侧是字符串，则这些内置的将字符串转换为日期/时间/日期时间。

date_if_unknown，time_if_unknown，datetime_if_unknown

内置date_if_unknown，time_if_unknown，datetime_if_unknown标记带有一些子类型的类似日期的值：分别为不带时间的日期，时间或日期时间。但是，如果该值已包含此信息，则内置无效。也就是说，它将永远不会转换值的子类型，仅在未知时才添加子类型。

iso_...

这些内置函数将日期，时间或日期时间值转换为遵循 ISO 8601：2004“扩展”格式的字符串。

此内置变量有多种变体：iso_utc，iso_local，iso_utc_nz，iso_local_nz，iso_utc_m，iso_utc_m_nz等。名称由以下单词按此 Sequences 构造，每个单词之间用_隔开。

• iso(必填)

• utc或local(必填(除非使用参数给定，但稍后再说))：指定是要根据 UTC 还是根据当前时区打印日期/时间/日期时间。当前时区由time_zone FreeMarker 设置决定，通常由程序员在模板外部进行配置(但也可以在模板中进行设置，例如<#setting time_zone="America/New_York">)。请注意，如果设置了sql_date_and_time_time_zone FreeMarker 设置而不是null，则对于java.sql.Date和java.sql.Time值(即，对于通过 SQL 来自数据库的仅日期和仅时间值)，local表示时区而不是值time_zone设置。

• h或m或ms(可选)：时间部分的准确性。如果省略，则默认为秒精度(如12:30:18)。 h表示小时精度(如12)，m表示分钟精度(12:30)，ms表示毫秒精度(12:30:18.25，我们有 250 ms)。请注意，使用ms时，毫秒显示为小数秒(遵循标准)，并且不包含尾随的0 -s。因此，如果毫秒部分恰好是0，则整个分数第二部分将被省略。还要注意，分数秒总是用点而不是逗号分隔(以遵循 Web 约定和 XML Schema time/dateTime 规范格式)。

• nz(可选)：nz(如${foo?utc_local_nz})代表“无时区”，这意味着将不显示时区偏移量(如+02:00或-04:30或Z)。如果省略此部分(如${foo?utc_local})，则将显示区域，但以下两种情况除外：

• 如果该值为日期(无时间部分)值(同样，ISO 8901 则不允许这样做)

• 如果值是java.sql.Time和incompatible_improvements(通常通过 Java Configuration构造函数参数设置)，则 FreeMarker 的配置设置至少应为 2.3.21(如果在字符串 Literals 中，则为 2.3.24)。这是因为大多数数据库存储的时间值不在任何时区中，而仅存储时，分，秒和十进制秒字段值，因此显示时区没有任何意义。

请注意，自 FreeMarker 2.3.19 起，偏移量始终包含符合 XML Schema 日期/时间/ dateTime 格式的分钟。 (但是，如果主要为 XML Schema 格式生成，请使用 xs 格式.)

Example:

<#assign aDateTime = .now>
<#assign aDate = aDateTime?date>
<#assign aTime = aDateTime?time>

Basic formats:
${aDate?iso_utc}
${aTime?iso_utc}
${aDateTime?iso_utc}

Different accuracies:
${aTime?iso_utc_ms}
${aDateTime?iso_utc_m}

Local time zone:
${aDateTime?iso_local}

可能的输出(取决于当前时间和时区)：

Basic formats:
2011-05-16
21:32:13Z
2011-05-16T21:32:13Z

Different accuracies:
21:32:13.868Z
2011-05-16T21:32Z

Local time zone:
2011-05-16T23:32:13+02:00

还有另一组iso_...内置变体，其中您从名称中省略了local或utc单词，而是将时区指定为内置参数。例：

<#assign aDateTime = .now>
${aDateTime?iso("UTC")}
${aDateTime?iso("GMT-02:30")}
${aDateTime?iso("Europe/Rome")}

The usual variations are supported:
${aDateTime?iso_m("GMT+02")}
${aDateTime?iso_m_nz("GMT+02")}
${aDateTime?iso_nz("GMT+02")}

可能的输出(取决于当前时间和时区)：

2011-05-16T21:43:58Z
2011-05-16T19:13:58-02:30
2011-05-16T23:43:58+02:00

The usual variations are supported:
2011-05-16T23:43+02:00
2011-05-16T23:43
2011-05-16T23:43:58

如果无法解释时区参数，则模板处理将错误终止。

该参数也可以是java.util.TimeZone对象(可能是 Java 方法的返回值，或者在数据模型中)，而不仅仅是字符串。

字符串(当与日期/时间/日期时间值一起使用时)

此内置将日期转换为具有指定格式的字符串。

可以指定所需的格式，例如?string.format或?string["format"](或等效的历史记录?string("format"))。这些是等效的，除了使用引号引起来的格式外，您可以在format中包括任何字符，例如空格。 format的语法与date_format，time_format和datetime_format的配置设置完全相同； 请参阅那里的可能值的文档。

示例：如果输出的语言环境是美国英语，并且时区是美国太平洋时区，并且openingTime是java.sql.Time，nextDiscountDay是java.sql.Date，并且lastUpdated是java.sql.Timestamp或java.util.Date，则此：

<#-- Predefined format names: -->

${openingTime?string.short}
${openingTime?string.medium}
${openingTime?string.long}
${openingTime?string.full}
${openingTime?string.xs} <#-- XSD xs:time -->
${openingTime?string.iso} <#-- ISO 8601 time -->

${nextDiscountDay?string.short}
${nextDiscountDay?string.medium}
${nextDiscountDay?string.long}
${nextDiscountDay?string.full}
${nextDiscountDay?string.xs} <#-- XSD xs:date -->
${nextDiscountDay?string.iso} <#-- ISO 8601 date -->

${lastUpdated?string.short}
${lastUpdated?string.medium}
${lastUpdated?string.long}
${lastUpdated?string.full}
${lastUpdated?string.medium_short} <#-- medium date, short time -->
${lastUpdated?string.xs} <#-- XSD xs:dateTime -->
${lastUpdated?string.iso} <#-- ISO 8601 combined date and time -->

<#-- Programmer-defined named format (@ + name): -->
${lastUpdated?string.@fileDate}

<#-- Advanced ISO 8601 and XSD formatting: -->
${lastUpdated?string.iso_m_u}
${lastUpdated?string.xs_ms_nz}

<#-- SimpleDateFormat patterns: -->
${lastUpdated?string["dd.MM.yyyy, HH:mm"]}
${lastUpdated?string["EEEE, MMMM dd, yyyy, hh:mm a '('zzz')'"]}
${lastUpdated?string["EEE, MMM d, ''yy"]}
${lastUpdated?string.yyyy} <#-- Same as ${lastUpdated?string["yyyy"]} -->

将打印如下内容：

01:45 PM
01:45:09 PM
01:45:09 PM PST
01:45:09 PM PST
13:45:09-08:00
13:45:09-08:00

2/20/07
Apr 20, 2007
April 20, 2007
Friday, April 20, 2007
2007-02-20-08:00
2007-02-20

2/20/07 01:45 PM
Feb 20, 2007 01:45:09 PM
February 20, 2007 01:45:09 PM PST
Friday, February 20, 2007 01:45:09 PM PST
Feb 8, 2003 9:24 PM
2007-02-20T13:45:09-08:00
2007-02-20T13:45:09-08:00

Apr/20/2007 13:45

2007-02-20T21:45Z
2007-02-20T13:45:09.000

08.04.2003 21:24
Tuesday, April 08, 2003, 09:24 PM (PDT)
Tue, Apr 8, '03
2003

请注意，使用自定义格式(如上面的lastUpdated?string.@fileDate)，模板只能引用应用程序域的含义，并且可以在模板外部的中心位置指定确切格式。 (程序员可以阅读有关在这里定义这样的命名格式...的信息)

为避免误解，格式不必是字符串 Literals，它可以是变量或任何其他表达式，只要其结果为字符串即可。例如，它可以像"..."?string[myFormat]。

另请参阅：日期插值