Thymeleaf中文网

深色模式

17.2 配置解耦模板 ​

启用解耦模板 ​

Thymeleaf 默认不会为所有模板启用「解耦逻辑」（decoupled logic）。相反，你需要在已配置的模板解析器（ITemplateResolver 实现类）中，显式标记其解析的模板启用解耦逻辑。

除了 StringTemplateResolver（该解析器不支持解耦逻辑）之外，Thymeleaf 内置的所有其他 ITemplateResolver 实现类都提供了一个名为 useDecoupledLogic 的开关——开启后，该解析器处理的所有模板都会被标记为：其逻辑的全部或部分可能存储在独立的外部资源文件中。

java
// 创建 Web 应用模板解析器实例
final WebApplicationTemplateResolver templateResolver = 
        new WebApplicationTemplateResolver(application);
// 其他基础配置（如模板模式、前缀/后缀等）
// ...
// 开启解耦逻辑：该解析器解析的所有模板均支持解耦配置
templateResolver.setUseDecoupledLogic(true);

核心解析 ​

1. 解耦模板的核心概念 ​

「解耦模板」是 Thymeleaf 的高级特性：将模板中的 Thymeleaf 逻辑（如 th:text、th:each 等属性）从 HTML 模板文件中抽离，单独存储在外部文件（通常是 .th.xml 或 .th.properties）中。

  • 优势：保持 HTML 文件的「纯静态原型特性」（无任何 Thymeleaf 标记，设计师可直接编辑），逻辑与视图完全分离；
  • 适用场景：需要前端/后端分工协作，且希望 HTML 模板无代码侵入的场景。

2. useDecoupledLogic 开关的作用 ​

  • 该开关是「全局标记」：针对当前解析器处理的所有模板生效，而非单个模板；
  • 开启后，Thymeleaf 解析模板时，会自动查找对应的外部解耦逻辑文件（如 home.html 对应 home.th.xml），并将外部逻辑合并到模板中；
  • 关闭时（默认值），Thymeleaf 仅解析模板文件本身的逻辑，不会读取外部解耦文件。

3. 关键限制 ​

  • StringTemplateResolver 不支持解耦逻辑：因为该解析器处理的是字符串形式的模板（而非文件），无对应的外部资源路径，无法加载解耦逻辑文件；
  • 解耦逻辑文件的路径/命名需遵循 Thymeleaf 约定：通常与模板文件同目录，文件名是「模板名 + .th.xml」（如 /templates/home.html 对应 /templates/home.th.xml）。

总结 ​

  1. 解耦模板需通过模板解析器的 setUseDecoupledLogic(true) 显式启用，默认不开启；
  2. 除 StringTemplateResolver 外，所有内置解析器均支持该开关，开启后解析器处理的模板可加载外部解耦逻辑文件；
  3. 核心价值：实现 Thymeleaf 逻辑与 HTML 模板的物理分离，提升模板的可维护性和原型友好性。