日期内建函数

Page Contents

date, time, datetime (当用于日期/时间/日期-时间值时)

这些内建函数用来指定日期变量中的哪些部分被使用：

  • 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

Note:

该内建函数从 FreeMarker 2.3.21 版本开始存在

date_if_unknown， time_if_unknown， datetime_if_unknown 内建函数使用一些子类型来标记日期类型的值：日期没有时间，时间，或日期-时间。 如果变量值已经持有这些信息，那么内建函数就不会起作用。也就是说， 它不会转换变量值的子类型，如果它是未知的，则会添加子类型。

iso_...

Note:

这些内建函数从 FreeMarker 2.3.21 版本开始废弃， 因为 date_format，time_format 和 datetime_format 设置理解 "iso" (ISO 8601:2004 格式) 和 "xs" (XML Schema 格式)，此外还有 Java SimpleDateFormat 格式。因此默认格式可以设置为ISO 8601， 要使用一次ISO格式，可以使用 myDate?string.iso。 更多内容请参考...

这些内建函数转换日期，时间或日期-时间值为字符串，遵循 ISO 8601:2004 "扩展" 格式。

该内建函数有很多表现形式： iso_utc， iso_local， iso_utc_nz， iso_local_nz， iso_utc_m， iso_utc_m_nz，等。 名称的构成由下列单词顺序组成，每部分由一个 _ 分隔开：

  1. iso (必须的)

  2. 是 utc 或 local 二者之一 (必须的(除了给定一个参数，这个后面再来说))： 来指定根据UTC或根据当前时区来打印日期/时间/日期-时间。 当前时区是根据 FreeMarker 的设置项 time_zone 来确定的，它通常是由程序员在模板外配置的(当然它也可以在模板内设置， 比如使用<#setting time_zone="America/New_York">)。 请注意，如果 FreeMarker 设置项 sql_date_and_time_time_zone 已经设置并且非 null，那么对于 java.sql.Date 和 java.sql.Time 值(也就是通过SQL从数据中获得的仅日期值和仅时间值) local 的时区值将会替代 time_zone 设置的值。

  3. h，m 或 ms(可选的)：时间部分的精度。 当忽略的时候，就默认设置到秒的精度(比如12:30:18)。 h 表示小时的精度(比如 12)， m 表示分钟的精度(比如 12:30)， ms 就表示毫秒的精度(12:30:18.25，这里表示250毫秒)。 要注意当使用 ms 时，毫秒会显示为百分制的形式 (遵循标准)而且不会去尾到 0 秒。因此， 如果毫秒的部分变成 0 的话，整个的毫秒的部分就会被忽略掉了。 同时也要注意毫秒的部分是由一个点来分隔的，而不是逗号 (遵循Web约定和XML Schema的日期/时间格式)。

  4. nz (可选的)： nz (比如在 ${foo?utc_local_nz} 中) 代表 "没有时区"，也就意味着时区的偏移量 (比如 +02:00 或者 -04:30 或者 Z)不会显示出来。如果这部分被忽略了 (比如在 ${foo?utc_local} 中) 那么时区就会显示出来， 除了两种情况：

    • 如果值是日期(没有时间部分)值(再说一次，ISO 8901 标准不允许)

    • 如果值是 java.sql.Time 而且 FreeMarker 配置设置项 incompatible_improvements (通常通过 Java代码 Configuration 的构造方法参数设置) 最小是2.3.21。 存储时间值是不分时区的，只是存储小时，分钟，秒和小数秒值， 所以显示时区就没什么意义。

    请注意，从 FreeMarker 2.3.19 版本开始，对于XML Schema 日期/时间/日期时间格式的兼容性，时区偏移量通常包含分钟。 (如果主要生成XML Schema格式，就使用 xs 格式。)

例如：

<#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 (当用于日期/时间/日期-时间值时)

这个内建函数以指定的格式转换日期类型到字符串类型。

Note:

应该很少使用这个内建函数，因为日期/时间/日期-时间值的默认格式可以全局指定 FreeMarker 的 date_format，time_format 和 datetime_format 设置。 该内建函数只在期望格式和常用格式不同的地方使用。在其它地方， 默认格式应该由程序员在模板之外合理地设置。

期望的格式可以由 ?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 那么：

${openingTime?string.short}
${openingTime?string.medium}
${openingTime?string.long}
${openingTime?string.full}
${openingTime?string.xs}
${openingTime?string.iso}

${nextDiscountDay?string.short}
${nextDiscountDay?string.medium}
${nextDiscountDay?string.long}
${nextDiscountDay?string.full}
${nextDiscountDay?string.xs}
${nextDiscountDay?string.iso}

${lastUpdated?string.short}
${lastUpdated?string.medium}
${lastUpdated?string.long}
${lastUpdated?string.full}
${lastUpdated?string.medium_short} <#-- medium date, short time -->
${lastUpdated?string.xs}
${lastUpdated?string.iso}

<#-- 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"]} -->

<#-- Advanced ISO 8601-related formats: -->
${lastUpdated?string.iso_m_u}
${lastUpdated?string.xs_ms_nz}

将会输出：

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

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

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

不幸的是，由于Java平台的限制，在数据模型中可以有日期变量， 那里 FreeMarker 不能决定变量是否是日期(年，月，日)，还是时间 (时，分，秒，毫秒)，或者是日期-时间值。这种情况下，当你编写如 ${lastUpdated?string.short} 或 ${lastUpdated?string.xs} 时，FreeMarker 不知道如何来显示日期，也就是说，格式不指定精确的字段去显示， 或者如果只是简单使用 ${lastUpdated}， 那么模板会中止执行并抛出错误。要阻止这些发生，可以使用 ?date， ?time 和 ?datetime 内建函数 来帮助 FreeMarker。例如： ${lastUpdated?datetime?string.short}。 要询问程序员数据模型中确定的变量是否有这个问题， 或通常使用内建函数 ?date，?time 和 ?datetime 来安全处理。

Note:

不需和格式模式使用 ?date, ?time 或 ?datetime， 比如 "yyyy.MM.dd HH:mm"，因为使用这些模式， 就告诉 FreeMarker 来显示哪部分日期。那么，FreeMarker 将盲目地相信你， 如果你显示的部分不存在于变量中，则可以显示"干扰"。例如， ${openingTime?string["yyyy-MM-dd hh:mm:ss a"]}, 而 openingTime 中只存储了时间，将会显示 1970-01-01 09:24:44 PM。

要避免误解，需要的格式不是字符串，它可以是变量或任意表达式，比如 "..."?string[myFormat]。

请参考： 日期的插入