Thymeleaf 中文文档----全译版

1 引入Thymeleaf

1.1 Thymeleaf是什么?

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

Thymeleaf的主要目标是提供一种优雅的和高度可维护的方式来创建模板。为了实现这一点，它构建在自然模板的概念上，以不影响模板作为设计原型使用的方式将其逻辑注入模板文件。这改进了设计的交流，并在设计和开发团队之间架起了桥梁。

Thymeleaf的设计从一开始就考虑了Web标准——尤其是HTML5——允许你创建完全验证模板，如果你需要的话。

1.2 Thymeleaf可以处理什么样的模板?

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

• HTML
• XML
• TEXT
• JAVASCRIPT
• CSS
• RAW

有两种标记模板模式(HTML和XML)、三种文本模板模式(文本、JAVASCRIPT和CSS)和一种无操作模板模式(RAW)。

HTML模板模式将允许任何类型的HTML输入，包括HTML5、HTML 4和XHTML。将不执行任何验证或格式良好性检查，并且将在输出中尽可能尊重模板代码/结构。

XML模板模式将允许XML输入。在这种情况下，代码应该是格式良好的—没有未关闭的标记，没有未引用的属性，等等—如果发现格式良好性违规，解析器将抛出异常。注意，将不执行任何验证(针对DTD或XML模式)。

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

JAVASCRIPT模板模式将允许在Thymeleaf应用程序中处理JAVASCRIPT文件。这意味着能够像在HTML文件中一样在JavaScript文件中使用模型数据，但是要使用特定于JavaScript的集成，比如专门的转义或自然脚本。JAVASCRIPT模板模式被认为是文本模式，因此使用与文本模板模式相同的特殊语法。

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

原始模板模式根本不会处理模板。它用于将未触及的资源(文件、URL响应等)插入正在处理的模板中。例如，可以将HTML格式的外部非控制资源包含到应用程序模板中，但要确保这些资源可能包含的任何Thymeleaf代码都不会被执行。

1.3 方言:标准方言

Thymeleaf是一个非常可扩展的模板引擎(事实上它可以被称为模板引擎框架)，它允许你定义和自定义的方式，你的模板将被处理到一个精细的细节级别。

将一些逻辑应用到标记工件(标记、一些文本、注释，如果模板不是标记，则仅仅是占位符)的对象称为处理程序，这些处理程序的集合—加上一些额外的工件—通常是方言的组成部分。Thymeleaf的核心库提供了一种称为标准方言的方言，这对大多数用户来说应该足够了。

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

本教程介绍标准方言。在下面的页面中，您将了解到的每个属性和语法特性都是由这种方言定义的，即使没有明确提到。

当然，如果希望在利用库的高级特性的同时定义自己的处理逻辑，用户可以创建自己的方言(甚至扩展标准的方言)。Thymeleaf也可以配置成同时使用几种方言。

官方thymeleaf-spring3和thymeleaf-spring4集成包都定义一个方言称为“SpringStandard方言”,大部分是一样的标准方言,但小适应更好地利用Spring框架的一些特性(例如,通过使用Spring表达式语言或图像代替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 一个很棒的虚拟杂货店设计

本文所示示例的源代码，以及本指南的后续章节，可以在 Good Thymes Virtual Grocery GitHub repository.

2.1 一个杂货店的网站

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

这个应用程序是一个虚拟杂货店的web站点，它将为我们提供许多场景来展示Thymeleaf的许多特性。

首先，我们的应用程序需要一组简单的模型实体:通过创建订单向客户销售的产品。我们还将管理这些产品的评论:

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

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);

模板解析器是实现来自调用的Thymeleaf API的接口的对象

org.thymeleaf.templateresolver.ITemplateResolver：

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);
}

这些对象负责决定如何访问模板，在这个GTVG应用程序中，org.thymeleaf.templateresolver.ServletContextTemplateResolver 意味着我们要从Servlet上下文中获取模板文件作为资源:应用程序范围的javax.servlet.ServletContext对象存在于每个Java web应用程序中，它从web应用程序根目录解析资源。

但这还不是我们对模板解析器所能说的全部，因为我们可以在它上面设置一些配置参数。

一、模板模式:

templateResolver.setTemplateMode(TemplateMode.HTML);

HTML是ServletContextTemplateResolver的默认模板模式，但是最好还是建立它，以便我们的代码清楚地记录正在发生的事情。

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

前缀和后缀修改我们将传递给引擎的模板名称，以获得要使用的实际资源名称。

使用此配置，模板名称“product/list”将对应于:

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

可选地，在模板解析器中通过cacheTTLMs属性配置一个解析后的模板在缓存中的生存时间:

templateResolver.setCacheTTLMs(3600000L);

如果达到了最大缓存大小，并且它是当前缓存中最老的条目，那么在到达TTL之前仍然可以从缓存中删除模板。

用户可以通过实现ICacheManager接口或修改StandardCacheManager对象来管理默认缓存来定义缓存行为和大小。

关于模板解析器还有很多要学习的，但是现在让我们来看看模板引擎对象的创建。

模板引擎

模板引擎对象是org.thymeleaf.ITemplateEngine接口的实现。其中一个实现是由Thymeleaf核心:org.thymeleaf.ITemplateEngine，我们创建了一个实例，它在这里:

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

