Spring Boot （二）：模版引擎 Thymeleaf 渲染 Web 頁面

• 2019 年 10 月 3 日
• 筆記

Spring Boot （二）：模版引擎 Thymeleaf 渲染 Web 頁面

在《Spring Boot（一）：快速開始》中介紹了如何使用 Spring Boot 構建一個工程，並且提供 RESTful API ，本節我們繼續介紹如何使用 Spring Boot 渲染 Web 頁面。

1. 什麼是 Thymeleaf ？

雖然我們目前擁有許多十分優秀的前端框架，例如： Vue 、 React 等，非常適用於前後端分離的場景，前端可以獨立部署成為服務，前後端從物理上完全進行隔離，降低程式耦合度。但是 Spring Boot 官方依然為我們提供了模版引擎用於一些無需前後端分離的場景。 Thymeleaf 是新一代的模板引擎，在 Spring Boot 中，官方推薦使用 Thymeleaf 來做前端模版引擎。打開 https://start.spring.io/ 可以看到，在當前Spring Boot 的版本中（ 2.1.8.RELEASE ）， 官方提供的模版引擎有以下幾種：

• Thymeleaf
• FreeMarker
• Mustache
• Groovy

Spring Boot 建議使用這些模版引擎，而並不推薦我們繼續使用 JSP 。

Thymeleaf 具體特性如下：

• Thymeleaf 在有網路和無網路的環境下皆可運行，即它可以讓美工在瀏覽器查看頁面的靜態效果，也可以讓程式設計師在伺服器查看帶數據的動態頁面效果。這是由於它支援 html 原型，然後在 html 標籤里增加額外的屬性來達到模板+數據的展示方式。瀏覽器解釋 html 時會忽略未定義的標籤屬性，所以 Thymeleaf 的模板可以靜態地運行；當有數據返回到頁面時，Thymeleaf 標籤會動態地替換掉靜態內容，使頁面動態顯示。
• Thymeleaf 開箱即用的特性。它提供標準和 Spring 標準兩種方言，可以直接套用模板實現 JSTL、 OGNL表達式效果，避免每天套模板、改 Jstl、改標籤的困擾。同時開發人員也可以擴展和創建自定義的方言。
• Thymeleaf 提供 Spring 標準方言和一個與 SpringMVC 完美集成的可選模組，可以快速的實現表單綁定、屬性編輯器、國際化等功能。

2. 快速入門

這裡我們先正常構建一個 Spring Boot 工程： spring-boot-thymeleaf ，在 pom.xml 文件中引入 Thymeleaf 的相關依賴，如下：

<dependency>      <groupId>org.springframework.boot</groupId>      <artifactId>spring-boot-starter-thymeleaf</artifactId>  </dependency>

工程的配置文件 application.yml 如下：

server:    port: 8080  spring:    application:      name: spring-boot-thymleaf    thymeleaf:      # 關閉thymeleaf快取 開發時使用 否則沒有實時畫面      cache: false      # 檢查模板是否存在，然後再呈現      check-template-location: true      # Content-Type value.      servlet:        content-type: text/html      # 啟用MVC Thymeleaf視圖解析度      enabled: true      # Template encoding.      encoding: UTF-8      # 關閉嚴格模式      mode: LEGACYHTML5      # Prefix that gets prepended to view names when building a URL.      prefix: classpath:/templates/      # Suffix that gets appended to view names when building a URL.      suffix: .html    mvc:      # 指定靜態資源處理路徑      static-path-pattern: /static/**      view:        suffix: .html

有關 thymeleaf 都寫明了注釋，這裡需要注意的有以下幾點：

