Thymeleaf中文网

深色模式

时间工具（Temporals，Java 8+ java.time API） ​

#temporals 是 Thymeleaf 专为 JDK8+ 新时间 API（java.time 包，如 LocalDate/LocalDateTime/ZonedDateTime 等）设计的工具对象，覆盖格式化、属性提取、对象创建等核心操作（底层对应 org.thymeleaf.expression.Temporals 类，可参考其 JavaDoc 获取完整 API）。

java
/*
 * ======================================================================
 * 请查阅 org.thymeleaf.expression.Temporals 类的 Javadoc API 文档
 * ======================================================================
 */

/*
 * 按系统默认的语言环境（Locale）格式化日期时间。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#temporals.format(temporal)}
${#temporals.arrayFormat(temporalsArray)}
${#temporals.listFormat(temporalsList)}
${#temporals.setFormat(temporalsSet)}

/*
 * 按指定的语言环境（Locale）格式化日期时间。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#temporals.format(temporal, locale)}
${#temporals.arrayFormat(temporalsArray, locale)}
${#temporals.listFormat(temporalsList, locale)}
${#temporals.setFormat(temporalsSet, locale)}

/*
 * 按指定的自定义格式模式格式化日期时间。
 * 也可指定 SHORT、MEDIUM、LONG、FULL（使用 Java 原生 java.time.format.FormatStyle 的默认格式）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#temporals.format(temporal, 'dd/MMM/yyyy HH:mm')}
${#temporals.format(temporal, 'dd/MMM/yyyy HH:mm', 'Europe/Paris')}
${#temporals.arrayFormat(temporalsArray, 'dd/MMM/yyyy HH:mm')}
${#temporals.listFormat(temporalsList, 'dd/MMM/yyyy HH:mm')}
${#temporals.setFormat(temporalsSet, 'dd/MMM/yyyy HH:mm')}

/*
 * 按指定的自定义格式模式和语言环境（Locale）格式化日期时间。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#temporals.format(temporal, 'dd/MMM/yyyy HH:mm', locale)}
${#temporals.arrayFormat(temporalsArray, 'dd/MMM/yyyy HH:mm', locale)}
${#temporals.listFormat(temporalsList, 'dd/MMM/yyyy HH:mm', locale)}
${#temporals.setFormat(temporalsSet, 'dd/MMM/yyyy HH:mm', locale)}

/*
 * 按 ISO-8601 标准格式格式化日期时间（如 2024-05-20T14:30:00）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#temporals.formatISO(temporal)}
${#temporals.arrayFormatISO(temporalsArray)}
${#temporals.listFormatISO(temporalsList)}
${#temporals.setFormatISO(temporalsSet)}

/*
 * 获取日期时间的各组成属性。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数（对应 arrayDay/listDay 等方法）。
 */