很简单，不是吗?我们只需要创建一个实例并将模板解析器设置为它。

模板解析器是TemplateEngine惟一需要的参数，尽管后面还会介绍许多其他参数(消息解析器、缓存大小等)。现在，这就是我们所需要的。

我们的模板引擎现在已经准备好了，我们可以开始使用Thymeleaf创建我们的页面。

3 使用文本

3.1 多语言的欢迎

我们的第一个任务是为我们的杂货站点创建一个主页。

这个页面的第一个版本将非常简单:只有一个标题和一条欢迎信息。

这是我们的/WEB-INF/templates/home.html文件:

 
<html xmlns:th="http://www.thymeleaf.org">
 
  <head>
    <title>Good Thymes Virtual Grocerytitle>
    <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属性到我们的标签，一些绝对非html5的东西:

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

它在模板处理中没有任何影响，但是作为一个incantation，这就避免了我们的IDE抱怨th:*这些属性缺少命名空间定义。

那么，如果我们想让这个模板html5有效呢?简单:切换到Thymeleaf的数据属性语法，使用数据前缀的属性名称和连字符(-)分隔符，而不是分号(:

 
<html>
 
  <head>
    <title>Good Thymes Virtual Grocerytitle>
    <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>

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

这两种表示法完全等价并且可以互换，但是为了代码示例的简单性和紧凑性，本教程将使用名称空间表示法(th:*)。此外，th:*符号更通用，在每个Thymeleaf模板模式(XML，文本…)，而数据符号只允许在HTML模式。

使用th:text和 externalizing text

外部化文本是从模板文件中提取模板代码片段，以便将它们保存在单独的文件中(通常是.properties文件)，并且可以用其他语言编写的等价文本轻松替换它们(这个过程称为国际化，简称i18n)。外部化的文本片段通常称为“消息”。

消息总是有一个标识它们的键，而Thymeleaf允许您指定文本应该与#{…}语法:

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

我们在这里看到的实际上是Thymeleaf标准方言的两个不同的特点:

• th:text属性，它计算其值表达式并将结果设置为主机标记的主体，有效地替换了“欢迎光临我们的杂货店!”“我们在代码中看到的文本。
• #{home.welcome}表达式，在标准表达式语法中指定，指示th:text属性使用的文本应该是带有home.welcome的消息。对应于我们正在处理模板的任何语言环境的键。

现在，这个外化的文本在哪里?

Thymeleaf中外部化文本的位置是完全可配置的，并且将取决于org.thymeleaf.messageresolver.IMessageResolver所使用的特定实现。通常，.properties将使用基于文件的实现，但是例如，如果我们想从数据库中获取消息，则可以创建自己的实现。

但是，我们尚未在初始化期间为模板引擎指定消息解析器，这意味着我们的应用程序使用的是由实现的 标准消息解析器thymeleaf.messageresolver.StandardMessageResolver。

标准消息解析器希望/WEB-INF/templates/home.html在与模板相同名称和名称的文件夹中的属性文件中查找消息，例如：

• /WEB-INF/templates/home_en.properties 用于英文文本。
• /WEB-INF/templates/home_es.properties 西班牙语文本。
• /WEB-INF/templates/home_pt_BR.properties 用于葡萄牙语（巴西）语言文本。
• /WEB-INF/templates/home.properties 用于默认文本（如果语言环境不匹配）。

让我们看一下我们的home_es.properties文件：

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

这就是使Thymeleaf加工成为模板所需要的。然后创建我们的Home控制器。

语境（上下文）

为了处理我们的模板，我们将创建一个HomeController实现IGTVGController之前看到的接口的类：

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());
        
    }
 
}

我们首先看到的是上下文的创建。Thymeleaf上下文是实现org.thymeleaf.context.IContext接口的对象。上下文应在变量映射中包含执行模板引擎所需的所有数据，并且还应引用必须用于外部化消息的语言环境。

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

该接口有一个专门的扩展，org.thymeleaf.context.IWebContext可以在基于ServletAPI的Web应用程序（如SpringMVC）中使用。

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

Thymeleaf核心库提供了以下每个接口的实现：

• org.thymeleaf.context.Context 实施 IContext
• org.thymeleaf.context.WebContext 实施 IWebContext

正如您在控制器代码中看到的那样，这WebContext是我们使用的代码。实际上，我们必须这样做，因为使用a ServletContextTemplateResolver要求我们使用上下文实现IWebContext。

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

这四个构造函数参数中只有三个是必需的，因为如果未指定默认语言环境，则将使用系统的默认语言环境（尽管您绝对不应在实际应用程序中让这种情况发生）。

我们可以使用一些专门的表达式从WebContext模板中的获取请求参数以及请求，会话和应用程序属性。例如：

• ${x}将返回x存储在Thymeleaf上下文中或作为请求属性的变量。
• ${param.x}将返回一个名为（可能是多值）的请求参数x。
• ${session.x}将返回名为的会话属性x。
• ${application.x}将返回名为的Servlet上下文属性x。

执行模板引擎

准备好上下文对象之后，现在我们可以告诉模板引擎使用上下文处理模板（按其名称），并将其传递给响应编写器，以便可以将响应写入其中：

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

