このチートシートでは、Spring Bootと連携して使うThymeleafの基本的な構文や使い方を一通り確認できます。変数の出力、条件分岐、ループ処理、フォームとの連携、共通パーツの再利用、JavaScriptとの連携まで、実践的なテンプレート開発に必要な知識を網羅的に確認できます。
困ったらこのシート見れば解決できます！
1. テキストの出力 th:text
HTMLに変数の内容を出力したいとき
<p th:text="${message}">ここは上書きされます</p>→ ${message} の内容が出力され、タグ内の「ここは上書きされます」は無視されます（サーバーサイドで完全に置換）。
2. 属性の動的設定 th:attr, th:href, th:src など
aタグやimgタグのリンク先や画像パスも動的に
<a th:href="@{/hello}">リンク</a>
<img th:src="@{/images/logo.png}" />→ @{} はURLの構築用。クエリパラメータも渡せます。 例：@{/search(q=${keyword})} → /search?q=xxx
3. 条件分岐 th:if, th:unless
表示・非表示の切り替えが簡単に可能
<p th:if="${isAdmin}">管理者メニュー</p>
<p th:unless="${isAdmin}">一般メニュー</p>→ th:if は条件を満たすと表示。th:unless は逆に「条件を満たさないとき」に表示。
4. ループ処理 th:each
リストや配列をぐるぐる回して表示したいとき
<ul>
<li th:each="user : ${userList}" th:text="${user.name}">名前</li>
</ul>→ userList がリストなら、1人ずつ取り出して user.name を表示。
使える変数：
* ${userStat.index} // インデックス（0スタート）
* ${userStat.count} // 1スタートの番号
* ${userStat.size} // 全体のサイズ
* ${userStat.first} // 最初の要素か？
* ${userStat.last} // 最後の要素か？5. 入力フォームの連携 th:field
Spring MVCのFormクラスと連携するときに便利
<form th:action="@{/submit}" th:object="${form}" method="post">
<input type="text" th:field="*{name}" />
</form>→ form.getName() の値をバインドし、POST時にも送信されます。
6. 定数やユーティリティの利用
よく使う定数や日付の書式など、便利機能がある
<p th:text="${T(java.lang.Math).random()}">ランダム</p>
<p th:text="${#dates.format(today, 'yyyy/MM/dd')}">日付</p>ユーティリティオブジェクト例：
- dates：日付処理
- strings：文字列操作（空チェックなど）
- lists, #maps, #arrays：コレクション処理
- numbers：数値フォーマット
- bools：真偽値の判定
- objects：nullチェックやequals比較
7. フラグメントの再利用 th:replace, th:include, th:insert
ヘッダーやフッターなど共通パーツを再利用
<!-- ヘッダーを挿入 -->
<div th:replace="fragments/header :: headerFragment"></div>→ fragments/header.html の中に <div th:fragment="headerFragment"> を定義しておく。
th:replace：完全に置き換える（外側のタグ含む）th:insert：内側に差し込むth:include（非推奨）：古い書き方
8. コメントと無視されるコード（コメントアウト）
HTMLに残したくないコメントや、一時的な無効化に使える
<!--/* これはThymeleaf専用コメントでHTMLには出力されません */-->9. 三項演算子とnull対策
シンプルな条件分岐やnull安全なコードも書ける
<span th:text="${user.name != null ? user.name : '名前未設定'}"></span>
<span th:text="${user.name ?: '未入力'}"></span> <!-- null合体演算 -->10. th:object との組み合わせでネストされたプロパティもOK
<form th:object="${form}">
<input th:field="*{address.city}" />
</form>→ form.getAddress().getCity() にバインドされます。
11. テーブルのループ表示（実践例）
<table>
<thead>
<tr><th>#</th><th>名前</th><th>年齢</th></tr>
</thead>
<tbody>
<tr th:each="user, stat : ${userList}">
<td th:text="${stat.count}"></td>
<td th:text="${user.name}"></td>
<td th:text="${user.age}"></td>
</tr>
</tbody>
</table>→ stat.count で行番号を出せる便利パターン。
12. JavaScriptとの連携 th:inline="javascript"
<script th:inline="javascript">
let username = [[${user.name}]];
</script>→ HTMLでは展開されないが、JS変数にサーバー値を埋め込める。
13. セレクトボックスの表示
<select th:field="*{gender}">
<option value="M">男性</option>
<option value="F">女性</option>
</select>→ th:field を使えば、Java側の値に応じて該当する <option> が自動で選択された状態になります。
14. チェックボックスやラジオボタン
<input type="checkbox" th:field="*{agree}" />
<input type="radio" th:field="*{type}" value="A" /> A
<input type="radio" th:field="*{type}" value="B" /> B→ 値が自動バインドされ、選択状態も反映される。
🧼 よくある間違いと対策
th:text="${user.name}"を書いたのにHTMLで反映されない →application.propertiesにspring.thymeleaf.cache=falseを忘れていませんか？<input type="text" value="..." th:value="...">のように両方書くと動かない →value属性はth:valueで上書きされます。重複に注意。- HTMLタグが壊れる →
<html>や<head>に Thymeleaf属性を入れるときは正しいDOCTYPEやxmlnsの設定を忘れずに。 - フラグメントが見つからない →
::の右側はth:fragment名を正確に！ファイルパスや拡張子も注意。
まとめ
ThymeleafはHTMLに自然に組み込めるテンプレートエンジンで、th:属性を使えば、Javaオブジェクトの出力、条件分岐、繰り返し、フォームのバインディングまで、すべて直感的に書けます。HTMLとしてもそのまま見えるので、デザイナーとの協業にも向いています。困ったら「何を出力したいか」「どんな条件で表示したいか」から逆算して、th:text, th:if, th:each などの属性を思い出しましょう。
コメント