1.1 什么是 Thymeleaf？

Thymeleaf 是一个适用于 Web 和独立环境的现代服务器端 Java 模板引擎，能够处理 HTML、XML、JavaScript、CSS 甚至纯文本。

Thymeleaf 的主要目标是提供一种优雅且高度可维护的模板创建方式。为了实现这一目标，它以自然模板的概念为基础，将其逻辑注入模板文件，而不会影响模板作为设计原型的使用。这改善了设计沟通并弥合了设计团队和开发团队之间的差距。

Thymeleaf 从一开始就考虑到了 Web 标准（尤其是HTML5），允许您创建完全验证的模板（如果需要）。

1.2 Thymeleaf 可以处理哪些类型的模板？

开箱即用，Thymeleaf 允许您处理六种模板，每种模板称为一种模板模式：

• HTML
• XML
• 文本
• JavaScript
• CSS
• 生的

有两种标记模板模式（HTML和XML），三种文本模板模式（TEXT，JAVASCRIPT和CSS）和一种无操作模板模式（RAW）。

模板HTML模式将允许任何类型的 HTML 输入，包括 HTML5、HTML 4 和 XHTML。不会执行任何验证或格式正确性检查，输出中将最大程度地尊重模板代码/结构。

模板XML模式将允许 XML 输入。在这种情况下，代码应格式正确 - 没有未关闭的标签、没有未加引号的属性等 - 如果发现格式错误，解析器将抛出异常。请注意，不会执行任何验证（针对 DTD 或 XML Schema）。

模板TEXT模式允许使用特殊语法来处理非标记性质的模板。此类模板的示例可能是文本电子邮件或模板化文档。请注意，HTML 或 XML 模板也可以作为 处理TEXT，在这种情况下，它们将不会被解析为标记，并且每个标签、DOCTYPE、注释等都将被视为纯文本。

模板JAVASCRIPT模式将允许在 Thymeleaf 应用程序中处理 JavaScript 文件。这意味着能够以与在 HTML 文件中相同的方式在 JavaScript 文件中使用模型数据，但具有 JavaScript 特定的集成，例如专门的转义或自然脚本。JAVASCRIPT模板模式被视为文本模式，因此使用与模板模式相同的特殊语法TEXT。

模板CSS模式将允许处理 Thymeleaf 应用程序中涉及的 CSS 文件。与该JAVASCRIPT模式类似，CSS模板模式也是一种文本模式，并使用来自模板模式的特殊处理语法TEXT。

模板RAW模式根本不会处理模板。它旨在用于将未触及的资源（文件、URL 响应等）插入正在处理的模板中。例如，HTML 格式的外部、不受控制的资源可以包含在应用程序模板中，并且可以放心地知道这些资源可能包含的任何 Thymeleaf 代码都不会被执行。

1.3 方言：标准方言

Thymeleaf 是一个极具扩展性的模板引擎（事实上它可以被称为模板引擎框架），它允许您定义和自定义模板处理方式的精细程度。

将某种逻辑应用于标记工件（标签、文本、注释或模板不是标记时的占位符）的对象称为处理器，方言通常由一组这样的处理器（可能还有一些额外的工件）组成。Thymeleaf 的核心库开箱即用地提供了一种称为标准方言的方言，这对大多数用户来说应该足够了。

请注意，方言实际上可以没有处理器，而完全由其他类型的工件组成，但处理器绝对是最常见的用例。

本教程涵盖了标准方言。您将在以下页面中了解的每个属性和语法特性都是由此方言定义的，即使没有明确提及。

当然，如果用户想定义自己的处理逻辑并利用该库的高级功能，他们可以创建自己的方言（甚至扩展标准方言）。Thymeleaf 还可以配置为同时使用多种方言。

官方的 thymeleaf-spring3 和 thymeleaf-spring4 集成包都定义了一种称为“SpringStandard Dialect”的方言，它与标准方言基本相同，但略有改动，以便更好地利用 Spring Framework 中的某些功能（例如，使用 Spring Expression Language 或 SpringEL 代替 OGNL）。因此，如果您是 Spring MVC 用户，那么您不会浪费时间，因为您在这里学到的几乎所有内容都将在您的 Spring 应用程序中派上用场。

标准方言的大多数处理器都是属性处理器。这使得浏览器即使在处理之前也能正确显示 HTML 模板文件，因为它们会忽略附加属性。例如，虽然使用标记库的 JSP 可能包含浏览器无法直接显示的代码片段，例如：

<form:inputText name="userName" value="${user.name}" />

...Thymeleaf 标准方言允许我们通过以下方式实现相同的功能：

<input type="text" name="userName" value="James Carrot" th:value="${user.name}" />

这不仅能被浏览器正确显示，而且这还允许我们（可选）在其中指定一个值属性（在本例中为“James Carrot”），当原型在浏览器中静态打开时将显示该值，并且该值将由在${user.name}处理模板期间评估的结果替换。

这可帮助您的设计师和开发人员处理同一个模板文件，并减少将静态原型转换为工作模板文件所需的工作量。实现此功能的功能称为“自然模板化”。

2.1 一家杂货店的网站

为了更好地解释使用 Thymeleaf 处理模板所涉及的概念，本教程将使用一个演示应用程序，您可以从项目网站下载。

该应用程序是一个虚构的虚拟杂货店的网站，将为我们提供许多场景来展示 Thymeleaf 的众多功能。

首先，我们需要为我们的应用程序创建一组简单的模型实体：通过创建Products出售给。我们还将管理这些：CustomersOrdersCommentsProducts

我们的应用程序还将有一个非常简单的服务层，由Service包含以下方法的对象组成：

public class ProductService {

    ...

    public List<Product> findAll() {
        return ProductRepository.getInstance().findAll();
    }

    public Product findById(Integer id) {
        return ProductRepository.getInstance().findById(id);
    }
    
}

在 Web 层，我们的应用程序将有一个过滤器，该过滤器将根据请求 URL 将执行委托给启用 Thymeleaf 的命令：