让我们使用西班牙语语言环境查看结果：

 
<html>
 
  <head>
    <title>Good Thymes Virtual Grocerytitle>
    <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 fantastic grocery store!

如果像以前一样执行此模板，我们将获得：

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

这与我们期望的不完全相同，因为我们的代码已被转义，因此将在浏览器中显示。

这是th:text属性的默认行为。如果我们希望Thymeleaf尊重我们的HTML标记而不是对其进行转义，我们将不得不使用不同的属性：（th:utext用于“未转义的文本”）：

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

这将输出我们的消息，就像我们想要的那样：

<p>Welcome to our <b>fantasticb> 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());
        
}

我们在上下文中添加了一个String类型的变量today，现在我们可以在模板中显示它：

 
  
Welcome to our grocery store!
 
  
Today is: 13 February 2011
  

如您所见，我们仍在使用th:text属性来工作（这是正确的，因为我们要替换标签的主体），但是这次的语法略有不同#{...}，我们使用的不是表达式值${...}。这是一个变量表达式，它包含一种称为OGNL（对象图导航语言）的语言的表达式，该表达式将在我们之前提到的上下文变量映射上执行。

该${today}表达式仅表示“获取今天调用的变量”，但是这些表达式可能更复杂（例如${user.name}“获取称为用户的变量并调用其getName()方法”）。

属性值有很多可能性：消息，变量表达式等等。下一章将向我们展示所有这些可能性。

4 标准表达式语法

我们将在杂货店虚拟商店的开发中稍作休息，以了解Thymeleaf标准方言最重要的部分之一：Thymeleaf Standard Expression语法。

我们已经看到了用这种语法表示的两种有效属性值：消息和变量表达式：

<p th:utext="#{home.welcome}">Welcome to our grocery store!p>
 
<p>Today is: <span th:text="${today}">13 february 2011span>p>

但是有更多类型的表达式，还有更多有趣的细节来了解我们已经知道的表达式。首先，让我们看一下标准表达式功能的快速摘要：

• 简单表达式：
  • 变量表达式： ${…}
  • 选择变量表达式： *{…}
  • 消息表达： #{...}
  • 链接URL表达式： @{…}
  • 片段表达式： ~{…}
• 文字
  • 文本文字：‘one text’，‘Another one!’，…
  • 号码文字：0，34，3.0，12.3，…
  • 布尔文字：true，false
  • 空文字： null
  • 文字标记：one，sometext，main，…
• 文字操作：
  • 字符串串联： +
  • 文字替换： |The name is ${name}|
• 算术运算：
  • 二元运算符：+，-，*，/，%
  • 减号（一元运算符）： -
• 布尔运算：
  • 二元运算符：and，or
  • 布尔否定（一元运算符）： !，not
• 比较和相等：
  • 比较：>，<，>=，<=（gt，lt，ge，le）
  • 等号运算符：==，!=（eq，ne）
• 条件运算符：
  • 如果-则： (if) ? (then)
  • 如果-则-否则： (if) ? (then) : (else)
  • 默认： (value) ?: (defaultvalue)
• 特殊令牌：
  • 无操作： _

所有这些功能都可以组合和嵌套：

'User is of type ' + (${user.isAdmin()} ? 'Administrator' : (${user.type} ?: 'Unknown'))

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 2011span>.p>

…实际上等于：

ctx.getVariable("today");

但是OGNL允许我们创建功能更强大的表达式，这就是这种方式：

  Welcome to our grocery store, Sebastian Pepper!

…通过执行以下操作获取用户名：

