Thymeleaf中文网

深色模式

15 配置进阶 ​

15.1 模板解析器 ​

在我们的“美好时光虚拟杂货店”项目中，我们选用了 WebApplicationTemplateResolver 这个 ITemplateResolver 接口实现类——它能从应用资源中（基于 Servlet 的 Web 应用中即 Servlet 上下文）读取模板资源。

除了可以通过实现 ITemplateResolver 接口自定义模板解析器外，Thymeleaf 还内置了 4 个开箱即用的实现类：

  1. org.thymeleaf.templateresolver.ClassLoaderTemplateResolver
    从类加载器资源中解析模板，逻辑等价于：

    java
    return Thread.currentThread().getContextClassLoader().getResourceAsStream(template);

  2. org.thymeleaf.templateresolver.FileTemplateResolver
    从文件系统中以文件形式解析模板，逻辑等价于：

    java
    return new FileInputStream(new File(template));

  3. org.thymeleaf.templateresolver.UrlTemplateResolver
    从 URL（甚至非本地 URL）中解析模板，逻辑等价于：

    java
    return (new URL(template)).openStream();

  4. org.thymeleaf.templateresolver.StringTemplateResolver
    直接将传入的字符串作为模板内容解析（此时的“模板名”不再只是名称，而是完整的模板内容），逻辑等价于：

    java
    return new StringReader(templateName);

所有内置的 ITemplateResolver 实现类都支持以下通用配置参数：

1. 前缀和后缀（前文已提及） ​
java
templateResolver.setPrefix("/WEB-INF/templates/"); // 模板文件路径前缀
templateResolver.setSuffix(".html"); // 模板文件后缀
2. 模板别名 ​

允许使用与文件名不直接对应的模板名。若同时配置了前缀/后缀和别名，别名会先生效，再拼接前缀/后缀：

java
// 为 "adminHome" 配置别名，实际指向 profiles/admin/home
templateResolver.addTemplateAlias("adminHome","profiles/admin/home");
// 批量设置别名（传入 Map 集合）
templateResolver.setTemplateAliases(aliasesMap);
3. 模板读取编码 ​
java
templateResolver.setCharacterEncoding("UTF-8");
4. 模板模式 ​
java
// 默认模式为 HTML，可手动指定为 XML 等
templateResolver.setTemplateMode("XML");
5. 模板缓存配置 ​

包括缓存默认开关、以及指定哪些模板需要缓存的匹配规则：

java
// 默认缓存开启（true），此处关闭全局缓存
templateResolver.setCacheable(false);
// 单独指定 /users/* 路径下的模板启用缓存
templateResolver.getCacheablePatternSpec().addPattern("/users/*");
6. 缓存过期时间（TTL） ​

单位为毫秒，用于设置当前解析器生成的模板缓存条目有效期。若未设置，缓存条目仅会在超出缓存最大容量时被移除（移除最久未使用的条目）：

java
// 默认无 TTL，此处设置为 60 秒（60000 毫秒）
templateResolver.setCacheTTLMs(60000L);

INFO

此外，Thymeleaf + Spring 集成包提供了 SpringResourceTemplateResolver 实现类——它基于 Spring 完整的资源访问基础设施读取应用资源，是启用 Spring 的应用中推荐使用的模板解析器。

总结 ​

  1. Thymeleaf 内置 4 种模板解析器（ClassLoader/File/Url/String），分别对应不同的模板资源来源，也支持自定义解析器；
  2. 所有内置解析器均支持前缀/后缀、别名、编码、缓存（开关/规则/TTL）、模板模式等通用配置；
  3. Spring 集成场景下优先使用 SpringResourceTemplateResolver，适配 Spring 资源访问体系。