private boolean process(HttpServletRequest request, HttpServletResponse response)
        throws ServletException {
    
    try {

        // This prevents triggering engine executions for resource URLs
        if (request.getRequestURI().startsWith("/css") ||
                request.getRequestURI().startsWith("/images") ||
                request.getRequestURI().startsWith("/favicon")) {
            return false;
        }

        
        /*
         * Query controller/URL mapping and obtain the controller
         * that will process the request. If no controller is available,
         * return false and let other filters/servlets process the request.
         */
        IGTVGController controller = this.application.resolveControllerForRequest(request);
        if (controller == null) {
            return false;
        }

        /*
         * Obtain the TemplateEngine instance.
         */
        ITemplateEngine templateEngine = this.application.getTemplateEngine();

        /*
         * Write the response headers
         */
        response.setContentType("text/html;charset=UTF-8");
        response.setHeader("Pragma", "no-cache");
        response.setHeader("Cache-Control", "no-cache");
        response.setDateHeader("Expires", 0);

        /*
         * Execute the controller and process view template,
         * writing the results to the response writer. 
         */
        controller.process(
                request, response, this.servletContext, templateEngine);
        
        return true;
        
    } catch (Exception e) {
        try {
            response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
        } catch (final IOException ignored) {
            // Just ignore this
        }
        throw new ServletException(e);
    }
    
}

这是我们的IGTVGController界面：

public interface IGTVGController {

    public void process(
            HttpServletRequest request, HttpServletResponse response,
            ServletContext servletContext, ITemplateEngine templateEngine);    
    
}

我们现在要做的就是创建IGTVGController接口的实现，从服务中检索数据并使用ITemplateEngine对象处理模板。

最后它看起来会像这样：

但首先让我们看看该模板引擎是如何初始化的。

2.2 创建并配置模板引擎

我们的过滤器中的process(…)方法包含以下行：

ITemplateEngine templateEngine = this.application.getTemplateEngine();

这意味着GTVGApplication类负责创建和配置 Thymeleaf 应用程序中最重要的对象之一：TemplateEngine实例（接口的实现ITemplateEngine）。

我们的org.thymeleaf.TemplateEngine对象初始化如下：

public class GTVGApplication {
  
    
    ...
    private final TemplateEngine templateEngine;
    ...
    
    
    public GTVGApplication(final ServletContext servletContext) {

        super();

        ServletContextTemplateResolver templateResolver = 
                new ServletContextTemplateResolver(servletContext);
        
        // HTML is the default mode, but we set it anyway for better understanding of code
        templateResolver.setTemplateMode(TemplateMode.HTML);
        // This will convert "home" to "/WEB-INF/templates/home.html"
        templateResolver.setPrefix("/WEB-INF/templates/");
        templateResolver.setSuffix(".html");
        // Template cache TTL=1h. If not set, entries would be cached until expelled
        templateResolver.setCacheTTLMs(Long.valueOf(3600000L));
        
        // Cache is set to true by default. Set to false if you want templates to
        // be automatically updated when modified.
        templateResolver.setCacheable(true);
        
        this.templateEngine = new TemplateEngine();
        this.templateEngine.setTemplateResolver(templateResolver);
        
        ...

    }

}

配置对象的方法有很多种TemplateEngine，但是现在这几行代码就足以让我们了解所需的步骤。

ServletContextTemplateResolver templateResolver = 
        new ServletContextTemplateResolver(servletContext);

public interface ITemplateResolver {

    ...
  
    /*
     * Templates are resolved by their name (or content) and also (optionally) their 
     * owner template in case we are trying to resolve a fragment for another template.
     * Will return null if template cannot be handled by this template resolver.
     */
    public TemplateResolution resolveTemplate(
            final IEngineConfiguration configuration,
            final String ownerTemplate, final String template,
            final Map<String, Object> templateResolutionAttributes);
}

templateResolver.setTemplateMode(TemplateMode.HTML);

templateResolver.setPrefix("/WEB-INF/templates/");
templateResolver.setSuffix(".html");

servletContext.getResourceAsStream("/WEB-INF/templates/product/list.html")

templateResolver.setCacheTTLMs(3600000L);

templateEngine = new TemplateEngine();
templateEngine.setTemplateResolver(templateResolver);

3.1 多语言欢迎

我们的首要任务是为我们的杂货网站创建一个主页。

此页面的第一个版本非常简单：只有一个标题和一条欢迎信息。这是我们的/WEB-INF/templates/home.html文件：

<!DOCTYPE html>

<html xmlns:th="http://www.thymeleaf.org">

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" media="all" 
          href="../../css/gtvg.css" th:href="@{/css/gtvg.css}" />
  </head>

  <body>
  
    <p th:text="#{home.welcome}">Welcome to our grocery store!</p>
  
  </body>

</html>

您首先会注意到的是，该文件是 HTML5，可以被任何浏览器正确显示，因为它不包含任何非 HTML 标签（浏览器会忽略它们不理解的所有属性，例如th:text）。

但您可能还注意到，此模板实际上并不是有效的HTML5 文档，因为我们在表单中使用的这些非标准属性th:*不符合 HTML5 规范。事实上，我们甚至xmlns:th在标签中添加了一个属性<html>，这完全不符合 HTML5 规范：

<html xmlns:th="http://www.thymeleaf.org">

...这对模板处理完全没有影响，但可以起到咒语的作用，防止我们的 IDE 抱怨所有这些属性缺少命名空间定义th:*。

那么如果我们想让这个模板符合 HTML5 规范该怎么做呢？很简单：切换到 Thymeleaf 的数据属性语法，使用data-属性名称的前缀和连字符 ( -) 分隔符代替分号 ( :)：

<!DOCTYPE html>

<html>

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" media="all" 
          href="../../css/gtvg.css" data-th-href="@{/css/gtvg.css}" />
  </head>

  <body>
  
    <p data-th-text="#{home.welcome}">Welcome to our grocery store!</p>
  
  </body>