((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('-')}
 

表达式基本对象

在上下文变量上评估OGNL表达式时，某些对象可用于表达式，以提高灵活性。这些对象（根据OGNL标准）将以#符号开头进行引用：

• #ctx：上下文对象。
• #vars: 上下文变量。
• #locale：上下文语言环境。
• #request：（仅在Web上下文中）HttpServletRequest对象。
• #response：（仅在Web上下文中）HttpServletResponse对象。
• #session：（仅在Web上下文中）HttpSession对象。
• #servletContext：（仅在Web上下文中）ServletContext对象。

因此，我们可以这样做：

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

您可以在附录A中阅读这些对象的完整参考。

表达工具对象

除了这些基本对象之外，Thymeleaf将为我们提供一组实用程序对象，这些对象将帮助我们在表达式中执行常见任务。

• #execInfo：有关正在处理的模板的信息。
• #messages：用于获取变量表达式内的外部化消息的方法，与使用＃{…}语法获得消息的方法相同。
• #uris：用于转义部分URL / URI的方法
• #conversions：用于执行已配置的转换服务（如果有）的方法。
• #dates：java.util.Date对象的方法：格式化，组件提取等。
• #calendars：类似于#dates，但用于java.util.Calendar对象。
• #numbers：格式化数字对象的方法。
• #strings：String对象的方法：包含，startsWith，前置/追加等。
• #objects：一般对象的方法。
• #bools：布尔值评估的方法。
• #arrays：数组方法。
• #lists：列表方法。
• #sets：套方法。
• #maps：地图方法。
• #aggregates：用于在数组或集合上创建聚合的方法。
• #ids：用于处理可能重复的id属性的方法（例如，由于迭代的结果）。

您可以在 附录B 中检查每个实用程序对象提供的功能。

在我们的主页中重新格式化日期

现在我们知道了这些实用程序对象，可以使用它们来更改在首页中显示日期的方式。而不是在我们的系统中这样做

HomeController：

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 2011span>
p>

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

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

但是，有一个重要的区别：星号语法在选定对象而不是整个上下文上评估表达式。也就是说，只要没有选定的对象，美元和星号的语法就完全一样。

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

  <div th:object="${session.user}">
    <p>Name: <span th:text="*{firstName}">Sebastianspan>.p>
    <p>Surname: <span th:text="*{lastName}">Pepperspan>.p>
    <p>Nationality: <span th:text="*{nationality}">Saturnspan>.p>
  div>

完全等同于：

<div>
  <p>Name: <span th:text="${session.user.firstName}">Sebastianspan>.p>
  <p>Surname: <span th:text="${session.user.lastName}">Pepperspan>.p>
  <p>Nationality: <span th:text="${session.user.nationality}">Saturnspan>.p>
div>

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

<div th:object="${session.user}">
  <p>Name: <span th:text="*{firstName}">Sebastianspan>.p>
  <p>Surname: <span th:text="${session.user.lastName}">Pepperspan>.p>
  <p>Nationality: <span th:text="*{nationality}">Saturnspan>.p>
div>

选择对象后，选定的对象也可以作为#object表达式变量用于美元表达式：

<div th:object="${session.user}">
  <p>Name: <span th:text="${#object.firstName}">Sebastianspan>.p>
  <p>Surname: <span th:text="${session.user.lastName}">Pepperspan>.p>
  <p>Nationality: <span th:text="*{nationality}">Saturnspan>.p>
div>

如前所述，如果未执行任何对象选择，则美元和星号语法是等效的。

<div>
  <p>Name: <span th:text="*{session.user.name}">Sebastianspan>.p>
  <p>Surname: <span th:text="*{session.user.surname}">Pepperspan>.p>
  <p>Nationality: <span th:text="*{session.user.nationality}">Saturnspan>.p>
div>

4.4 链接网址

由于它们的重要性，URL是Web应用程序模板中的一等公民，而Thymeleaf Standard Dialect对它们有一种特殊的语法，该@语法为：@{...}

URL有不同类型：

• 绝对网址： http://www.thymeleaf.org
• 相对URL，可以是：
  • 相对页面： user/login.html
  • 上下文相关：（/itemdetails?id=3服务器中的上下文名称将自动添加）
  • 相对于服务器：（~/billing/processInvoice允许在同一服务器中的另一个上下文（=应用程序）中调用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属性：

<a href="details.html" 
   th:href="@{http://localhost:8080/gtvg/order/details(orderId=${o.id})}">viewa>
 

<a href="details.html" th:href="@{/order/details(orderId=${o.id})}">viewa>
 

<a href="details.html" th:href="@{/order/{orderId}/details(orderId=${o.id})}">viewa>

这里要注意一些事情：

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

与消息语法（#{...}）一样，URL基也可以是求值另一个表达式的结果：

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

主页的菜单

现在，我们知道了如何创建链接URL，如何在主页中为站点中的其他页面添加一个小菜单？

Please select an option

  
Product List
  
Order List
  
Subscribe to our Newsletter
  
See User Profile

服务器根目录相对URL

可以使用其他语法来创建相对于服务器根目录的URL（而不是上下文根目录的URL），以便链接到同一服务器中的不同上下文。这些网址的指定方式如下@{~/path/to/something}

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 filespan>.
p>

数字文本

数字文本就是：数字。

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

布尔文本

布尔文本是true和false。例如：

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

在此示例中，== false y是写在花括号外的，因此Thymeleaf负责处理。如果将其写在花括号内，则OGNL / SpringEL引擎应负责：

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

空文本

该null文本也可用于：

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

文字代币

实际上，数字，布尔值和null文字是文字标记的一种特殊情况。

这些标记允许在标准表达式中进行一些简化。它们的工作原理与文本文字（'...'）完全相同，但是它们仅允许使用字母（A-Z和a-z），数字（0-9），方括号（[和]），点（.），连字符（-）和下划线（_）。因此，没有空格，没有逗号等。

好的部分？令牌不需要任何引号引起来。因此，我们可以这样做：

<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 比较器和平等

在表达式中的值可以与进行比较>，<，>=和<=符号，以及==和!=运营商可以被用来检查是否相等（或缺乏）。请注意，XML规定，不得在属性值中使用<和>符号，因此应将其替换为<和 >。

<div th:if="${prodStat.count} > 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）本身的表达式，这意味着它们可以是变量（${...}，*{...}），消息（#{...}），网址（@{...}）或文字（'...'）。

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

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

其他表达式也可以省略，在这种情况下，如果条件为false，则返回null值：

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

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

一个默认的表情是一种特殊的条件值的没有那么一部分。它等效于某些语言（如Groovy）中出现的Elvis运算符，可让您指定两个表达式：如果第一个表达式的计算结果不为null，则使用第一个表达式；如果第二个表达式使用，则使用第二个表达式。

让我们在我们的用户个人资料页面中看到它的实际效果：

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

如您所见，运算符为?:，并且仅当求*{age}值结果为null时，才在此处使用它来指定名称的默认值（在这种情况下为文字值）。因此，这等效于：

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

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

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

4.13 无操作令牌

No-Operation令牌由下划线符号（_）表示。

该标记背后的想法是指定表达式的期望结果什么也不做，即完全就像可处理属性（例如th:text）根本不存在一样。

除其他可能性外，这还使开发人员可以将原型文本用作默认值。例如，代替：

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

…我们可以直接将“未经用户身份验证”用作原型文本，从设计的角度来看，这使得代码既简洁又通用：

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

4.14 数据转换/格式化

Thymeleaf 为变量（）和选择（）表达式定义了双括号语法，使我们能够通过配置的转换服务来应用数据转换。${...} *{...}

它基本上是这样的：

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

注意到那里有双括号了吗？：${ {...}}。指示Thymeleaf将user.lastAccessDate表达式的结果传递给转换服务，并要求它执行格式操作（将转换为String），然后再写入结果。

假设user.lastAccessDate类型为java.util.Calendar，如果已注册转换服务（的实现IStandardConversionService）并且包含的有效转换Calendar -> String，则将应用。

IStandardConversionService（StandardConversionService该类）的默认实现仅对.toString()转换为的任何对象执行String。有关如何注册自定义转换服务实现的更多信息，请参见 更多关于配置部分。

官方的thymeleaf-spring3和thymeleaf-spring4集成软件包将Thymeleaf的转换服务机制与Spring自己的转换服务基础结构透明地集成在一起，以便在Spring配置中声明的转换服务和格式化程序将自动提供给${ {...}}和*{ {...}}表达式。

4.15 预处理

除了用于表达式处理的所有这些功能之外，Thymeleaf还具有预处理表达式的功能。

预处理是在普通表达式之前执行的表达式的执行，该表达式允许修改最终将要执行的表达式。

预处理表达式与普通表达式完全一样，但是出现了一个双下划线符号（如__${expression}__）。

假设我们有一个i18n Messages_fr.properties条目，其中包含一个OGNL表达式，该表达式调用特定于语言的静态方法，例如：

[email protected]@translateToFrench({0})

…和Messages_es.properties equivalent：

[email protected]@translateToSpanish({0})

我们可以创建一个标记片段，该片段根据语言环境评估一个表达式或另一个表达式。为此，我们将首先选择表达式（通过预处理），然后让Thymeleaf执行它：

Some text here...

请注意，法语语言环境的预处理步骤将创建以下等效项：

Some text here...

可以使用来在属性中对预处理字符串进行转义。

5 设置属性值

本章将说明在标记中设置（或修改）属性值的方法。

5.1 设置任何属性的值

假设我们的网站发布了新闻通讯，我们希望用户能够订阅该新闻通讯，所以我们创建/WEB-INF/templates/subscribe.html具有以下形式的模板：

<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以前放过的那些吗？它们是完全一样的属性：

Product List

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

 
th:abbr	th:accept	th:accept-charset
th:accesskey	th:action	th:align
th:alt	th:archive	th:audio
th:autocomplete	th:axis	th:background
th:bgcolor	th:border	th:cellpadding
th:cellspacing	th:challenge	th:charset
th:cite	th:class	th:classid
th:codebase	th:codetype	th:cols
th:colspan	th:compact	th:content
th:contenteditable	th:contextmenu	th:data
th:datetime	th:dir	th:draggable
th:dropzone	th:enctype	th:for
th:form	th:formaction	th:formenctype
th:formmethod	th:formtarget	th:fragment
th:frame	th:frameborder	th:headers
th:height	th:high	th:href
th:hreflang	th:hspace	th:http-equiv
th:icon	th:id	th:inline
th:keytype	th:kind	th:label
th:lang	th:list	th:longdesc
th:low	th:manifest	th:marginheight
th:marginwidth	th:max	th:maxlength
th:media	th:method	th:min
th:name	th:onabort	th:onafterprint
th:onbeforeprint	th:onbeforeunload	th:onblur
th:oncanplay	th:oncanplaythrough	th:onchange
th:onclick	th:oncontextmenu	th:ondblclick
th:ondrag	th:ondragend	th:ondragenter
th:ondragleave	th:ondragover	th:ondragstart
th:ondrop	th:ondurationchange	th:onemptied
th:onended	th:onerror	th:onfocus
th:onformchange	th:onforminput	th:onhashchange
th:oninput	th:oninvalid	th:onkeydown
th:onkeypress	th:onkeyup	th:onload
th:onloadeddata	th:onloadedmetadata	th:onloadstart
th:onmessage	th:onmousedown	th:onmousemove
th:onmouseout	th:onmouseover	th:onmouseup
th:onmousewheel	th:onoffline	th:ononline
th:onpause	th:onplay	th:onplaying
th:onpopstate	th:onprogress	th:onratechange
th:onreadystatechange	th:onredo	th:onreset
th:onresize	th:onscroll	th:onseeked
th:onseeking	th:onselect	th:onshow
th:onstalled	th:onstorage	th:onsubmit
th:onsuspend	th:ontimeupdate	th:onundo
th:onunload	th:onvolumechange	th:onwaiting
th:optimum	th:pattern	th:placeholder
th:poster	th:preload	th:radiogroup
th:rel	th:rev	th:rows
th:rowspan	th:rules	th:sandbox
th:scheme	th:scope	th:scrolling
th:size	th:sizes	th:span
th:spellcheck	th:src	th:srclang
th:standby	th:start	th:step
th:style	th:summary	th:tabindex
th:target	th:title	th:type
th:usemap	th:value	th:valuetype
th:vspace	th:width	th:wrap
th:xmlbase	th:xmllang	th:xmlspace

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具有布尔属性的概念，即没有值的属性，并且首字母缩写为1表示值是“ true”。在XHTML中，这些属性仅取1值，这就是它本身。

例如checked：

<input type="checkbox" name="option2" checked /> 
<input type="checkbox" name="option1" checked="checked" /> 

标准方言包括一些属性，这些属性使您可以通过评估条件来设置这些属性，因此，如果评估为true，则该属性将设置为其固定值；如果评估为false，则将不设置该属性：

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

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

 
th:async	th:autofocus	th:autoplay
th:checked	th:controls	th:declare
th:default	th:defer	th:disabled
th:formnovalidate	th:hidden	th:ismap
th:loop	th:multiple	th:novalidate
th:nowrap	th:open	th:pubdate
th:readonly	th:required	th:reversed
th:scoped	th:seamless	th:selected

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 迭代

到目前为止，我们已经创建了一个主页，一个用户个人资料页面以及一个允许用户订阅我们的新闻通讯的页面……但是我们的产品呢？为此，我们将需要一种方法来遍历集合中的项目以构建我们的产品页面。

6.1 迭代基础

为了在我们的/WEB-INF/templates/product/list.html页面中显示产品，我们将使用一个表格。我们的每种产品都将显示在一行（一个元素）中，因此对于我们的模板，我们需要创建一个模板行 -一个示例行，以举例说明我们希望每种产品的显示方式，然后指示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());
    
}

