Thymeleafの基本構文（入門）初心者でもわかる使い方ガイド
新人
「Thymeleafって何ですか？HTMLと一緒にどうやって使うんでしょうか？」
先輩
「ThymeleafはHTML内でJavaのデータを埋め込んで表示できるテンプレートエンジンだよ。Spring Bootと組み合わせると、Webアプリの画面を簡単に作れるんだ。」
新人
「どうやって書けばいいのかイメージがつきません。簡単に教えてもらえますか？」
先輩
「それじゃあ、基本構文から順に説明していくね！」
1. Thymeleafとは？
Thymeleaf（タイムリーフ）は、HTMLテンプレートエンジンで、Webアプリケーション開発においてJavaコードからHTMLファイルにデータを埋め込むために使用されます。特にSpring Bootとの相性が良く、HTMLをそのままブラウザで表示してもエラーにならない「自然なテンプレート」が特徴です。
Thymeleafの主なメリット:
- HTMLファイルをブラウザで直接確認できる
- HTMLタグのままテンプレート処理ができる
- 条件分岐やループ処理が簡単に記述可能
- Spring Bootとの統合が簡単で便利
2. Thymeleafの基本構文の概要
Thymeleafでは、HTMLタグ内に専用の属性を追加して、Javaから渡されたデータを表示したり処理したりできます。以下でよく使われる基本構文を紹介します。
2.1 テキスト表示：th:text
th:text属性は、HTML要素内にテキストを表示するために使用します。以下は基本的な使い方です。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>テキスト表示例</title>
</head>
<body>
<h1 th:text="${message}">デフォルトメッセージ</h1>
</body>
</html>
このコードでは、Javaのコントローラで指定したmessage変数の値が表示されます。
2.2 属性変更：th:hrefとth:src
リンクや画像のパスを動的に変更したいときに使用します。
<a th:href="@{/home}">ホームへ</a>
<img th:src="@{/images/logo.png}" alt="ロゴ">
上記では、@{/home}がURLに変換され、ブラウザでリンクが機能します。
2.3 条件分岐：th:ifとth:unless
表示する要素を条件付きで切り替えることができます。
<p th:if="${isLoggedIn}">ようこそ、ユーザーさん！</p>
<p th:unless="${isLoggedIn}">ログインしてください。</p>
2.4 繰り返し処理：th:each
リストや配列をループして表示する場合に使用します。
<ul>
<li th:each="item : ${items}" th:text="${item}"></li>
</ul>
このコードは、コントローラから渡されたitemsリスト内の要素をリスト形式で表示します。
2.5 コメントの書き方
Thymeleaf専用のコメントは以下のように書きます。ブラウザには表示されません。
<!--/* これはThymeleaf専用のコメントです */-->
2.6 値の代入：th:with
テンプレート内で変数を定義したい場合に便利です。
<div th:with="greeting='こんにちは！'">
<p th:text="${greeting}"></p>
</div>
3. テキスト表示の基本構文
Thymeleafでは、Javaの変数や値をHTMLに表示するためにth:textをよく使用します。これは画面にデータを出力するときの基本的な構文です。
3.1 th:textの使い方
th:text属性は、HTMLタグ内のテキストを動的に変更するのに使います。例えば、ユーザーにメッセージを表示する場合に便利です。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>メッセージ表示</title>
</head>
<body>
<h1 th:text="${message}">デフォルトメッセージ</h1>
</body>
</html>
上記のコードでは、Java側のコントローラからmessage変数が渡されます。コントローラ側は以下のように記述します。
@Controller
public class MessageController {
@GetMapping("/message")
public String showMessage(Model model) {
model.addAttribute("message", "こんにちは、Thymeleaf！");
return "message";
}
}
ブラウザでhttp://localhost:8080/messageにアクセスすると、"こんにちは、Thymeleaf！"と表示されます。
4. 変数の埋め込み方法
Thymeleafでは、Javaの変数をHTMLに埋め込むことが簡単にできます。ここでは、テキストや属性への埋め込み方法を紹介します。
4.1 テキストへの変数埋め込み
th:textを使うことで、変数の値を直接HTMLに埋め込めます。
<p th:text="${userName}">デフォルトユーザー</p>
コントローラ側では次のように設定します。
@GetMapping("/user")
public String user(Model model) {
model.addAttribute("userName", "山田太郎");
return "user";
}
結果として、「山田太郎」が画面に表示されます。
4.2 属性への変数埋め込み
リンクや画像のパスに変数を埋め込みたい場合は、th:hrefやth:srcを使用します。
<a th:href="@{'/profile/' + ${userId}}">プロフィールへ</a>
<img th:src="@{'/images/' + ${imageName}}" alt="ユーザー画像">
これにより、ユーザーごとに異なるリンクや画像を表示できます。
5. 条件分岐と繰り返し構文
Thymeleafでは、条件によって表示を切り替えたり、リストを繰り返し表示することが可能です。
5.1 条件分岐（th:if と th:unless）
th:ifは条件が真のとき、th:unlessは偽のときに要素を表示します。
<p th:if="${isLoggedIn}">ようこそ、ユーザーさん！</p>
<p th:unless="${isLoggedIn}">ログインしてください。</p>
コントローラ側のコード例:
@GetMapping("/login-status")
public String loginStatus(Model model) {
model.addAttribute("isLoggedIn", true); // または false
return "status";
}
ログイン状態に応じてメッセージが変わります。
5.2 繰り返し構文（th:each）
th:eachはリストや配列をループして表示する際に使います。
<ul>
<li th:each="item : ${items}" th:text="${item}"></li>
</ul>
コントローラで次のように設定します。
@GetMapping("/items")
public String itemList(Model model) {
List<String> items = List.of("りんご", "バナナ", "みかん");
model.addAttribute("items", items);
return "items";
}
ブラウザで確認すると、以下のリストが表示されます。
- りんご
- バナナ
- みかん
6. 属性値の操作方法（th:href, th:srcなど）
Thymeleafでは、HTMLタグの属性値を動的に変更することができます。特にリンク先や画像パスを動的に生成する場合、th:hrefやth:srcをよく使用します。
6.1 th:hrefの使い方
リンクのhref属性を動的に変更するには、th:hrefを使います。以下は基本的な例です。
<a th:href="@{/home}">ホームへ戻る</a>
このコードは、/homeへのリンクを生成します。さらに、動的にユーザーIDを付与することも可能です。
<a th:href="@{'/user/' + ${userId}}">プロフィール</a>
例えば、userIdが123の場合、リンクは/user/123になります。
6.2 th:srcの使い方
画像表示に使うsrc属性も、th:srcで動的に設定できます。
<img th:src="@{'/images/' + ${imageName}}" alt="ユーザー画像">
たとえば、imageNameがavatar.pngの場合、表示される画像は/images/avatar.pngとなります。
7. フォーム入力とデータ送信の基本
Webアプリケーションでは、ユーザーからの入力を受け取って処理することが重要です。Thymeleafは、Spring Bootと組み合わせて簡単にフォームを作成し、データを送信できます。
7.1 簡単なフォームの作成
以下は、名前を入力して送信するシンプルなフォームの例です。
<form th:action="@{/submit}" method="post">
<label for="name">名前:</label>
<input type="text" id="name" name="name" th:value="${name}">
<button type="submit">送信</button>
</form>
th:actionで送信先URLを指定し、th:valueで初期値を設定できます。
7.2 コントローラの作成
データを受け取るために、Spring Bootのコントローラを用意します。
@Controller
public class FormController {
@GetMapping("/form")
public String showForm(Model model) {
model.addAttribute("name", "");
return "form";
}
@PostMapping("/submit")
public String submitForm(@RequestParam String name, Model model) {
model.addAttribute("message", name + "さん、送信ありがとうございます！");
return "result";
}
}
/formでフォーム画面を表示し、/submitでデータを受け取ります。
7.3 送信結果の表示
送信後、result.htmlでメッセージを表示します。
<p th:text="${message}">ここにメッセージが表示されます</p>
ユーザーが「田中」と入力した場合、画面には「田中さん、送信ありがとうございます！」と表示されます。
8. よくあるエラーとその解決方法
Thymeleafを使う際に、初心者が遭遇しやすいエラーと解決策をまとめました。
8.1 "Template not found" エラー
原因: 指定したHTMLファイルがtemplatesフォルダ内に存在しない。
解決方法: ファイル名が正しいか確認し、resources/templates内に配置されていることを確認してください。
8.2 "Could not resolve placeholder" エラー
原因: コントローラで渡した変数がテンプレートに存在しない場合に発生します。
解決方法: model.addAttribute("message", "値")が正しく記述されているか確認してください。
8.3 th:eachが正しく動作しない
原因: 渡すリストがnullまたは空の場合。
解決方法: コントローラ側で必ず初期化してください。
@GetMapping("/items")
public String itemList(Model model) {
List<String> items = List.of("りんご", "バナナ", "みかん");
model.addAttribute("items", items);
return "items";
}
8.4 "HTTP 404" エラー
原因: URLが間違っているか、コントローラが適切にマッピングされていない場合。
解決方法: コントローラの@GetMappingやURLを再確認してください。
この記事を読んだ人からの質問