</html>

HTML5 规范允许使用自定义data-前缀属性，因此，通过上述代码，我们的模板将是有效的 HTML5 文档。

这两种符号完全等价且可以互换，但为了代码示例的简单和紧凑，本教程将使用命名空间符号（th:*）。此外，该th:*符号更通用，允许在每个 Thymeleaf 模板模式中使用（XML，TEXT...），而data-符号仅允许在HTML模式下使用。

<p th:text="#{home.welcome}">Welcome to our grocery store!</p>

home.welcome=¡Bienvenido a nuestra tienda de comestibles!

public class HomeController implements IGTVGController {

    public void process(
            final HttpServletRequest request, final HttpServletResponse response,
            final ServletContext servletContext, final ITemplateEngine templateEngine)
            throws Exception {
        
        WebContext ctx = 
                new WebContext(request, response, servletContext, request.getLocale());
        
        templateEngine.process("home", ctx, response.getWriter());
        
    }

}

public interface IContext {

    public Locale getLocale();
    public boolean containsVariable(final String name);
    public Set<String> getVariableNames();
    public Object getVariable(final String name);
    
}

public interface IWebContext extends IContext {
    
    public HttpServletRequest getRequest();
    public HttpServletResponse getResponse();
    public HttpSession getSession();
    public ServletContext getServletContext();
    
}

WebContext ctx = new WebContext(request, response, servletContext, request.getLocale());

templateEngine.process("home", ctx, response.getWriter());

<!DOCTYPE html>

<html>

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
    <link rel="stylesheet" type="text/css" media="all" href="/gtvg/css/gtvg.css" />
  </head>

  <body>
  
    <p>¡Bienvenido a nuestra tienda de comestibles!</p>

  </body>

</html>

3.2 有关文本和变量的更多信息

home.welcome=Welcome to our <b>fantastic</b> grocery store!

<p>Welcome to our &lt;b&gt;fantastic&lt;/b&gt; grocery store!</p>

<p th:utext="#{home.welcome}">Welcome to our grocery store!</p>

<p>Welcome to our <b>fantastic</b> grocery store!</p>

Welcome to our fantastic grocery store!

Today is: 12 july 2010

public void process(
            final HttpServletRequest request, final HttpServletResponse response,
            final ServletContext servletContext, final ITemplateEngine templateEngine)
            throws Exception {
        
    SimpleDateFormat dateFormat = new SimpleDateFormat("dd MMMM yyyy");
    Calendar cal = Calendar.getInstance();
        
    WebContext ctx = 
            new WebContext(request, response, servletContext, request.getLocale());
    ctx.setVariable("today", dateFormat.format(cal.getTime()));
        
    templateEngine.process("home", ctx, response.getWriter());
        
}

<body>

  <p th:utext="#{home.welcome}">Welcome to our grocery store!</p>

  <p>Today is: <span th:text="${today}">13 February 2011</span></p>
  
</body>

4.1 消息

我们已经知道，#{...}消息表达式允许我们链接以下内容：

<p th:utext="#{home.welcome}">Welcome to our grocery store!</p>

…变成这样：

home.welcome=¡Bienvenido a nuestra tienda de comestibles!

但有一个方面我们还没有想到：如果消息文本不是完全静态的，会发生什么？例如，如果我们的应用程序随时知道谁是访问网站的用户，而我们想通过名字来问候他们，该怎么办？

<p>¡Bienvenido a nuestra tienda de comestibles, John Apricot!</p>

这意味着我们需要在消息中添加一个参数。就像这样：

home.welcome=¡Bienvenido a nuestra tienda de comestibles, {0}!

参数是根据java.text.MessageFormat标准语法指定，这意味着您可以按照包中类的 API 文档中指定的方式将其格式化为数字和日期java.text.*。

为了为我们的参数指定一个值，并给出一个名为的 HTTP 会话属性user，我们可以：

<p th:utext="#{home.welcome(${session.user.name})}">
  Welcome to our grocery store, Sebastian Pepper!
</p>

注意，这里使用th:utext表示格式化的消息不会被转义。此示例假设user.name已经转义。

可以指定多个参数，以逗号分隔。

消息键本身可以来自变量：

<p th:utext="#{${welcomeMsgKey}(${session.user.name})}">
  Welcome to our grocery store, Sebastian Pepper!
</p>

4.2 变量

我们已经提到，${...}表达式实际上是在上下文中包含的变量映射上执行的 OGNL（对象图导航语言）表达式。

有关 OGNL 语法和功能的详细信息，你应该阅读OGNL 语言指南

在支持 Spring MVC 的应用程序中，OGNL 将被SpringEL取代，但其语法与 OGNL 非常相似（实际上，对于大多数常见情况而言完全相同）。

从OGNL的语法中，我们知道表达式：

<p>Today is: <span th:text="${today}">13 february 2011</span>.</p>

…实际上相当于这样：

ctx.getVariable("today");

但是 OGNL 允许我们创建更强大的表达式，例如：

<p th:utext="#{home.welcome(${session.user.name})}">
  Welcome to our grocery store, Sebastian Pepper!
</p>

...通过执行以下命令获取用户名：

((User) ctx.getVariable("session").get("user")).getName();

但是 getter 方法导航只是 OGNL 的功能之一。让我们看看更多：

/*
 * Access to properties using the point (.). Equivalent to calling property getters.
 */
${person.father.name}

/*
 * Access to properties can also be made by using brackets ([]) and writing 
 * the name of the property as a variable or between single quotes.
 */
${person['father']['name']}

/*
 * If the object is a map, both dot and bracket syntax will be equivalent to 
 * executing a call on its get(...) method.
 */
${countriesByCode.ES}
${personsByName['Stephen Zucchini'].age}

/*
 * Indexed access to arrays or collections is also performed with brackets, 
 * writing the index without quotes.
 */
${personsArray[0].name}

/*
 * Methods can be called, even with arguments.
 */
${person.createCompleteName()}
${person.createCompleteNameWithSeparator('-')}