然后，我们将th:each在模板中使用它来遍历产品列表：

 
<html xmlns:th="http://www.thymeleaf.org">
 
  <head>
    <title>Good Thymes Virtual Grocerytitle>
    <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 listh1>
  
    <table>
      <tr>
        <th>NAMEth>
        <th>PRICEth>
        <th>IN STOCKth>
      tr>
      <tr th:each="prod : ${prods}">
        <td th:text="${prod.name}">Onionstd>
        <td th:text="${prod.price}">2.41td>
        <td th:text="${prod.inStock}? #{true} : #{false}">yestd>
      tr>
    table>
  
    <p>
      <a href="../home.html" th:href="@{/}">Return to homea>
    p>
 
  body>
 
html>

即prod : ${prods}你看到上述手段的属性值“为在评估的结果的每个元素${prods}，重复模板的该片段中，使用一个称为PROD可变当前元素”。让我们给每一个看到的事物命名：

我们将调用${prods}的迭代式或迭代变量。
我们将调用prod的迭代变量或者干脆ITER变量。

请注意，proditer变量的作用域为元素，这意味着它可用于内部标记（如）。

迭代值

该java.util.List班是不是可以在Thymeleaf用于迭代onlyvalue。有相当完整的一组对象，这些对象被属性视为可迭代的th:each：

