Thymeleaf中文网

深色模式

日期工具（Dates） ​

#dates 是 Thymeleaf 标准表达式中专门用于操作 java.util.Date 对象的工具对象，提供了格式化、属性提取、对象创建等一站式方法（底层对应 org.thymeleaf.expression.Dates 类，可参考其 JavaDoc 获取完整 API）。

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

/*
 * 按系统默认的语言环境（Locale）格式化日期对象。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#dates.format(date)}
${#dates.arrayFormat(datesArray)}
${#dates.listFormat(datesList)}
${#dates.setFormat(datesSet)}

/*
 * 按 ISO-8601 标准格式格式化日期对象（如 2024-05-20T14:30:00.123）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#dates.formatISO(date)}
${#dates.arrayFormatISO(datesArray)}
${#dates.listFormatISO(datesList)}
${#dates.setFormatISO(datesSet)}

/*
 * 按指定的自定义格式模式格式化日期对象。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#dates.format(date, 'dd/MMM/yyyy HH:mm')}
${#dates.arrayFormat(datesArray, 'dd/MMM/yyyy HH:mm')}
${#dates.listFormat(datesList, 'dd/MMM/yyyy HH:mm')}
${#dates.setFormat(datesSet, 'dd/MMM/yyyy HH:mm')}

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

/*
 * 从日期时间组件（年/月/日等）创建日期对象（java.util.Date 类型）。
 */
${#dates.create(year,month,day)}                                    // 创建仅含日期的 Date 实例
${#dates.create(year,month,day,hour,minute)}                        // 创建含日期+时分的 Date 实例
${#dates.create(year,month,day,hour,minute,second)}                 // 创建含日期+时分秒的 Date 实例
${#dates.create(year,month,day,hour,minute,second,millisecond)}    // 创建含日期+时分秒毫秒的 Date 实例

/*
 * 创建表示当前系统日期时间的日期对象（java.util.Date 类型）。
 */
${#dates.createNow()}                       // 创建当前系统时区的 Date 实例（含当前时间）
${#dates.createNowForTimeZone(timeZone)}    // 创建指定时区的 Date 实例（含当前时间）

/*
 * 创建表示当前系统日期的日期对象（时间部分设为 00:00:00.000）。
 */
${#dates.createToday()}                     // 创建当前系统时区的 Date 实例（仅日期，时间为0）
${#dates.createTodayForTimeZone(timeZone)}  // 创建指定时区的 Date 实例（仅日期，时间为0）

补充说明（贴合 Thymeleaf 旧版 Date 处理技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
Dates日期工具类（Thymeleaf 针对 Java 旧版 java.util.Date 的专用工具，#dates 是简写）
date日期对象（特指 java.util.Date，是 Java 8 之前的核心日期时间类）
timeZone时区参数（支持 java.util.TimeZone 实例或字符串ID，如 GMT+8/Asia/Shanghai）
ISO-8601国际标准格式（格式化后输出 2024-05-20T14:30:00.123，包含毫秒精度）

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

html
<!-- 1. 基础格式化（直接处理 Date 对象） -->
<div th:with="
  // 创建当前时间的 Date 对象
  nowDate=${#dates.createNow()},
  // 自定义格式格式化
  fmtDate=${#dates.format(nowDate, 'yyyy-MM-dd HH:mm:ss.SSS')}
">
  默认格式：<span th:text="${#dates.format(nowDate)}"></span> <!-- 2024-05-20 14:30:00 -->
  含毫秒格式：<span th:text="${fmtDate}"></span> <!-- 2024-05-20 14:30:00.123 -->
  ISO格式：<span th:text="${#dates.formatISO(nowDate)}"></span> <!-- 2024-05-20T14:30:00.123 -->
</div>

<!-- 2. 从组件创建 Date + 获取属性 -->
<div th:with="
  // 年、月、日创建 Date（月份直接传 5=5月，无需减1）
  customDate=${#dates.create(2024,5,20,10,30,0,500)},
  // 获取各属性
  year=${#dates.year(customDate)},
  ms=${#dates.millisecond(customDate)}
">
  年份：<span th:text="${year}"></span> <!-- 2024 -->
  毫秒数：<span th:text="${ms}"></span> <!-- 500 -->
  星期全称：<span th:text="${#dates.dayOfWeekName(customDate)}"></span> <!-- 星期一 -->
</div>

<!-- 3. 指定时区创建 Date -->
<div th:with="
  // 定义上海时区
  shTZ=${T(java.util.TimeZone).getTimeZone('Asia/Shanghai')},
  // 创建上海时区的今日 Date（时间为0）
  shToday=${#dates.createTodayForTimeZone(shTZ)}
">
  上海时区今日：<span th:text="${#dates.format(shToday, 'yyyy-MM-dd')}"></span> <!-- 2024-05-20 -->
</div>

<!-- 4. 批量处理数组中的 Date -->
<div th:with="
  dateArray=${#arrays.toArray(new java.util.Date[]{#dates.create(2024,1,1), #dates.create(2024,2,1)})},
  // 批量格式化数组
  fmtArray=${#dates.arrayFormat(dateArray, 'yyyy年MM月dd日')}
">
  批量格式化结果：<span th:text="${fmtArray}"></span> <!-- [2024年01月01日, 2024年02月01日] -->
</div>

3. 核心注意点（与 Calendars/Temporals 的区别） ​

特性#dates（Date 专用）#calendars（Calendar 专用）#temporals（Java 8+ 新版）
底层依赖java.util.Datejava.util.Calendar/Datejava.time.LocalDate/LocalDateTime 等
核心定位直接操作 Date 对象封装 Calendar 操作，兼容 Date现代日期时间 API（推荐）
精度毫秒（millisecond）毫秒（millisecond）纳秒（nanosecond）
月份参数1-12（符合日常认知）1-12（封装后）1-12（符合日常认知）
推荐场景仅兼容老旧项目（强依赖 Date）老旧项目（需 Calendar 操作）新项目/Java 8+ 项目（主流）

总结 ​

  1. #dates 是 Thymeleaf 针对 java.util.Date 的专用工具类，核心功能是格式化、属性提取、Date 对象创建，且完全兼容 Date 原生特性；
  2. 核心优势：
    • 直接操作 Date 对象，无需手动转换为 Calendar；
    • 月份参数为 1-12（无需像 Calendar 原生那样减1），符合日常使用习惯；
    • 支持批量处理数组/列表/集合中的 Date 对象；
  3. 关键建议：
    • 新项目优先使用 #temporals（基于 Java 8+ java.time 系列），API 更规范、线程安全；
    • 仅在老旧项目（Java 7及以下、强依赖 Date）中使用 #dates；
    • createNowForTimeZone/createTodayForTimeZone 的 timeZone 参数需传入 TimeZone 实例或合法时区ID字符串。