静态资源映射、Thymeleaf 模板、整合 Thymeleaf

1. 静态资源映射

    在 Web 应用中会涉及到大量的静态资源，例如 JS、CSS 和 HTML 等。我们知道，Spring MVC 导入静态资源文件时，需要配置静态资源的映射；但在 SpringBoot 中则不再需要进行此项配置，因为 SpringBoot 已经默认完成了这一工作。

    Spring Boot 默认为我们提供了 3 种静态资源映射规则：

        (1) 默认资源映射
        (2) 静态首页（欢迎页）映射
        (3) WebJars 映射

    1) 默认资源映射

        当访问项目中的任意资源（即“/**”）时，Spring Boot 会默认从以下路径中查找资源文件（优先级依次降低）：

            classpath:/META-INF/resources/
            classpath:/resources/
            classpath:/static/
            classpath:/public/

        这些路径又被称为静态资源文件夹。

        当请求某个静态资源时，Spring Boot 会先查找优先级高的文件夹，再查找优先级低的文件夹，直到找到指定的静态资源为止。

        示例，在 “” 里 SpringbootWeb 项目基础上，代码如下。

            创建 src/main/resources/static/test.html 文件

1                 
2                 
3                 
4                     "Content-Type" content="text/html; charset=UTF-8"/>
5                        
6                 
7                     
Test HTML Page
8                 
9                 

            访问：http://localhost:9090/test.html

    2) 静态首页（欢迎页）映射

        静态资源文件夹下的所有 index.html 被称为静态首页或者欢迎页，它们会被 /** 映射，当访问 "/" 或者 "/index.html" 时，都会跳转到静态首页（欢迎页）。
        
        注意，访问静态首页或欢迎页时，其查找顺序也遵循默认静态资源的查找顺序，即先查找优先级高的目录，在查找优先级低的目录，直到找到 index.html 为止。

        示例，在上文 SpringbootWeb 项目基础上，代码如下。

            创建 src/main/resources/static/index.html 文件

1                 
2                 
3                 
4                     "Content-Type" content="text/html; charset=UTF-8"/>
5                        
6                 
7                     
Index HTML Page
8                 
9                 

            访问：http://localhost:9090/ 或 http://localhost:9090/index.html

    3）WebJars 映射

        为了让页面更加美观，让用户有更多更好的体验，Web 应用中通常会使用大量的 JS 和 CSS，例如 jQuery、Bootstrap 等等。通常我们会将这些 Web 前端资源拷贝到 Java Web 项目的 webapp 相应目录下进行管理。但是 Spring Boot 项目是以 JAR 包的形式进行部署的，不存在 webapp 目录，那么 Web 前端资源该如何引入到 Spring Boot 项目中呢？

        WebJars 可以完美的解决上面的问题，它可以 Jar 形式为 Web 项目提供资源文件。

        WebJars 可以将 Web 前端资源（JS，CSS 等）打成一个个的 Jar 包，然后将这些 Jar 包部署到 Maven 中央仓库中进行统一管理，当 Spring Boot 项目中需要引入 Web 前端资源时，只需要访问 WebJars 官网 (https://www.webjars.org/)，找到所需资源的 pom 依赖，将其导入到项目中即可。

        所有通过 WebJars 引入的前端资源都存放在当前项目类路径（classpath）下的 "/META-INF/resources/webjars/" 目录中。

        示例，在上文 SpringbootWeb 项目基础上，代码如下。

            (1) 修改 pom.xml，将 jquery 引入到该项目中

                
                    ...
                    
                        ...

                        
                            org.webjars
                            jquery
                            3.6.0
                        

                        ...
                    
                
                    ...    
                

            (2) 修改 src/main/resources/static/test.html 文件

 1                 
 2                 
 3                 
 4                     "Content-Type" content="text/html; charset=UTF-8"/>
 5                     <script language="javascript" src="/webjars/jquery/3.6.0/jquery.js"></script>
 6                        
 7                 
 8                     
Test HTML Page
 9 
10                     <script type="text/javascript">
11                         $(document).ready(function() {
12                             console.log("Test HTML Page");
13                         });
14                     </script>
15                 
16                 

            访问：http://localhost:9090/test.html

2. Thymeleaf 模板

    Thymeleaf 是一款用于渲染 XML/XHTML/HTML5 内容的模板引擎。它与 JSP，Velocity，FreeMaker 等模板引擎类似，也可以轻易地与 Spring MVC 等 Web 框架集成。
    
    Thymeleaf 是新一代 Java 模板引擎，与 Velocity、FreeMarker 等传统 Java 模板引擎不同，Thymeleaf 支持 HTML 原型，其文件后缀为“.html”，因此它可以直接被浏览器打开，此时浏览器会忽略未定义的 Thymeleaf 标签属性，展示 thymeleaf 模板的静态页面效果；当通过 Web 应用程序访问时，Thymeleaf 会动态地替换掉静态内容，使页面动态显示。

    Thymeleaf 模板引擎具有以下特点：
    
        (1) 动静结合：Thymeleaf 既可以直接使用浏览器打开，查看页面的静态效果，也可以通过 Web 应用程序进行访问，查看动态页面效果；
        (2) 开箱即用：Thymeleaf 提供了 Spring 标准方言以及一个与 SpringMVC 完美集成的可选模块，可以快速的实现表单绑定、属性编辑器、国际化等功能；
        (3) 多方言支持：它提供了 Thymeleaf 标准和 Spring 标准两种方言，可以直接套用模板实现 JSTL、 OGNL 表达式；必要时，开发人员也可以扩展和创建自定义的方言；
        (4) 与 SpringBoot 完美整合：SpringBoot 为 Thymeleaf 提供了的默认配置，并且还为 Thymeleaf 设置了视图解析器，因此 Thymeleaf 可以与 Spring Boot 完美整合。

    Thymeleaf 通过在 html 标签中，增加额外属性来达到“模板+数据”的展示方式，示例代码如下。

 1         
 2         "en" xmlns:th="http://www.thymeleaf.org">
 3         
 4             "UTF-8">
 5             
 6         
 7         
 8             
 9             
"Welcome Thymeleaf">Welcome Static HTML
10         
11         

        当直接使用浏览器打开时，浏览器显示：

            欢迎您访问静态页面HTML

        当通过 Web 应用程序访问时，浏览器显示：

            迎您来到 Thymeleaf

    1) Thymeleaf 语法规则

        在使用 Thymeleaf 之前，首先要在页面的 html 标签中声明名称空间，示例代码如下。

            xmlns:th="http://www.thymeleaf.org"

        在 html 标签中声明此名称空间，可避免编辑器出现 html 验证错误，但这一步并非必须进行的，即使我们不声明该命名空间，也不影响 Thymeleaf 的使用。

        Thymeleaf 作为一种模板引擎，它拥有自己的语法规则。Thymeleaf 语法分为以下 2 类：

            (1) 标准表达式语法
            (2) th 属性

    2) 标准表达式语法

        Thymeleaf 模板引擎支持多种表达式：

            变量表达式：${...}
            选择变量表达式：*{...}
            链接表达式：@{...}
            国际化表达式：#{...}
            片段引用表达式：~{...}

        (1) 变量表达式，格式如下：

            使用 ${} 包裹的表达式被称为变量表达式，该表达式具有以下功能：

                获取对象的属性和方法
                使用内置的基本对象
                使用内置的工具对象
            
            a) 获取对象的属性和方法，表达式如下：

                ${person.lastName}

                获取 person 对象的 lastName 属性

            b) 使用内置的基本对象
 
                Thymeleaf 中常用的内置基本对象如下：

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

                例如，可以通过以下 2 种形式，都可以获取到 session 对象中的 map 属性：

                    ${#session.getAttribute('map')}
                    ${session.map}

            c) 使用内置的工具对象
            
                除了能使用内置的基本对象外，变量表达式还可以使用一些内置的工具对象。

                    strings：字符串工具对象，常用方法有：equals、equalsIgnoreCase、length、trim、toUpperCase、toLowerCase、indexOf、substring、replace、startsWith、endsWith，contains 和 containsIgnoreCase 等；
                    numbers：数字工具对象，常用的方法有：formatDecimal 等；
                    bools：布尔工具对象，常用的方法有：isTrue 和 isFalse 等；
                    arrays：数组工具对象，常用的方法有：toArray、length、isEmpty、contains 和 containsAll 等；
                    lists/sets：List/Set 集合工具对象，常用的方法有：toList、size、isEmpty、contains、containsAll 和 sort 等；
                    maps：Map 集合工具对象，常用的方法有：size、isEmpty、containsKey 和 containsValue 等；
                    dates：日期工具对象，常用的方法有：format、year、month、hour 和 createNow 等。

                例如，可以使用内置工具对象 strings 的 equals 方法，来判断字符串与对象的某个属性是否相等，代码如下。

                    ${#strings.equals('Tester',name)}           

        (2) 选择变量表达式

            选择变量表达式与变量表达式功能基本一致，只是在变量表达式的基础上增加了与 th:object 的配合使用。

            当使用 th:object 存储一个对象后，就可以在其子元素中使用选择变量表达式获取该对象中的属性，其中，"*" 代表该对象。

               

    3) th 属性

        Thymeleaf 还提供了大量的 th 属性，这些属性可以直接在 HTML 标签中使用，其中常用 th 属性及其示例如下表。

        属性                描述
        th:id        替换 HTML 的 id 属性，例如
        th:text        文本替换，转义特殊字符，例如

hello

 1                 
 2                 
"common::fragment-name">
 3                 
 4                 
"common::#fragment-id">
 5 
 6                 
 7                 
"common::fragment-name">
 8                 
 9                 
"common::#fragment-id">
10 
11                 
12                 
"common::fragment-name">
13                 
14                 
"common::#fragment-id">

 1                     
 2                     
"common::fragment-name(var1='insert-name',var2='insert-name2')">
 3                     
 4                     
"common::#fragment-id(var1='insert-id',var2='insert-id2')">
 5                     
 6                     
 7                     
"common::fragment-name(var1='replace-name',var2='replace-name2')">
 8                     
 9                     
"common::#fragment-id(var1='replace-id',var2='replace-id2')">
10                     
11                     
12                     
"common::fragment-name(var1='include-name',var2='include-name2')">
13                     
14                     
"common::#fragment-id(var1='include-id',var2='include-id2')">

1                     
2                     
"fragment-name(var1, var2)" id="fragment-id">
3                         
"'var1: ' + ${var1} + ', var2: ' + ${var2}">Empty
4                     

1         @Configuration(proxyBeanMethods = false)
2         @EnableConfigurationProperties({ThymeleafProperties.class})
3         @ConditionalOnClass({TemplateMode.class, SpringTemplateEngine.class})
4         @AutoConfigureAfter({WebMvcAutoConfiguration.class, WebFluxAutoConfiguration.class})
5         public class ThymeleafAutoConfiguration {
6 
7         }

 1         @ConfigurationProperties(prefix = "spring.thymeleaf")
 2         public class ThymeleafProperties {
 3             private static final Charset DEFAULT_ENCODING;
 4             public static final String DEFAULT_PREFIX = "classpath:/templates/";
 5             public static final String DEFAULT_SUFFIX = ".html";
 6             private boolean checkTemplate = true;
 7             private boolean checkTemplateLocation = true;
 8             private String prefix = "classpath:/templates/";
 9             private String suffix = ".html";
10             private String mode = "HTML";
11             private Charset encoding;
12             private boolean cache;
13             
14             ...
15         }

 1             
 2                 ...
 3                 
 4                     ...
 5 
 6                     
 7                     
 8                         org.springframework.boot
 9                         spring-boot-starter-thymeleaf
10                     
11                     
12                     ...
13                 
14             
15                 ...    
16             

 1             
 2             "en" xmlns:th="http://www.thymeleaf.org">
 3             
 4                 "UTF-8">
 5                 
 6             
 7             
 8                 
 9                 
"'Welcome ' + ${name}">
10             
11             

 1             package com.example.controller;
 2 
 3             import java.util.Map;
 4             import org.springframework.stereotype.Controller;
 5             import org.springframework.web.bind.annotation.RequestMapping;
 6 
 7             @Controller
 8             public class IndexController {
 9                 @RequestMapping("/demo")
10                 public String demo(Map map) {
11                     map.put("name", "admin");
12                     return "demo";
13                 }
14             }