${#temporals.day(temporal)}                    // 获取日期中的“日”（1-31），支持数组/列表/集合批量获取
${#temporals.month(temporal)}                  // 获取日期中的“月”（1-12），支持批量获取
${#temporals.monthName(temporal)}              // 获取月份全称（如 January/一月），支持批量获取
${#temporals.monthNameShort(temporal)}         // 获取月份简称（如 Jan/一月），支持批量获取
${#temporals.year(temporal)}                   // 获取年份（如 2024），支持批量获取
${#temporals.dayOfWeek(temporal)}              // 获取星期几（1=周一/周日，依Locale而定），支持批量获取
${#temporals.dayOfWeekName(temporal)}          // 获取星期全称（如 Monday/星期一），支持批量获取
${#temporals.dayOfWeekNameShort(temporal)}     // 获取星期简称（如 Mon/周一），支持批量获取
${#temporals.hour(temporal)}                   // 获取小时（0-23），支持批量获取
${#temporals.minute(temporal)}                 // 获取分钟（0-59），支持批量获取
${#temporals.second(temporal)}                 // 获取秒（0-59），支持批量获取
${#temporals.nanosecond(temporal)}             // 获取纳秒（0-999999999），支持批量获取

/*
 * 从日期时间组件（年/月/日等）创建 Temporal 对象（java.time.Temporal 类型）。
 */
${#temporals.create(year,month,day)}                                // 创建 LocalDate 实例（仅日期）
${#temporals.create(year,month,day,hour,minute)}                    // 创建 LocalDateTime 实例（日期+时分）
${#temporals.create(year,month,day,hour,minute,second)}             // 创建 LocalDateTime 实例（日期+时分秒）
${#temporals.create(year,month,day,hour,minute,second,nanosecond)}  // 创建 LocalDateTime 实例（日期+时分秒纳秒）

/*
 * 创建表示当前日期时间的 Temporal 对象（java.time.Temporal 类型）。
 */
${#temporals.createNow()}                      // 创建当前系统时间的 LocalDateTime 实例
${#temporals.createNowForTimeZone(zoneId)}     // 创建指定时区（如 Asia/Shanghai）的 ZonedDateTime 实例
${#temporals.createToday()}                    // 创建当前系统日期的 LocalDate 实例（仅日期，时间为0）
${#temporals.createTodayForTimeZone(zoneId)}   // 创建指定时区的当前日期 LocalDate 实例

/*
 * 从指定的日期字符串创建 Temporal 对象（java.time.Temporal 类型）。
 */
${#temporals.createDate(isoDate)}              // 从 ISO 格式字符串（如 2024-05-20）创建 LocalDate 实例
${#temporals.createDateTime(isoDate)}          // 从 ISO 格式字符串（如 2024-05-20T14:30:00）创建 LocalDateTime 实例
${#temporals.createDate(isoDate, pattern)}     // 从指定格式的字符串创建 LocalDate 实例
${#temporals.createDateTime(isoDate, pattern)} // 从指定格式的字符串创建 LocalDateTime 实例

补充说明（贴合 Thymeleaf 日期时间处理技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
Temporals时间工具类（Thymeleaf 基于 Java 8+ java.time 包的日期时间工具，#temporals 是简写）
temporal时间对象（泛指 LocalDate/LocalDateTime/ZonedDateTime 等 java.time.Temporal 实现类）
FormatStyle格式样式（Java 原生枚举：SHORT=短格式 24-5-20、MEDIUM=中格式 2024-05-20、LONG=长格式 2024年5月20日、FULL=完整格式 2024年5月20日 星期一）
ISO-8601国际标准日期时间格式（如 2024-05-20T14:30:00，跨系统通用）
zoneId时区ID（如 Asia/Shanghai 上海时区、Europe/Paris 巴黎时区，需符合 Java 时区规范）

2. 关键逻辑解读（高频用法示例） ​

html
<!-- 1. 基础格式化（自定义模式） -->
<div th:with="now=${#temporals.createNow()}">
  默认格式：<span th:text="${#temporals.format(now)}"></span> <!-- 2024-05-20 14:30:00（系统Locale） -->
  自定义格式：<span th:text="${#temporals.format(now, 'yyyy年MM月dd日 HH:mm:ss')}"></span> <!-- 2024年05月20日 14:30:00 -->
  ISO格式：<span th:text="${#temporals.formatISO(now)}"></span> <!-- 2024-05-20T14:30:00 -->
</div>

<!-- 2. 获取日期时间属性 -->
<div th:with="date=${#temporals.create(2024,5,20)}">
  年份：<span th:text="${#temporals.year(date)}"></span> <!-- 2024 -->
  月份全称：<span th:text="${#temporals.monthName(date)}"></span> <!-- 五月（中文Locale） -->
  星期几：<span th:text="${#temporals.dayOfWeekName(date)}"></span> <!-- 星期一 -->
</div>

<!-- 3. 从字符串创建时间对象 -->
<div th:with="
  dateStr='2024-05-20',
  dateTimeStr='2024-05-20 14:30:00',
  localDate=${#temporals.createDate(dateStr)},
  localDateTime=${#temporals.createDateTime(dateTimeStr, 'yyyy-MM-dd HH:mm:ss')}
">
  字符串转LocalDate：<span th:text="${localDate}"></span> <!-- 2024-05-20 -->
  自定义格式转LocalDateTime：<span th:text="${localDateTime}"></span> <!-- 2024-05-20T14:30 -->
</div>

<!-- 4. 时区适配 -->
<div th:with="parisTime=${#temporals.createNowForTimeZone('Europe/Paris')}">
  巴黎当前时间：<span th:text="${#temporals.format(parisTime, 'yyyy-MM-dd HH:mm')}"></span> <!-- 比北京时间慢6/7小时 -->
</div>
  • 核心特性：
    • #temporals 仅支持 Java 8+ 的 java.time 系列类（LocalDate/LocalDateTime等），不支持旧的 Date/Calendar；
    • 格式化模式遵循 java.time.format.DateTimeFormatter 规则（如 yyyy=4位年、MM=2位月、dd=2位日、HH=24小时制、hh=12小时制）；
    • 批量处理方法（arrayFormat/listFormat）会遍历数组/集合中的每个时间对象，按相同规则格式化。

3. 句式优化说明 ​

  • 统一补充“（对应 arrayDay/listDay 等方法）”解释注释中的 // also arrayDay(...)，避免重复且清晰；
  • 对时间属性方法补充具体取值范围/含义（如 day(temporal) → 1-31），降低新手理解成本；
  • 明确不同 create 方法返回的具体类型（LocalDate/LocalDateTime），避免“Temporal 抽象类型”的理解盲区；
  • 保留 ${#temporals.xxx} 表达式原样，注释兼顾“参数规则”和“实际效果”，适配模板开发场景。

总结 ​

  1. #temporals 是 Thymeleaf 基于 Java 8+ java.time 的日期时间工具类，覆盖格式化、属性提取、对象创建三大核心场景；
  2. 格式化核心规则：
    • 支持自定义格式模式（遵循 DateTimeFormatter 规范）、Locale、时区、ISO-8601 标准格式；
    • 批量处理数组/列表/集合时，所有元素按相同规则格式化；
  3. 高频扩展用法：
    • 时间属性提取：year/month/day 等方法可单独获取日期时间的某一部分；
    • 字符串转时间：createDate/createDateTime 支持从 ISO 格式/自定义格式字符串创建时间对象；
    • 时区适配：createNowForTimeZone 可生成指定时区的时间对象，解决跨时区展示问题。