Established locale country: <span th:text="${#locale.country}">US</span>.

SimpleDateFormat dateFormat = new SimpleDateFormat("dd MMMM yyyy");
Calendar cal = Calendar.getInstance();

WebContext ctx = new WebContext(request, servletContext, request.getLocale());
ctx.setVariable("today", dateFormat.format(cal.getTime()));

templateEngine.process("home", ctx, response.getWriter());

WebContext ctx = 
    new WebContext(request, response, servletContext, request.getLocale());
ctx.setVariable("today", Calendar.getInstance());

templateEngine.process("home", ctx, response.getWriter());

<p>
  Today is: <span th:text="${#calendars.format(today,'dd MMMM yyyy')}">13 May 2011</span>
</p>

4.3 选择表达式（星号语法）

变量表达式不仅可以写成${...}，还可以写成*{...}。

但有一个重要的区别：星号语法对选定对象而不是整个上下文进行表达式求值。也就是说，只要没有选定对象，美元和星号语法的作用完全相同。

那么选定对象是什么？使用属性的表达式的结果th:object。让我们在用户资料 ( userprofile.html) 页面中使用一个：

  <div th:object="${session.user}">
    <p>Name: <span th:text="*{firstName}">Sebastian</span>.</p>
    <p>Surname: <span th:text="*{lastName}">Pepper</span>.</p>
    <p>Nationality: <span th:text="*{nationality}">Saturn</span>.</p>
  </div>

这完全等同于：

<div>
  <p>Name: <span th:text="${session.user.firstName}">Sebastian</span>.</p>
  <p>Surname: <span th:text="${session.user.lastName}">Pepper</span>.</p>
  <p>Nationality: <span th:text="${session.user.nationality}">Saturn</span>.</p>
</div>

当然，美元和星号语法可以混合使用：

<div th:object="${session.user}">
  <p>Name: <span th:text="*{firstName}">Sebastian</span>.</p>
  <p>Surname: <span th:text="${session.user.lastName}">Pepper</span>.</p>
  <p>Nationality: <span th:text="*{nationality}">Saturn</span>.</p>
</div>

当选择对象时，所选对象也将作为#object表达式变量用于美元表达式：

<div th:object="${session.user}">
  <p>Name: <span th:text="${#object.firstName}">Sebastian</span>.</p>
  <p>Surname: <span th:text="${session.user.lastName}">Pepper</span>.</p>
  <p>Nationality: <span th:text="*{nationality}">Saturn</span>.</p>
</div>

如上所述，如果没有执行对象选择，则美元和星号语法是等效的。

<div>
  <p>Name: <span th:text="*{session.user.name}">Sebastian</span>.</p>
  <p>Surname: <span th:text="*{session.user.surname}">Pepper</span>.</p>
  <p>Nationality: <span th:text="*{session.user.nationality}">Saturn</span>.</p>
</div>

4.4 链接 URL

由于其重要性，URL 是 Web 应用程序模板中的一等公民，并且Thymeleaf 标准方言对它们有一种特殊的语法，@语法为：@{...}

URL 有多种类型：

• 绝对 URL：http://www.thymeleaf.org
• 相对 URL，可以是：
  • 页面相关：user/login.html
  • 上下文相关：（/itemdetails?id=3服务器中的上下文名称将自动添加）
  • 服务器相关：（~/billing/processInvoice允许在同一服务器中调用另一个上下文（=应用程序）中的 URL。
  • 协议相对 URL：//code.jquery.com/jquery-2.0.3.min.js

这些表达式的实际处理及其向将要输出的 URL 的转换是通过org.thymeleaf.linkbuilder.ILinkBuilder注册到ITemplateEngine正在使用的对象中的接口的实现来完成的。

默认情况下，该类只注册了一个此接口的实现org.thymeleaf.linkbuilder.StandardLinkBuilder，这对于离线（非 Web）和基于 Servlet API 的 Web 场景来说已经足够了。其他场景（如与非 ServletAPI Web 框架集成）可能需要链接生成器接口的特定实现。

让我们使用这个新语法。了解一下th:href属性：

<!-- Will produce 'http://localhost:8080/gtvg/order/details?orderId=3' (plus rewriting) -->
<a href="details.html" 
   th:href="@{http://localhost:8080/gtvg/order/details(orderId=${o.id})}">view</a>

<!-- Will produce '/gtvg/order/details?orderId=3' (plus rewriting) -->
<a href="details.html" th:href="@{/order/details(orderId=${o.id})}">view</a>

<!-- Will produce '/gtvg/order/3/details' (plus rewriting) -->
<a href="details.html" th:href="@{/order/{orderId}/details(orderId=${o.id})}">view</a>

这里需要注意以下几点：

• th:href是一个修饰属性：一旦处理，它将计算要使用的链接 URL 并将该值设置为标签href的属性<a>。
• 我们可以使用表达式来表示 URL 参数（如 所示orderId=${o.id}）。所需的 URL 参数编码操作也将自动执行。
• 如果需要多个参数，这些参数将用逗号分隔：@{/order/process(execId=${execId},execType='FAST')}
• URL 路径中也允许使用变量模板：@{/order/{orderId}/details(orderId=${orderId})}
• /以（例如： ）开头的相对 URL/order/details将自动以应用程序上下文名称作为前缀。
• 如果未启用 cookie 或者尚不清楚这一点，";jsessionid=..."则可能会将后缀添加到相对 URL 中，以便保留会话。这称为URL 重写response.encodeURL(...)，Thymeleaf 允许您使用Servlet API 中的机制为每个 URL插入自己的重写过滤器。
• 该th:href属性允许我们（可选）href在模板中拥有一个有效的静态属性，以便我们的模板链接在为原型目的直接打开时仍然可以通过浏览器导航。

与消息语法 () 的情况一样#{...}，URL 基础也可以是评估另一个表达式的结果：

<a th:href="@{${url}(orderId=${o.id})}">view</a>
<a th:href="@{'/details/'+${user.login}(orderId=${o.id})}">view</a>