• spring.thymeleaf.mode ：這裡是配置當前模版的解析模式的，默認值為 HTML ，這時會開啟嚴格模式，所有的 HTML 必須有頭有尾，很多地方並不符合我們平時的書寫習慣，這裡最好關閉嚴格模式。
• spring.thymeleaf.cache ：這裡是 thymeleaf 的快取，在平時的練習中最好關閉，否則頁面修改後刷新瀏覽器將會無效，而在生產環境中，視具體的業務場景而定。
• spring.mvc.static-path-pattern ：這裡是配置我們靜態資源的路徑，一般默認是配置 /static/** 路徑，這裡用於存放我們的 js 、 css 、圖片等靜態資源。

配置通用 404 和 500 頁面，直接在 templateserror 創建對應頁面即可，這裡可以看一下 Spring Boot 錯誤頁面轉發的源碼 org.springframework.boot.autoconfigure.web.servlet.error.DefaultErrorViewResolver，如下：

@Override  public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) {      ModelAndView modelAndView = resolve(String.valueOf(status.value()), model);      if (modelAndView == null && SERIES_VIEWS.containsKey(status.series())) {          modelAndView = resolve(SERIES_VIEWS.get(status.series()), model);      }      return modelAndView;  }    private ModelAndView resolve(String viewName, Map<String, Object> model) {      String errorViewName = "error/" + viewName;      TemplateAvailabilityProvider provider = this.templateAvailabilityProviders.getProvider(errorViewName,              this.applicationContext);      if (provider != null) {          return new ModelAndView(errorViewName, model);      }      return resolveResource(errorViewName, model);  }

可以看到這裡會根據當前的狀態響應碼轉發到對應的頁面，路由為 error/** 。筆者這裡簡單創建兩個錯誤頁面，如圖：

創建測試 Controller ，如下：

@Controller  public class HelloController {        @GetMapping("/hello")      public String hello(HttpServletRequest request) {          // 構建測試數據          Map<String, Object> map = new HashMap<>();            UserModel userModel = new UserModel();          userModel.setId(1L);          userModel.setName("Spring Boot");          userModel.setAge(18);            map.put("user", userModel);            List<CourseModel> list = new ArrayList<>();            for (int i = 0; i < 2; i++) {              CourseModel courseMode = new CourseModel();              courseMode.setId((long) i);              courseMode.setName("Spring Boot：" + i);              courseMode.setAddress("課程地點：" + i);              list.add(courseMode);          }            map.put("list", list);            map.put("flag", true);            request.setAttribute("data", map);          return "hello";      }  }

在此註冊測試類中，進行數據初始化並輸出至頁面。

• Thymeleaf 默認的模板路徑 src/main/resources/templates ，只需要在這個這個路徑下編寫模版文件即可。

Thymeleaf 模版文件如下：

<!DOCTYPE html>  <html xmlns="http://www.w3.org/1999/xhtml"        xmlns:th="http://www.thymeleaf.org">  <head>      <meta charset="UTF-8">      <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">      <title>Hello Spring Boot</title>      <link rel="stylesheet" th:href="@{/static/css/bootstrap.min.css}">  </head>  <body>  <div class="container">      <div>用戶資訊：</div>      <table class="table table-dark">          <thead>          <tr>              <th scope="col">#</th>              <th scope="col">姓名</th>              <th scope="col">年齡</th>          </tr>          </thead>          <tbody>          <tr>              <th scope="row" th:text="${data.user.id}"></th>              <td th:text="${data.user.name}"></td>              <td th:text="${data.user.age}"></td>          </tr>          </tbody>      </table>      <div>課程資訊：</div>      <table class="table table-dark">          <thead>          <tr>              <th scope="col">#</th>              <th scope="col">課程名稱</th>              <th scope="col">課程地點</th>          </tr>          </thead>          <tbody>          <tr th:each="course, iterStat : ${data.list}">              <th scope="row" th:text="${course.id}"></th>              <td th:text="${course.name}"></td>              <td th:text="${course.address}"></td>          </tr>          </tbody>      </table>        <div th:if="${data.flag == true}">如果 flag 為 true 你將可以看到這行字：）</div>    </div>    </body>  </html>

Thymeleaf 部分常用 th 標籤如下：

3. 測試

啟動當前工程，打開瀏覽器訪問路徑： http://localhost:8080/hello ，結果如圖：

5. 程式碼示例

示例程式碼-Github

示例程式碼-Gitee

6. 參考

《Thymeleaf 使用詳解》