Thymeleaf中文网

深色模式

日历工具（Calendars） ​

#calendars：功能与 #dates 类似，但专门用于处理 java.util.Calendar 类型的对象：

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

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

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

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

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

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

${#calendars.createForTimeZone(year,month,day,timeZone)}                // 按指定时区创建仅含日期的 Calendar 实例
${#calendars.createForTimeZone(year,month,day,hour,minute,timeZone)}    // 按指定时区创建含日期+时分的 Calendar 实例
${#calendars.createForTimeZone(year,month,day,hour,minute,second,timeZone)} // 按指定时区创建含日期+时分秒的 Calendar 实例
${#calendars.createForTimeZone(year,month,day,hour,minute,second,millisecond,timeZone)} // 按指定时区创建完整 Calendar 实例

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

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

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

1. 核心术语解析 ​

英文术语译法/说明
Calendars日历工具类（Thymeleaf 针对 Java 旧版 java.util.Calendar/Date 的工具，#calendars 是简写）
calendar日历对象（泛指 java.util.Calendar 或 java.util.Date，工具类会自动兼容）
timeZone时区对象/时区ID（支持 java.util.TimeZone 实例或字符串ID，如 GMT+8/Asia/Shanghai）
millisecond毫秒（区别于 Temporals 的纳秒，Calendar 最高精度为毫秒）
ISO-8601国际标准格式（对 Calendar 格式化后输出 2024-05-20T14:30:00.123，含毫秒）

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

html
<!-- 1. 基础格式化（兼容 Date/Calendar） -->
<div th:with="
  // 模拟后端传入的旧版 Date 对象
  oldDate=${T(java.util.Date).new()},
  // 转为 Calendar 后格式化
  cal=${T(java.util.Calendar).getInstance()},
  _=${cal.setTime(oldDate)}
">
  默认格式：<span th:text="${#calendars.format(cal)}"></span> <!-- 2024-05-20 14:30:00（系统Locale） -->
  自定义格式：<span th:text="${#calendars.format(cal, 'yyyy年MM月dd日 HH:mm:ss')}"></span> <!-- 2024年05月20日 14:30:00 -->
  ISO格式：<span th:text="${#calendars.formatISO(cal)}"></span> <!-- 2024-05-20T14:30:00.123 -->
</div>

<!-- 2. 获取日历属性 -->
<div th:with="cal=${#calendars.create(2024,5,20)}">
  年份：<span th:text="${#calendars.year(cal)}"></span> <!-- 2024 -->
  毫秒数：<span th:text="${#calendars.millisecond(cal)}"></span> <!-- 0（因仅传了年月日） -->
  星期简称：<span th:text="${#calendars.dayOfWeekNameShort(cal)}"></span> <!-- 一（中文Locale） -->
</div>

<!-- 3. 创建指定时区的日历对象 -->
<div th:with="
  shanghaiTZ=${T(java.util.TimeZone).getTimeZone('Asia/Shanghai')},
  shCal=${#calendars.createNowForTimeZone(shanghaiTZ)}
">
  上海时区当前时间：<span th:text="${#calendars.format(shCal, 'yyyy-MM-dd HH:mm')}"></span> <!-- 北京时间 -->
</div>
  • 核心特性：
    • #calendars 是为兼容 Java 8 之前的 Date/Calendar 设计的，推荐优先使用 #temporals（Java 8+ java.time 系列）；
    • 支持直接传入 java.util.Date 对象（工具类会自动转为 Calendar 处理）；
    • 月份参数为1-12（与日常认知一致，区别于 Calendar 原生的 0-11）；
    • 批量处理方法（arrayFormat/listFormat）会遍历数组/集合中的每个 Calendar/Date 对象，按相同规则格式化。

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

特性#calendars（旧版）#temporals（新版）
底层依赖java.util.Calendar/Datejava.time.LocalDate/LocalDateTime 等
最高精度毫秒（millisecond）纳秒（nanosecond）
时区处理依赖 TimeZone 对象依赖 ZoneId 对象，更贴合现代标准
推荐场景兼容老旧项目（Java 7及以下）新项目/Java 8+ 项目（主流推荐）

总结 ​

  1. #calendars 是 Thymeleaf 针对 Java 旧版 Calendar/Date 的日期时间工具类，覆盖格式化、属性提取、对象创建，且兼容 Date 对象；
  2. 核心用法与 #temporals 类似，但精度仅到毫秒，时区依赖 TimeZone，仅推荐用于老旧项目兼容；
  3. 关键注意：
    • 月份参数为 1-12（无需减1），符合日常使用习惯；
    • 新项目优先使用 #temporals（基于 Java 8+ java.time），API 更规范、功能更完善；
    • createNowForTimeZone/timeZone 参数需传入 TimeZone 实例或合法的时区ID字符串（如 Asia/Shanghai）。