<p>Please select an option</p>
<ol>
  <li><a href="product/list.html" th:href="@{/product/list}">Product List</a></li>
  <li><a href="order/list.html" th:href="@{/order/list}">Order List</a></li>
  <li><a href="subscribe.html" th:href="@{/subscribe}">Subscribe to our Newsletter</a></li>
  <li><a href="userprofile.html" th:href="@{/userprofile}">See User Profile</a></li>
</ol>

4.5 片段

片段表达式是一种表示标记片段并在模板中移动它们的简单方法。这使我们能够复制它们、将它们作为参数传递给其他模板等等。

最常见的用途是使用th:insert或插入片段th:replace（更多内容请参阅后面的部分）：

<div th:insert="~{commons :: main}">...</div>

但它们可以在任何地方使用，就像任何其他变量一样：

<div th:with="frag=~{footer :: #main/text()}">
  <p th:insert="${frag}">
</div>

本教程的后面有一整节专门介绍模板布局，包括对片段表达式的更深入的解释。

4.6 文字

<p>
  Now you are looking at a <span th:text="'working web application'">template file</span>.
</p>

<p>The year is <span th:text="2013">1492</span>.</p>
<p>In two years, it will be <span th:text="2013 + 2">1494</span>.</p>

<div th:if="${user.isAdmin()} == false"> ...

<div th:if="${user.isAdmin() == false}"> ...

<div th:if="${variable.something} == null"> ...

<div th:class="content">...</div>

<div th:class="'content'">...</div>

4.7 附加文本

文本，无论它们是文字还是评估变量或消息表达式的结果，都可以使用+运算符轻松附加：

<span th:text="'The name of the user is ' + ${user.name}">

4.8 文字替换

文字替换允许轻松格式化包含变量值的字符串，而无需在文字后附加'...' + '...'。

这些替换必须用竖线 ( |) 包围，例如：

<span th:text="|Welcome to our application, ${user.name}!|">

这相当于：

<span th:text="'Welcome to our application, ' + ${user.name} + '!'">

文字替换可以与其他类型的表达式结合使用：

<span th:text="${onevar} + ' ' + |${twovar}, ${threevar}|">

文字替换中仅允许使用变量/消息表达式（${...}、*{...}、 ） 。不允许使用其他文字（）、布尔/数字标记、条件表达式等。#{...}|...|'...'

4.9 算术运算

还可以进行一些算术运算：+，，，和-。*/%

<div th:with="isEven=(${prodStat.count} % 2 == 0)">

请注意，这些运算符也可以在 OGNL 变量表达式内部应用（在这种情况下将由 OGNL 而不是 Thymeleaf 标准表达式引擎执行）：

<div th:with="isEven=${prodStat.count % 2 == 0}">

请注意，其中一些运算符存在文本别名：div( /)、mod( %)。

4.10 比较器和相等性

>表达式中的值可以用、和符号进行比较，并且可以使用and运算符来检查是否相等（或不相等）。请注意，XML 规定<不应在属性值中使用and符号，因此应将其替换为and 。>=<===!=<>&lt;&gt;

<div th:if="${prodStat.count} &gt; 1">
<span th:text="'Execution mode is ' + ( (${execMode} == 'dev')? 'Development' : 'Production')">

一种更简单的替代方法可能是使用以下某些运算符的文本别名：gt( >)、lt( <)、ge( >=)、le( <=)、not( !)。还有eq( ==)、neq/ ne( !=)。

4.11 条件表达式

条件表达式旨在根据评估条件（本身是另一个表达式）的结果仅评估两个表达式中的一个。

我们来看一个示例片段（引入另一个属性修饰符, th:class）：

<tr th:class="${row.even}? 'even' : 'odd'">
  ...
</tr>

条件表达式的所有三个部分（condition、then和else）本身都是表达式，这意味着它们可以是变量（${...}、*{...}）、消息（#{...}）、URL（@{...}）或文字（'...'）。

条件表达式也可以使用括号嵌套：

<tr th:class="${row.even}? (${row.first}? 'first' : 'even') : 'odd'">
  ...
</tr>

Else 表达式也可以省略，在这种情况下，如果条件为假，则返回空值：

<tr th:class="${row.even}? 'alt'">
  ...
</tr>

4.12 默认表达式（Elvis 运算符）

默认表达式是一种特殊的条件值，没有then部分。它相当于某些语言（如 Groovy）中的Elvis 运算符，允许您指定两个表达式：如果结果不为空，则使用第一个表达式；如果结果为空，则使用第二个表达式。

让我们在用户资料页面中看看它的实际运行情况：

<div th:object="${session.user}">
  ...
  <p>Age: <span th:text="*{age}?: '(no age specified)'">27</span>.</p>
</div>

如您所见，运算符为?:，我们在此使用它来指定名称的默认值（在本例中为文字值），仅当评估结果*{age}为空时才使用。因此，这相当于：

<p>Age: <span th:text="*{age != null}? *{age} : '(no age specified)'">27</span>.</p>

与条件值一样，它们可以在括号之间包含嵌套表达式：

<p>
  Name: 
  <span th:text="*{firstName}?: (*{admin}? 'Admin' : #{default.username})">Sebastian</span>
</p>

4.13 无操作标记

无操作标记用下划线符号 ( _) 表示。

此标记背后的想法是指定表达式的期望结果是不执行任何操作，即，就像可处理属性（例如th:text）根本不存在一样。

除其他可能性外，这允许开发人员使用原型文本作为默认值。例如，而不是：

<span th:text="${user.name} ?: 'no user authenticated'">...</span>

...我们可以直接使用“未对用户进行身份验证”作为原型文本，这样从设计的角度来看代码会更加简洁和通用：

<span th:text="${user.name} ?: _">no user authenticated</span>

4.14 数据转换/格式化

Thymeleaf defines a double-brace syntax for variable (${...}) and selection (*{...}) expressions that allows us to apply data conversion by means of a configured conversion service.