• 任何实现的对象 java.util.Iterable
• 任何实现的对象java.util.Enumeration。
• 实现的任何对象java.util.Iterator，其值将由迭代器返回，而无需在内存中缓存所有值。
• 任何实现的对象java.util.Map。迭代地图时，迭代变量将属于class java.util.Map.Entry。
• 任何数组。
• 任何其他对象都将被视为包含该对象本身的单值列表。

6.2 保持迭代状态

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

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

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

让我们看看如何在上一个示例中使用它：

<table>
  <tr>
    <th>NAMEth>
    <th>PRICEth>
    <th>IN STOCKth>
  tr>
  <tr th:each="prod,iterStat : ${prods}" th:class="${iterStat.odd}? 'odd'">
    <td th:text="${prod.name}">Onionstd>
    <td th:text="${prod.price}">2.41td>
    <td th:text="${prod.inStock}? #{true} : #{false}">yestd>
  tr>
table>

iterStat在th:each属性中定义状态变量（在此示例中），方法是在iter变量本身之后写入名称，并用逗号分隔。就像iter变量一样，status变量的范围也由持有th:each属性的标签所定义的代码片段组成。

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

 
<html>
 
  <head>
    <title>Good Thymes Virtual Grocerytitle>
    <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 listh1>
  
    <table>
      <tr>
        <th>NAMEth>
        <th>PRICEth>
        <th>IN STOCKth>
      tr>
      <tr class="odd">
        <td>Fresh Sweet Basiltd>
        <td>4.99td>
        <td>yestd>
      tr>
      <tr>
        <td>Italian Tomatotd>
        <td>1.25td>
        <td>notd>
      tr>
      <tr class="odd">
        <td>Yellow Bell Peppertd>
        <td>2.50td>
        <td>yestd>
      tr>
      <tr>
        <td>Old Cheddartd>
        <td>18.75td>
        <td>yestd>
      tr>
    table>
  
    <p>
      <a href="/gtvg/" shape="rect">Return to homea>
    p>
 
  body>
  
html>

请注意，我们的迭代状态变量运行良好，odd仅对奇数行建立了CSS类。

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

