Documentation
Frameworks
Spring
Thymeleaf

Thymeleaf

HTML 屬性對照表

標準表達式語法 (Standard Expression Syntax)

關鍵字描述範例
${...}變數表達式 (Variable Expression)${user.name}
*{...}選擇表達式 (Selection Expression)*{name}
#{...}消息表達式 (Message Expression)#{welcome.message}
@{...}連結表達式 (Link Expression)@{/user/profile}
~{...}片段表達式 (Fragment Expression)~{header :: menu}

標準屬性處理器 (Standard Attribute Processors)

關鍵字描述範例
th:text設定元件的文本內容<p th:text="${user.name}">Default Name</p>
th:utext設定未轉義的 HTML 內容<div th:utext="${htmlContent}">Default Content</div>
th:each迭代集合<tr th:each="user : ${users}">
th:if條件式顯示元素<div th:if="${not #lists.isEmpty(users)}">
th:unless條件式隱藏元素<div th:unless="${#lists.isEmpty(users)}">
th:switch/th:case多條件判斷<div th:switch="${user.role}"><p th:case="'admin'">Admin</p></div>
th:attr設定任意屬性<img th:attr="src=@{/images/logo.png},title=${logoTitle}">
th:value設定元件的 Value 值<input th:value="${user.name}">
th:action設定表單提交位址<form th:action="@{/user/save}">
th:href設定連結 URL<a th:href="@{/user/{id}(id=${user.id})}">
th:src設定媒體資源來源<img th:src="@{/images/logo.png}">
th:with定義區域變數<div th:with="isAdmin=${user.role == 'admin'}">

表單處理屬性 (Form Handling Attributes)

關鍵字描述範例
th:field繫結表單欄位<input type="text" th:field="*{name}">
th:errors顯示欄位驗證錯誤<span th:errors="*{name}">Name Error</span>
th:errorclass發生錯誤時添加 CSS 類別<input th:field="*{name}" th:errorclass="is-invalid">
th:selected設定選取狀態<option th:selected="${user.role=='admin'}">Admin</option>
th:checked設定核取狀態<input type="checkbox" th:checked="${user.active}">

迭代與條件屬性 (Iteration and Conditional Attributes)

關鍵字描述範例
th:each迭代集合<tr th:each="user, stat : ${users}">
th:if條件顯示<div th:if="${user.age > 18}">
th:unless條件隱藏<div th:unless="${user.age > 18}">
th:switch/th:case多條件切換<div th:switch="${user.role}"><p th:case="'admin'">Admin</p></div>

註釋與區塊屬性 (Comment and Block Attributes)

關鍵字描述範例
th:block範本片段處理容器<th:block th:each="user : ${users}">Content</th:block>
<!--/* ... */-->解析器層級註釋 (渲染時移除)<!--/* Removed during rendering */-->
<!--/*/-->…<!--/*/-->條件解析器區塊<!--/*/--> Only shown during processing <!--/*/-->

內聯表達式 (Inline Expressions)

關鍵字描述範例
[[...]]內聯文本<p>Welcome, [[${user.name}]]!</p>
[(...)]未轉義內聯文本<div>[(${htmlContent})]</div>
th:inline="text"在文本中使用表達式<script th:inline="text">var m = '[[${message}]]';</script>
th:inline="javascript"在 JS 中使用表達式<script th:inline="javascript">var u = [[${user}]];</script>
th:inline="css"在 CSS 中使用表達式<style th:inline="css">.u { color: [[${color}]]; }</style>

佈局屬性 (Layout Dialect Attributes)

關鍵字描述範例
layout:decorate指定裝飾範本<html layout:decorate="~{layouts/default}">
layout:fragment定義可替換的片段<div layout:fragment="content">Page Content</div>
layout:insert插入片段<div layout:insert="~{fragments/header :: header}"></div>
layout:replace替換片段<div layout:replace="~{fragments/footer :: footer}"></div>

工具函數 (Utility Functions)

類別前綴範例
字串#strings${#strings.isEmpty(name)}
數字#numbers${#numbers.formatDecimal(num, 1, 2)}
日期#dates, #calendars, #temporals${#dates.format(date, 'yyyy-MM-dd')}
集合#lists, #sets, #maps${#lists.size(users)}
陣列#arrays${#arrays.length(userArray)}

實用筆記 (Casual Notes)

  1. 資料顯示與處理

    • th:text: 最基礎的文本顯示。
    • th:utext: 用於顯示包含 HTML 標籤的內容。
    • ${...}: 變數表達式，存取 Model 資料。
    • *{...}: 選擇表達式，簡化長物件路徑。

  2. 條件與邏輯控制

    • th:if / th:unless: 根據條件決定元素是否輸出。
    • th:switch / th:case: 適合狀態機式的顯示邏輯。
    • th:with: 定義局部變數以簡化複雜表達式。

  3. 集合處理

    • th:each: 迭代資料，產生表格或清單。
    • th:object: 設定物件上下文。

  4. 格式化與特殊處理

    • #dates: 格式化日期。
    • #numbers: 處理金額、百分比等數字格式。
    • #strings: 字串修剪、替換等。

Flying Saucer (PDF 產生) 相關注意事項

  • 樣式處理:
    • 請使用內聯樣式 (Inline Style) 或內部 CSS，Flying Saucer 無法處理外部樣式表。
    • th:style 與 th:class 可用於動態設定樣式。
  • 分頁控制:
    • 使用 CSS 的 page-break-before, page-break-after 控制 PDF 分頁。
  • 圖片處理:
    • th:src 請使用絕對路徑，或確保路徑能被解析器正確識別。
SpringDoc OpenAPI (Swagger)