It basically goes like this:

<td th:text="${{user.lastAccessDate}}">...</td>

Noticed the double brace there?: ${{...}}. That instructs Thymeleaf to pass the result of the user.lastAccessDate expression to the conversion service and asks it to perform a formatting operation (a conversion to String) before writing the result.

Assuming that user.lastAccessDate is of type java.util.Calendar, if a conversion service (implementation of IStandardConversionService) has been registered and contains a valid conversion for Calendar -> String, it will be applied.

The default implementation of IStandardConversionService (the StandardConversionService class) simply executes .toString() on any object converted to String. For more information on how to register a custom conversion service implementation, have a look at the More on Configuration section.

The official thymeleaf-spring3 and thymeleaf-spring4 integration packages transparently integrate Thymeleaf’s conversion service mechanism with Spring’s own Conversion Service infrastructure, so that conversion services and formatters declared in the Spring configuration will be made automatically available to ${{...}} and *{{...}} expressions.

4.15 Preprocessing

In addition to all these features for expression processing, Thymeleaf has the feature of preprocessing expressions.

Preprocessing is an execution of the expressions done before the normal one that allows for modification of the expression that will eventually be executed.

Preprocessed expressions are exactly like normal ones, but appear surrounded by a double underscore symbol (like __${expression}__).

Let’s imagine we have an i18n Messages_fr.properties entry containing an OGNL expression calling a language-specific static method, like:

article.text=@myapp.translator.Translator@translateToFrench({0})

…and a Messages_es.properties equivalent:

article.text=@myapp.translator.Translator@translateToSpanish({0})

We can create a fragment of markup that evaluates one expression or the other depending on the locale. For this, we will first select the expression (by preprocessing) and then let Thymeleaf execute it:

<p th:text="${__#{article.text('textVar')}__}">Some text here...</p>

Note that the preprocessing step for a French locale will be creating the following equivalent:

<p th:text="${@myapp.translator.Translator@translateToFrench(textVar)}">Some text here...</p>

The preprocessing String __ can be escaped in attributes using \_\_.

5.1 Setting the value of any attribute

Say our website publishes a newsletter, and we want our users to be able to subscribe to it, so we create a /WEB-INF/templates/subscribe.html template with a form:

<form action="subscribe.html">
  <fieldset>
    <input type="text" name="email" />
    <input type="submit" value="Subscribe!" />
  </fieldset>
</form>

与 Thymeleaf 一样，此模板一开始更像是静态原型，而不是 Web 应用程序的模板。首先，action表单中的属性静态链接到模板文件本身，因此没有地方进行有用的 URL 重写。其次，value提交按钮中的属性使其显示英文文本，但我们希望它能够国际化。

然后输入th:attr属性，以及它改变所设置标签的属性值的能力：

<form action="subscribe.html" th:attr="action=@{/subscribe}">
  <fieldset>
    <input type="text" name="email" />
    <input type="submit" value="Subscribe!" th:attr="value=#{subscribe.submit}"/>
  </fieldset>
</form>

这个概念很简单：th:attr只需采用一个将值分配给属性的表达式。创建相应的控制器和消息文件后，处理此文件的结果将是：

<form action="/gtvg/subscribe">
  <fieldset>
    <input type="text" name="email" />
    <input type="submit" value="¡Suscríbe!"/>
  </fieldset>
</form>

除了新的属性值之外，您还可以看到应用程序上下文名称已自动添加到 URL 基础的前缀/gtvg/subscribe，如上一章所述。

但是如果我们想一次设置多个属性怎么办？ XML 规则不允许在标签中两次设置属性，因此th:attr将采用逗号分隔的分配列表，例如：

<img src="../../images/gtvglogo.png" 
     th:attr="src=@{/images/gtvglogo.png},title=#{logo},alt=#{logo}" />

给定所需的消息文件，这将输出：

<img src="/gtgv/images/gtvglogo.png" title="Logo de Good Thymes" alt="Logo de Good Thymes" />

5.2 设置特定属性的值

现在，你可能会想：

<input type="submit" value="Subscribe!" th:attr="value=#{subscribe.submit}"/>

…是一段相当丑陋的标记。在属性值中指定赋值可能非常实用，但如果您必须一直这样做，那么这不是创建模板的最优雅的方式。

Thymeleaf 同意你的观点，这就是为什么th:attr在模板中很少使用的原因。通常，你会使用其他th:*属性，其任务是设置特定的标签属性（而不仅仅是像这样的任何属性th:attr）。

例如，要设置value属性，请使用th:value：

<input type="submit" value="Subscribe!" th:value="#{subscribe.submit}"/>

这看起来好多了！让我们尝试对标签action中的属性执行相同的操作form：

<form action="subscribe.html" th:action="@{/subscribe}">

你还记得th:href我们home.html之前添加的那些吗？它们正是这种类型的属性：

<li><a href="product/list.html" th:href="@{/product/list}">Product List</a></li>

有很多这样的属性，每个属性都针对特定的 HTML5 属性：

5.3 一次设置多个值

有两个相当特殊的属性称为th:alt-title和，th:lang-xmllang它们可用于同时将两个属性设置为相同的值。具体来说：

• th:alt-title将设置alt和title。
• th:lang-xmllang将设置lang和xml:lang。

对于我们的 GTVG 主页，我们可以用以下方法替换：

<img src="../../images/gtvglogo.png" 
     th:attr="src=@{/images/gtvglogo.png},title=#{logo},alt=#{logo}" />

...或者这个，等效于：

<img src="../../images/gtvglogo.png" 
     th:src="@{/images/gtvglogo.png}" th:title="#{logo}" th:alt="#{logo}" />

…有了这个：

<img src="../../images/gtvglogo.png" 
     th:src="@{/images/gtvglogo.png}" th:alt-title="#{logo}" />

5.4 附加和前置

Thymeleaf 还提供th:attrappend和th:attrprepend属性，将其评估结果附加（后缀）或添加到现有属性值之前（前缀）。