<table>
  <tr>
    <th>NAMEth>
    <th>PRICEth>
    <th>IN STOCKth>
  tr>
  <tr th:each="prod : ${prods}" th:class="${prodStat.odd}? 'odd'">
    <td th:text="${prod.name}">Onionstd>
    <td th:text="${prod.price}">2.41td>
    <td th:text="${prod.inStock}? #{true} : #{false}">yestd>
  tr>
table>

6.3 通过延迟检索数据进行优化

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

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

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

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

可以在不了解其惰性的情况下使用此变量，例如：

  
user name

但是同时，loadValue()如果在以下代码中condition计算为，则将永远不会初始化（永远不会调用其方法）false：

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

7 条件评估

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

有时，您需要模板的一部分才能仅在满足特定条件的情况下出现在结果中。

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

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

<table>
  <tr>
    <th>NAMEth>
    <th>PRICEth>
    <th>IN STOCKth>
    <th>COMMENTSth>
  tr>
  <tr th:each="prod : ${prods}" th:class="${prodStat.odd}? 'odd'">
    <td th:text="${prod.name}">Onionstd>
    <td th:text="${prod.price}">2.41td>
    <td th:text="${prod.inStock}? #{true} : #{false}">yestd>
    <td>
      <span th:text="${#lists.size(prod.comments)}">2span> comment/s
      <a href="comments.html" 
         th:href="@{/product/comments(prodId=${prod.id})}" 
         th:if="${not #lists.isEmpty(prod.comments)}">viewa>
    td>
  tr>
table>

在这里可以看到很多东西，所以让我们集中在重要的一行上：

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

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

让我们看一下结果标记：

<table>
  <tr>
    <th>NAMEth>
    <th>PRICEth>
    <th>IN STOCKth>
    <th>COMMENTSth>
  tr>
  <tr>
    <td>Fresh Sweet Basiltd>
    <td>4.99td>
    <td>yestd>
    <td>
      <span>0span> comment/s
    td>
  tr>
  <tr class="odd">
    <td>Italian Tomatotd>
    <td>1.25td>
    <td>notd>
    <td>
      <span>2span> comment/s
      <a href="/gtvg/product/comments?prodId=2">viewa>
    td>
  tr>
  <tr>
    <td>Yellow Bell Peppertd>
    <td>2.50td>
    <td>yestd>
    <td>
      <span>0span> comment/s
    td>
  tr>
  <tr class="odd">
    <td>Old Cheddartd>
    <td>18.75td>
    <td>yestd>
    <td>
      <span>1span> comment/s
      <a href="/gtvg/product/comments?prodId=4">viewa>
    td>
  tr>
table>

完善！这正是我们想要的。

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

• 如果value不为null：
  • 如果value是一个布尔值并且是true。
  • 如果value是一个数字且非零
  • 如果value是一个字符并且非零
  • 如果value是一个String且不是“ false”，“ off”或“ no”
  • 如果value不是布尔值，数字，字符或字符串。
• （如果value为null，则th：if的值为false）。

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

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

7.2 切换语句

还有一种方法可以使用Java 中的开关结构的等效条件来显示内容：th:switch/ th:case属性集。

<div th:switch="${user.role}">
  <p th:case="'admin'">User is an administratorp>
  <p th:case="#{roles.manager}">User is a managerp>
div>

请注意，一旦一个th:case属性的值为true，th:case同一切换上下文中的所有其他属性的值为false。

默认选项指定为th:case="*"：

  
User is an administrator
  
User is a manager
  
User is some other thing

8 模板布局

8.1 包括模板片段

定义和引用片段

在我们的模板中，我们经常需要包含其他模板中的部分，例如页脚，页眉，菜单等部分。

为了做到这一点，Thymeleaf需要我们定义这些要包含的部分“片段”，可以使用该th:fragment属性来完成。

假设我们要在所有杂货店页面中添加标准的版权页脚，因此我们创建一个/WEB-INF/templates/footer.html包含以下代码的文件：

 
<html xmlns:th="http://www.thymeleaf.org">
 
  <body>
  
    <div th:fragment="copy">
      © 2011 The Good Thymes Virtual Grocery
    div>
  
  body>
  
html>

上面的代码定义了一个片段copy，我们可以使用th:insert或th:replace属性之一轻松地将其包含在主页中（并且th:include，尽管从Thymeleaf 3.0开始不再建议使用它）：

<body>
 
  ...
 
  <div th:insert="~{footer :: copy}">div>
  
body>

请注意，th:insert需要一个片段表达式（{…}），这是一个产生片段的表达式。但是，在上面的示例中，它是一个非复杂的片段表达式，（{，}）包围是完全可选的，因此上面的代码等效于：

<body>
 
  ...
 
  <div th:insert="footer :: copy">div>
  
body>

片段规范语法

片段表达式的语法非常简单。有三种不同的格式：

• "{templatename::selector}"包括在名为的模板上应用指定的标记选择器所产生的片段templatename。请注意，该selector名称可能仅仅是片段名称，因此您可以{templatename::fragmentname}像~{footer :: copy}上面一样指定简单的名称。

标记选择器语法由基础的AttoParser解析库定义，并且类似于XPath表达式或CSS选择器。有关更多信息，请参见附录C。

• "~{templatename}"包括名为的完整模板templatename。

请注意，您在th:insert/ th:replace标记中使用的模板名称必须由模板引擎当前正在使用的模板解析器解析。

