Thymeleaf中文网

深色模式

15.3 转换服务 ​

通过双大括号语法（${{...}}）实现数据转换和格式化的「转换服务」，本质上是标准方言（Standard Dialect）的特性，而非 Thymeleaf 模板引擎（Template Engine）本身的功能。

因此，配置该转换服务的方式是：将我们自定义实现的 IStandardConversionService 接口实例，直接设置到正在配置到模板引擎中的 StandardDialect 实例里。示例如下

java
// 1. 自定义转换服务实现类（需实现 IStandardConversionService 接口）
IStandardConversionService customConversionService = new MyCustomConversionService();

// 2. 创建标准方言实例，并绑定自定义转换服务
StandardDialect dialect = new StandardDialect();
dialect.setConversionService(customConversionService);

// 3. 将配置好的方言设置到模板引擎中
templateEngine.setDialect(dialect);

需要注意的是， thymeleaf-spring3 和 thymeleaf-spring4 集成包中提供了 SpringStandardDialect（Spring 专用标准方言），该方言已预置了 IStandardConversionService 的实现——它会自动将 Spring 框架自身的 Conversion Service 基础设施与 Thymeleaf 打通：

  • 无需手动配置转换服务，Spring 配置中声明的转换器（Converter）、格式化器（Formatter）会自动对 ${{...}} 和 *{{...}} 表达式生效；
  • 例如 Spring 中通过 @NumberFormat、@DateTimeFormat 注解配置的格式化规则，或自定义的 Converter<String, LocalDate>，都能直接在 Thymeleaf 双大括号表达式中使用。

核心解析 ​

  1. 归属关系： 转换服务是「方言级」配置，而非「引擎级」——模板引擎仅负责加载方言，数据转换的逻辑由方言中的 IStandardConversionService 实现类处理，这保证了不同方言可拥有独立的转换规则。

  2. 自定义转换服务的适用场景：

    • 非 Spring 项目（纯 Thymeleaf 环境），需自定义数据格式（如将 Calendar 转为指定格式的字符串、将枚举值转为中文描述）；
    • 需覆盖标准方言默认的转换逻辑（默认仅调用 toString()）。

  3. Spring 集成的优势： SpringStandardDialect 无缝复用 Spring 的转换体系，避免了「Thymeleaf 转换规则」和「Spring 业务转换规则」的重复定义，是 Spring Boot + Thymeleaf 项目的默认选择。

总结 ​

  1. 双大括号语法的转换能力由 StandardDialect 的 IStandardConversionService 实现，需配置到方言实例中；
  2. 非 Spring 项目可通过实现 IStandardConversionService 自定义转换逻辑，Spring 项目则可直接使用 SpringStandardDialect 复用 Spring 转换服务；
  3. 核心价值：统一数据转换/格式化规则，让模板中的 ${{...}} 表达式能按业务需求处理日期、数字、自定义对象等数据类型。