例如，您可能希望将要添加（不是设置，只是添加）到上下文变量中的一个按钮的 CSS 类的名称存储起来，因为要使用的特定 CSS 类取决于用户之前所做的事情：

<input type="button" value="Do it!" class="btn" th:attrappend="class=${' ' + cssStyle}" />

如果你将cssStyle变量设置为 来处理此模板"warning"，你将得到：

<input type="button" value="Do it!" class="btn warning" />

标准方言中还有两个特定的附加属性th:classappend：和th:styleappend属性，用于向元素添加 CSS 类或样式片段而不覆盖现有的：

<tr th:each="prod : ${prods}" class="row" th:classappend="${prodStat.odd}? 'odd'">

（不要担心该th:each属性。它是一个迭代属性，我们稍后会讨论它。）

5.5 固定值布尔属性

HTML 有布尔属性的概念，即没有值的属性，如果存在一个值则表示值为“真”。在 XHTML 中，这些属性只接受 1 个值，即其本身。

例如，checked：

<input type="checkbox" name="option2" checked /> <!-- HTML -->
<input type="checkbox" name="option1" checked="checked" /> <!-- XHTML -->

标准方言包含一些属性，允许您通过评估条件来设置这些属性，因此，如果评估结果为 true，则该属性将设置为其固定值，如果评估结果为 false，则不会设置该属性：

<input type="checkbox" name="active" th:checked="${user.active}" />

标准方言中存在以下固定值布尔属性：

5.6 设置任意属性的值（默认属性处理器）

Thymeleaf 提供了一个默认的属性处理器，允许我们设置任何属性的值，即使th:*在标准方言中没有为其定义特定的处理器。

因此类似于：

<span th:whatever="${user.name}">...</span>

将导致：

<span whatever="John Apricot">...</span>

5.7 支持 HTML5 友好的属性和元素名称

还可以使用完全不同的语法以更加 HTML5 友好的方式将处理器应用于模板。

<table>
    <tr data-th-each="user : ${users}">
        <td data-th-text="${user.login}">...</td>
        <td data-th-text="${user.name}">...</td>
    </tr>
</table>

该data-{prefix}-{name}语法是在 HTML5 中编写自定义属性的标准方法，无需开发人员使用任何命名空间名称（如）th:*。Thymeleaf 使此语法自动适用于所有方言（不仅仅是标准方言）。

还有一种语法用于指定自定义标签：{prefix}-{name}，它遵循W3C 自定义元素规范（ W3C Web 组件规范的一部分）。例如，这可以用于元素th:block（或th-block），这将在后面的部分中解释。

重要提示：此语法是对命名空间语法的补充th:*，并非替代。未来我们完全没有打算弃用命名空间语法。

6.1 迭代基础

为了在/WEB-INF/templates/product/list.html页面中显示产品，我们将使用表格。我们的每件产品都将显示在一行中（一个<tr>元素），因此对于我们的模板，我们需要创建一个模板行- 一个将举例说明我们希望如何显示每件产品的行 - 然后指示 Thymeleaf 重复此操作，对每件产品重复一次。

标准方言为我们提供了一个确切的属性：th:each。

public void process(
        final HttpServletRequest request, final HttpServletResponse response,
        final ServletContext servletContext, final ITemplateEngine templateEngine)
        throws Exception {
    
    ProductService productService = new ProductService();
    List<Product> allProducts = productService.findAll(); 
    
    WebContext ctx = new WebContext(request, response, servletContext, request.getLocale());
    ctx.setVariable("prods", allProducts);
    
    templateEngine.process("product/list", ctx, response.getWriter());
    
}

<!DOCTYPE html>

<html xmlns:th="http://www.thymeleaf.org">

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" media="all" 
          href="../../../css/gtvg.css" th:href="@{/css/gtvg.css}" />
  </head>

  <body>

    <h1>Product list</h1>
  
    <table>
      <tr>
        <th>NAME</th>
        <th>PRICE</th>
        <th>IN STOCK</th>
      </tr>
      <tr th:each="prod : ${prods}">
        <td th:text="${prod.name}">Onions</td>
        <td th:text="${prod.price}">2.41</td>
        <td th:text="${prod.inStock}? #{true} : #{false}">yes</td>
      </tr>
    </table>
  
    <p>
      <a href="../home.html" th:href="@{/}">Return to home</a>
    </p>

  </body>

</html>

6.2 保持迭代状态

使用时th:each，Thymeleaf 提供了一种用于跟踪迭代状态的有用机制：状态变量。

状态变量在属性内定义th:each并包含以下数据：

• 当前迭代索引，从 0 开始。这是index属性。
• 当前迭代索引，从 1 开始。这是count属性。
• 迭代变量中的元素总数。这是size属性。
• 每次迭代的iter 变量。这是current属性。
• 当前迭代是偶数还是奇数。这些是even/odd布尔属性。
• 当前迭代是否为第一次迭代。这是一个first布尔属性。
• 当前迭代是否是最后一次迭代。这是一个last布尔属性。

让我们看看如何在前面的例子中使用它：

<table>
  <tr>
    <th>NAME</th>
    <th>PRICE</th>
    <th>IN STOCK</th>
  </tr>
  <tr th:each="prod,iterStat : ${prods}" th:class="${iterStat.odd}? 'odd'">
    <td th:text="${prod.name}">Onions</td>
    <td th:text="${prod.price}">2.41</td>
    <td th:text="${prod.inStock}? #{true} : #{false}">yes</td>
  </tr>
</table>

状态变量（iterStat在本例中）在属性中定义，th:each方法是将其名称写在 iter 变量本身后面，以逗号分隔。与 iter 变量一样，状态变量的作用域也限定在由保存属性的标签定义的代码片段中th:each。

让我们看一下处理模板的结果：

<!DOCTYPE html>

