Thymeleaf中文网

深色模式

类型转换工具（Conversions） ​

#conversions：是一个工具对象，允许你在模板的任意位置调用转换服务（Conversion Service） 完成数据类型转换：

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

/*
 * 将指定的 'object' 数值转换为指定的目标类类型。
 */
${#conversions.convert(object, 'java.util.TimeZone')}
${#conversions.convert(object, targetClass)}

补充说明（贴合 Thymeleaf 类型转换技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
Conversions类型转换工具类（Thymeleaf 内置的通用类型转换工具，#conversions 是简写）
convert类型转换（核心方法，基于 Thymeleaf 注册的转换器实现类型转换，支持自定义扩展）
targetClass目标类（可传入类的全限定名字符串，或 Class 类型实例）

2. 关键逻辑解读（实战示例） ​

#conversions.convert 是 Thymeleaf 模板中实现跨类型转换的核心方法，底层依赖 Spring 的 ConversionService（Spring 环境下）或 Thymeleaf 内置转换器，常见用法如下：

html
<!-- 场景1：字符串转 TimeZone（传入类全限定名字符串） -->
<div th:with="
  // 时区ID字符串
  tzStr='Asia/Shanghai',
  // 转换为 TimeZone 对象
  timeZone=${#conversions.convert(tzStr, 'java.util.TimeZone')}
">
  转换后的时区ID：<span th:text="${timeZone.getID()}"></span> <!-- 输出 Asia/Shanghai -->
</div>

<!-- 场景2：字符串转 LocalDate（传入 Class 实例，Java 8+） -->
<div th:with="
  // 日期字符串
  dateStr='2024-05-20',
  // 获取 LocalDate 的 Class 实例
  localDateClass=${T(java.time.LocalDate)},
  // 转换为 LocalDate 对象
  localDate=${#conversions.convert(dateStr, localDateClass)}
">
  转换后的日期：<span th:text="${localDate}"></span> <!-- 输出 2024-05-20 -->
</div>

<!-- 场景3：数字转字符串（基础类型转换） -->
<div th:with="
  num=123,
  str=${#conversions.convert(num, 'java.lang.String')}
">
  数字转字符串：<span th:text="${str} + '_后缀'"></span> <!-- 输出 123_后缀 -->
</div>

3. 核心特性与注意事项 ​

  1. 转换器依赖：
    • 在 Spring Boot 项目中，#conversions 会自动使用 Spring 的 ConversionService，支持 Spring 内置的所有类型转换（如 String→LocalDate、String→TimeZone、Number→String 等）；
    • 非 Spring 环境下，仅支持 Thymeleaf 内置的基础转换器（如 String→基本类型、基本类型→String 等），复杂类型转换（如 String→LocalDate）需手动注册转换器。
  2. 异常处理：
    • 若无法完成转换（如字符串 "abc" 转 Integer），会抛出 ConversionException，建议结合 #objects.nullSafe 做兜底：
      html
      <div th:with="
  invalidStr='abc',
  num=${#objects.nullSafe(#conversions.convert(invalidStr, 'java.lang.Integer'), 0)}
">
  转换失败兜底：<span th:text="${num}"></span> <!-- 输出 0 -->
</div>
  3. 自定义转换器（Spring 环境）： 若内置转换器不满足需求，可自定义 Spring 转换器并注册，示例：
    java
    // 自定义 String → LocalDateTime 转换器
@Configuration
public class ConversionConfig {
    @Bean
    public ConversionService conversionService() {
        DefaultConversionService service = new DefaultConversionService();
        service.addConverter(String.class, LocalDateTime.class, source -> 
            LocalDateTime.parse(source, DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
        return service;
    }
}
    模板中即可直接使用：
    html
    <div th:with="
  dtStr='2024-05-20 14:30:00',
  ldt=${#conversions.convert(dtStr, 'java.time.LocalDateTime')}
">
  自定义转换结果：<span th:text="${ldt}"></span> <!-- 输出 2024-05-20T14:30 -->
</div>

总结 ​

  1. #conversions 是 Thymeleaf 通用类型转换工具类，核心方法 convert(object, targetClass) 支持将任意对象转换为指定类型；
  2. 核心规则：
    • 目标类可传入全限定名字符串（如 'java.util.TimeZone'）或 Class 实例；
    • Spring 环境下依赖 ConversionService，支持丰富的类型转换，非 Spring 环境仅支持基础转换；
  3. 关键建议：
    • 转换前建议做空值/异常兜底，避免转换失败导致页面报错；
    • 复杂类型转换优先通过 Spring 自定义转换器扩展，而非在模板中硬编码。