• {::selector}“或”{this::selector}"从同一模板插入一个片段，匹配selector。如果在出现表达式的模板上未找到，则将模板调用（插入）堆栈遍历到原始处理的模板（root），直到selector在某个级别上匹配为止。

双方templatename并selector在上面的例子可以是全功能的表达式（甚至条件语句！），如：

<div th:insert="footer :: (${user.isAdmin}? #{footer.admin} : #{footer.normaluser})">div>

再次注意周围的~{…}信封在th:insert/中是可选的th:replace。

片段可以包含任何th:*属性。一旦将片段包含到目标模板（带有th:insert/ th:replace属性的片段）中，就会评估这些属性，并且它们将能够引用此目标模板中定义的任何上下文变量。

这种片段处理方法的一大优势是，您可以将片段写在浏览器可以完美显示的页面中，并具有完整甚至有效的标记结构，同时仍保留使Thymeleaf将其包含在其他模板中的功能。

引用片段不带 th:fragment

由于标记选择器的强大功能，我们可以包含不使用任何th:fragment属性的片段。甚至可能是完全不了解Thymeleaf的来自不同应用程序的标记代码：

...
<div id="copy-section">
  © 2011 The Good Thymes Virtual Grocery
div>
...

我们可以使用上面的片段，简单地通过其id属性引用它，类似于CSS选择器：

<body>
 
  ...
 
  <div th:insert="~{footer :: #copy-section}">div>
  
body>

th:insert和th:replace（和th:include）之间的差异

和之间有什么区别th:insert和th:replace（和th:include，因为3.0不推荐）？

th:insert 最简单：它将简单地将指定的片段作为其host标签的主体插入。

th:replace实际上将其主机标签替换为指定的片段。

th:include与相似th:insert，但不插入片段，而是仅插入该片段的内容。

因此，HTML片段如下所示：

<footer th:fragment="copy">
  © 2011 The Good Thymes Virtual Grocery
footer>

…在主机

标签中包含了3次，如下所示：

<body>
 
  ...
 
  <div th:insert="footer :: copy">div>
 
  <div th:replace="footer :: copy">div>
 
  <div th:include="footer :: copy">div>
  
body>

…将导致：

<body>
 
  ...
 
  <div>
    <footer>
      © 2011 The Good Thymes Virtual Grocery
    footer>
  div>
 
  <footer>
    © 2011 The Good Thymes Virtual Grocery
  footer>
 
  <div>
    © 2011 The Good Thymes Virtual Grocery
  div>
  
body>

8.2 可参数化的片段签名

为了为模板片段创建更类似于函数的机制，使用定义的片段th:fragment可以指定一组参数：

<div th:fragment="frag (onevar,twovar)">
    <p th:text="${onevar} + ' - ' + ${twovar}">...p>
div>

这需要使用以下两种语法之一来从th:insert或调用片段th:replace：

<div th:replace="::frag (${value1},${value2})">...div>
<div th:replace="::frag (onevar=${value1},twovar=${value2})">...div>

请注意，在最后一个选项中顺序并不重要：

<div th:replace="::frag (twovar=${value2},onevar=${value1})">...div>

片段局部变量，不带片段参数

即使片段没有这样的参数定义：

<div th:fragment="frag">
    ...
div>

我们可以使用上面指定的第二种语法来调用它们（并且只有第二种）：

<div th:replace="::frag (onevar=${value1},twovar=${value2})">

这将相当于组合th:replace和th:with：

<div th:replace="::frag" th:with="onevar=${value1},twovar=${value2}">

请注意，这种对片段的局部变量的规范（无论它是否具有参数签名）都不会导致上下文在执行之前被清空。片段仍将能够像当前一样访问在调用模板中使用的每个上下文变量。

声明模板内断言

该th:assert属性可以指定一个逗号分隔的表达式列表，应对其进行评估，并为每次评估生成true，否则将引发异常。

<div th:assert="${onevar},(${twovar} != 43)">...div>

这对于验证片段签名中的参数非常有用：

<header th:fragment="contentheader(title)" th:assert="${!#strings.isEmpty(title)}">...header>

8.3 灵活的布局：不仅仅是插入片段

借助片段表达式，我们可以为片段指定参数，这些参数不是文本，数字，bean对象……而是标记片段。

这允许我们以一种方式来创建我们的片段，以便可以使用来自调用模板的标记来丰富它们，从而产生非常灵活的模板布局机制。

请注意以下片段中title和links变量的使用：

<head th:fragment="common_header(title,links)">
 
  <title th:replace="${title}">The awesome applicationtitle>
 
  
  <link rel="stylesheet" type="text/css" media="all" th:href="@{/css/awesomeapp.css}">
  <link rel="shortcut icon" th:href="@{/images/favicon.ico}">
  <script type="text/javascript" th:src="@{/sh/scripts/codebase.js}">script>
 
  
  <th:block th:replace="${links}" />
 
head>

现在，我们可以将该片段称为：

...
<head th:replace="base :: common_header(~{::title},~{::link})">
 
  <title>Awesome - Maintitle>
 
  <link rel="stylesheet" th:href="@{/css/bootstrap.min.css}">
  <link rel="stylesheet" th:href="@{/themes/smoothness/jquery-ui.css}">
 
head>
...

…结果将使用调用模板中的实际