<html>

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
    <link rel="stylesheet" type="text/css" media="all" href="/gtvg/css/gtvg.css" />
  </head>

  <body>

    <h1>Product list</h1>
  
    <table>
      <tr>
        <th>NAME</th>
        <th>PRICE</th>
        <th>IN STOCK</th>
      </tr>
      <tr class="odd">
        <td>Fresh Sweet Basil</td>
        <td>4.99</td>
        <td>yes</td>
      </tr>
      <tr>
        <td>Italian Tomato</td>
        <td>1.25</td>
        <td>no</td>
      </tr>
      <tr class="odd">
        <td>Yellow Bell Pepper</td>
        <td>2.50</td>
        <td>yes</td>
      </tr>
      <tr>
        <td>Old Cheddar</td>
        <td>18.75</td>
        <td>yes</td>
      </tr>
    </table>
  
    <p>
      <a href="/gtvg/" shape="rect">Return to home</a>
    </p>

  </body>
  
</html>

请注意，我们的迭代状态变量已完美运行，odd仅将 CSS 类建立到奇数行。

如果你没有明确设置状态变量，Thymeleaf 将始终通过Stat在迭代变量名称后添加后缀来为你创建一个：

<table>
  <tr>
    <th>NAME</th>
    <th>PRICE</th>
    <th>IN STOCK</th>
  </tr>
  <tr th:each="prod : ${prods}" th:class="${prodStat.odd}? 'odd'">
    <td th:text="${prod.name}">Onions</td>
    <td th:text="${prod.price}">2.41</td>
    <td th:text="${prod.inStock}? #{true} : #{false}">yes</td>
  </tr>
</table>

6.3 通过惰性检索数据进行优化

有时我们可能希望优化数据集合的检索（例如从数据库），以便只有在真正需要使用时才检索这些集合。

实际上，这可以应用于任何数据，但考虑到内存集合可能具有的大小，检索需要迭代的集合是此场景中最常见的情况。

为了支持这一点，Thymeleaf 提供了一种延迟加载上下文变量的机制。实现接口的上下文变量ILazyContextVariable（很可能通过扩展其LazyContextVariable默认实现）将在执行时解析。例如：

context.setVariable(
     "users",
     new LazyContextVariable<List<User>>() {
         @Override
         protected List<User> loadValue() {
             return databaseRepository.findAllUsers();
         }
     });

这个变量可以在不了解其惰性的情况下使用，例如在代码中：

<ul>
  <li th:each="u : ${users}" th:text="${u.name}">user name</li>
</ul>

但同时，如果在代码中计算结果为，则永远不会被初始化（其loadValue()方法永远不会被调用） ：conditionfalse

<ul th:if="${condition}">
  <li th:each="u : ${users}" th:text="${u.name}">user name</li>
</ul>

7.1 简单条件：“如果”和“除非”

有时您需要模板的某个片段仅在满足某个特定条件时才出现在结果中。

例如，假设我们想在产品表中显示一列，其中包含每个产品的评论数，如果有任何评论，则显示指向该产品评论详细信息页面的链接。

为了做到这一点，我们将使用以下th:if属性：

<table>
  <tr>
    <th>NAME</th>
    <th>PRICE</th>
    <th>IN STOCK</th>
    <th>COMMENTS</th>
  </tr>
  <tr th:each="prod : ${prods}" th:class="${prodStat.odd}? 'odd'">
    <td th:text="${prod.name}">Onions</td>
    <td th:text="${prod.price}">2.41</td>
    <td th:text="${prod.inStock}? #{true} : #{false}">yes</td>
    <td>
      <span th:text="${#lists.size(prod.comments)}">2</span> comment/s
      <a href="comments.html" 
         th:href="@{/product/comments(prodId=${prod.id})}" 
         th:if="${not #lists.isEmpty(prod.comments)}">view</a>
    </td>
  </tr>
</table>

这里有很多东西需要查看，因此让我们集中关注重要的一行：

<a href="comments.html"
   th:href="@{/product/comments(prodId=${prod.id})}" 
   th:if="${not #lists.isEmpty(prod.comments)}">view</a>

这将创建一个指向评论页面的链接（带有 URL /product/comments），并将prodId参数设置为id产品的，但前提是该产品有任何评论。

让我们看一下最终的标记：

<table>
  <tr>
    <th>NAME</th>
    <th>PRICE</th>
    <th>IN STOCK</th>
    <th>COMMENTS</th>
  </tr>
  <tr>
    <td>Fresh Sweet Basil</td>
    <td>4.99</td>
    <td>yes</td>
    <td>
      <span>0</span> comment/s
    </td>
  </tr>
  <tr class="odd">
    <td>Italian Tomato</td>
    <td>1.25</td>
    <td>no</td>
    <td>
      <span>2</span> comment/s
      <a href="/gtvg/product/comments?prodId=2">view</a>
    </td>
  </tr>
  <tr>
    <td>Yellow Bell Pepper</td>
    <td>2.50</td>
    <td>yes</td>
    <td>
      <span>0</span> comment/s
    </td>
  </tr>
  <tr class="odd">
    <td>Old Cheddar</td>
    <td>18.75</td>
    <td>yes</td>
    <td>
      <span>1</span> comment/s
      <a href="/gtvg/product/comments?prodId=4">view</a>
    </td>
  </tr>
</table>

太棒了！这正是我们想要的。

请注意，该th:if属性不仅会评估布尔条件。它的功能远不止于此，它将按照true以下规则评估指定的表达式：

• 如果值不为空：
  • 如果值是布尔值并且是true。
  • 如果值是数字且非零
  • 如果值是字符且非零
  • 如果值是字符串且不是“false”、“off”或“no”
  • 如果值不是布尔值、数字、字符或字符串。
• （如果值为空，则 th:if 将计算为 false）。

此外，th:if还有一个逆属性th:unless，我们可以在前面的例子中使用它，而不是not在 OGNL 表达式中使用：

<a href="comments.html"
   th:href="@{/comments(prodId=${prod.id})}" 
   th:unless="${#lists.isEmpty(prod.comments)}">view</a>