Thymeleaf とは？初心者向けにThymeleafの基本を徹底解説
新人
「Thymeleaf ってどんなテンプレートエンジンなんですか？」
先輩
「Thymeleaf は Java と密に連携して使える HTML テンプレートエンジンで、特に Spring や Pleiades 環境でよく使われています。」
新人
「Spring のプロジェクトで Pleiades＋Gradle の環境下でも動かせますか？」
先輩
「はい。Pleiades で作成した Gradle プロジェクトに依存追加すれば、@Controller を使って Thymeleaf テンプレートをレンダリングできますよ。」
新人
「なるほど。では Thymeleaf の基本的な特徴から教えてください！」
1. Thymeleaf とは？
Thymeleaf（タイムリーフ）は Java 向けのサーバサイド HTML テンプレートエンジンです。Spring や Pleiades のプロジェクトで使いやすく、Gradle を使った依存管理にも対応しています。HTML の中に th:* 属性を付けることで、動的に値を埋め込んだり、条件分岐や繰り返し表示が可能です。特に HTML 骨格を崩さずに記述できるため、テンプレートの可読性が高く、開発者やデザイナー両方に優しい設計が特長です。
公式ドキュメントや SEO 観点でも「Thymeleaf テンプレート」「Thymeleaf Spring」「Thymeleaf Gradle」「Thymeleaf 使い方」などのキーワードで検索されやすく、初心者にも情報が体系的に整理されています。
2. Thymeleaf がどのように Java 開発に役立つのか
Thymeleaf は Spring Boot（Spring MVC）プロジェクトで標準的にサポートされており、@Controller アノテーションを使ったハンドラーメソッドからテンプレート名を返すだけで HTML をレンダリングできます。Pleiades で作成した開発環境でも、Gradle の dependencies に下記を追加すればすぐに動作します。
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
この設定により、Thymeleaf が自動的にテンプレートフォルダー（通常は src/main/resources/templates）から HTML ファイルを読み込んで、変数や構造を処理してくれます。
さらに、Gradle プロジェクトにおける依存管理も Pleiades の GUI チェックで完結できるため、初心者でも迷わずに実装できます。「Thymeleaf コントローラ」「Thymeleaf Gradle 設定」「Thymeleaf Pleiades 連携」などのキーワードで検索されやすく、情報も豊富です。
次のセクションでは、実際の Thymeleaf の基本構文（th:text、th:if、th:each など）を使ったサンプルコードを見ていきましょう。
3. Thymeleaf の基本構文（th:if、th:each、th:text など）
Thymeleaf は HTML 内に th:* 属性を使って動的に処理を指定できるテンプレートエンジンです。まずは代表的な構文を初心者向けにやさしく解説します。
● th:text でテキストを埋め込む
HTML 要素の中に Java の変数値を表示したいときに使います。以下のように Spring の @Controller でモデルに追加した値をテンプレートに渡します。
@Controller
public class HomeController {
@GetMapping("/")
public String home(Model model) {
model.addAttribute("message", "こんにちは、Thymeleaf！");
return "index";
}
}
<p th:text="${message}">ここにメッセージが入ります</p>
● th:if で条件分岐
表示条件を指定したい場合に使います。null チェックや真偽値にも対応できます。
<p th:if="${user != null}">ようこそ、<span th:text="${user.name}">ユーザ名</span>さん！</p>
<p th:unless="${user != null}">ログインしていません。</p>
● th:each でループ処理
リストを繰り返して表示するときに便利です。index を使ったカウンター表示にも対応します。
@GetMapping("/items")
public String items(Model model) {
List<String> items = List.of("リンゴ", "バナナ", "オレンジ");
model.addAttribute("items", items);
return "items";
}
<ul>
<li th:each="item, iterStat : ${items}">
<span th:text="${iterStat.index + 1}">1</span>. <span th:text="${item}">果物</span>
</li>
</ul>
このように th:text、th:if、th:each を組み合わせることで、条件付き表示や繰り返し表示が簡単に実現できます。これが Thymeleaf の強みです。
4. Spring Boot プロジェクトでの Thymeleaf 設定と利用例
Gradle と Pleiades 環境下で Spring Boot プロジェクトに Thymeleaf を導入する手順を解説します。開発者が迷わないようにステップごとに説明します。
1. Gradle の依存追加
Pleiades の GUI で dependencies チェックを入れるか、build.gradle に記載して追加します。
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
implementation 'org.springframework.boot:spring-boot-starter-web'
}
これにより、Spring MVC と連携して Thymeleaf テンプレートが使えるようになります。Pleiades 環境では自動で依存解決され、設定が簡単です。
2. テンプレートファイルの配置
HTML ファイルは src/main/resources/templates フォルダーに配置します。例として greeting.html を作成します。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>挨拶ページ</title>
</head>
<body>
<h1 th:text="${greeting}">ここに挨拶が入ります</h1>
</body>
</html>
3. コントローラでの処理
@Controller を使って値をセットし、テンプレート名を返します。Spring Boot と Thymeleaf の基本的な連携です。
@Controller
public class GreetingController {
@GetMapping("/greet")
public String greet(Model model) {
model.addAttribute("greeting", "おはようございます、Thymeleaf！");
return "greeting";
}
}
5. Thymeleaf を使った簡単なテンプレートのサンプル
ここでは、複数の構文を組み合わせた実践例を紹介します。リスト表示と条件分岐、リンクの埋め込みを含む簡単なサンプルです。
@Controller
public class TaskController {
@GetMapping("/tasks")
public String tasks(Model model) {
List<Task> tasks = List.of(
new Task("買い物", false),
new Task("メール返信", true),
new Task("レポート作成", false)
);
model.addAttribute("tasks", tasks);
return "tasks";
}
}
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>タスク一覧</title></head>
<body>
<h2>タスク一覧</h2>
<ul>
<li th:each="task : ${tasks}">
<span th:text="${task.name}">タスク名</span>
<span th:if="${task.completed}" th:text="'完了済'">状態</span>
<span th:unless="${task.completed}">未完了</span>
</li>
</ul>
</body>
</html>
6. Thymeleaf を使うメリット（可読性の高さ、学習コストの低さなど）
Thymeleaf の魅力の一つは、テンプレートの可読性が非常に高い点です。HTML をそのままブラウザで確認しながら開発できるため、フロントエンドとバックエンドの連携がスムーズに進みます。これは HTML の骨格を壊さずに、Java のデータを埋め込める th:* 構文の設計が大きな理由です。
また、Java の初心者でも理解しやすいシンプルな書き方が用意されており、Spring Boot のプロジェクトに最初から組み込まれていることが多いため、設定の手間が少ないのも特徴です。Pleiades の GUI 操作で依存関係を簡単に追加できるため、学習コストが低く、迷わずに始められます。
「Thymeleaf メリット」「Thymeleaf 学びやすさ」などのキーワードで検索しても多くの情報が見つかり、初心者向けの資料も豊富に揃っています。
7. よくあるエラーとその対処法
Thymeleaf を学ぶ際によく直面するエラーについても、あらかじめ知っておくと安心です。特に Spring Boot と連携する際の代表的なエラーをまとめました。
1. テンプレートファイルが見つからない
Thymeleaf のテンプレートは src/main/resources/templates に配置する必要があります。間違った場所に配置すると下記のようなエラーが出ることがあります。
org.thymeleaf.exceptions.TemplateInputException: Error resolving template [index], template might not exist
対処法として、ファイルパスを確認し、正しいフォルダに置くことが大切です。
2. 変数が null で表示されない
モデルに値が入っていないとき、th:text で空文字やエラーになる場合があります。@Controller 側で model.addAttribute を忘れずに記述しましょう。
@Controller
public class SampleController {
@GetMapping("/sample")
public String sample(Model model) {
model.addAttribute("text", "サンプルテキスト");
return "sample";
}
}
3. Thymeleaf の構文エラー
HTML に th:* 属性を入れたときに、閉じタグの書き忘れや構文ミスがあると、表示が崩れたり動かなくなることがあります。Pleiades で HTML ファイルの構文チェックを有効にし、細かいミスを見逃さないようにしましょう。
8. Thymeleaf を学ぶためのおすすめの方法
最後に、Thymeleaf をさらに深く理解するための勉強方法を紹介します。まずは公式ドキュメントを読み込むことがおすすめです。特に「Thymeleaf チュートリアル」「Thymeleaf Spring Boot 連携」などのキーワードで調べると、初心者向けの記事が多数見つかります。
また、Pleiades の環境で自分で簡単なテンプレートを作りながら、th:text や th:if を試すことも大事です。例えば「お知らせ一覧ページ」や「簡単なプロフィール表示ページ」など、実践的な題材を作ると理解が深まります。
サンプルプロジェクトを作って学ぶ
以下は簡単なサンプルプロジェクトを Gradle で作成し、Pleiades で動かす流れの例です。テンプレートの作り方や @Controller の使い方を総復習できます。
@Controller
public class ProfileController {
@GetMapping("/profile")
public String profile(Model model) {
model.addAttribute("name", "山田太郎");
model.addAttribute("age", 25);
return "profile";
}
}
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>プロフィール</title>
</head>
<body>
<h1>プロフィール</h1>
<p>名前: <span th:text="${name}">ここに名前</span></p>
<p>年齢: <span th:text="${age}">ここに年齢</span> 歳</p>
</body>
</html>
このような小さなプロジェクトを積み重ねることで、Thymeleaf の使い方やメリットが自然に身につきます。迷ったら「Thymeleaf 使い方 初心者」などのキーワードで検索すると、役立つ情報がたくさん出てくるので安心です。
まとめ
Thymeleaf のしくみや基本構文を学ぶことで、Spring MVC と連携した動的なテンプレート処理をより深く理解できるようになります。今回の記事では、Pleiades＋Gradle という初心者がよく使う開発環境で Thymeleaf を扱う流れを初めから丁寧に追いかけながら、画面に値を埋め込む方法や条件分岐、繰り返し処理など、実際の開発で必ず必要となる操作を体系的に整理しました。Thymeleaf は単なるテンプレートエンジンにとどまらず、HTML を壊さずに扱える特長や、サーバサイドレンダリングが得意な構造によって、静的ページと同じ感覚で画面の状態を確認できる点が、多くの開発現場で支持されている理由でもあります。
特に本文で扱った th:text、th:if、th:each といった属性は、どの規模の Web アプリケーションでも活用される中心的な構文であり、これらを組み合わせることでユーザー情報の表示や一覧画面の構築、ページ内容の条件切り替えなど、幅広い用途に適用できます。たとえばメッセージの表示では th:text を使い、ログイン状態の判定では th:if や th:unless を併用し、一覧形式の画面では th:each を利用してループ処理することができます。また、複数の構文をまとめて活用することでより柔軟なテンプレート構築ができるため、初心者でも理解しやすい一方で大規模アプリケーションでも十分対応できる拡張性があります。
Spring Boot との親和性が高い点も Thymeleaf の大きな魅力であり、Gradle の依存管理だけで簡単に導入できるため、初心者でもつまずきにくく、環境構築から画面表示までの流れが非常にスムーズになります。また、Java のモデルオブジェクトをそのままテンプレートで扱えるため、コントローラから受け渡したデータ構造を忠実に画面へ反映でき、業務システムや管理画面などのように、複雑なデータを扱う場面でも活躍します。実際の記事中では、文字列、リスト、オブジェクト、状態を持つデータなどを例にして学習しましたが、これらは業務アプリでも頻繁に用いられるパターンであり、ひとつひとつ理解しておくことで開発効率が大きく変わります。
また、エラーが発生したときにどこを確認すればよいか、という点も重要な学習ポイントです。テンプレートのパスが誤っているときや、モデルに値を渡していないために表示できないときは、初心者が特につまずきやすい部分です。ファイル配置場所の確認や、@Controller 側での model.addAttribute の記述漏れなどを見直すことで、ほとんどの問題は解決できます。Thymeleaf はエラーメッセージが比較的わかりやすいため、慣れてくるとどこに原因があるか自然と推測できるようになり、トラブルシューティング能力も高まります。
最後に、学んだ内容を復習するために小さなサンプルを用意しました。構文の組み合わせ方やテンプレートの流れをもう一度確認しながら、自分で新しい画面を作ってみることで、理解がさらに深まります。Thymeleaf は学習素材が豊富で、検索すれば多くの例が見つかりやすいため、疑問が出たときに調べながら試すスタイルの学習とも相性が良いのが特長です。
サンプルコード（まとめ用の簡単な復習）
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>まとめ復習サンプル</title>
</head>
<body>
<h2>復習サンプル</h2>
<p th:text="${message}">ここにメッセージ</p>
<p th:if="${user != null}">
ようこそ、<span th:text="${user.name}">ユーザー名</span> さん
</p>
<ul>
<li th:each="item, iter : ${items}">
<span th:text="${iter.index + 1}">1</span> - <span th:text="${item}">アイテム</span>
</li>
</ul>
</body>
</html>
生徒：今日学んだ Thymeleaf の基礎が、実際の画面づくりとどう結びつくのかよくわかりました。
先生：そうですね。特に th:text と th:each はどの画面でも使うので、しっかり理解しておくと開発が一気にやりやすくなりますよ。
生徒：一覧表示や条件分岐を簡単に書けるのも便利だと感じました。Spring MVC と連携すると、より実用的になりますね。
先生：その通りです。モデルでセットした値をシンプルな形でテンプレートへ渡せるので、画面側の編集もしやすい構成になります。
生徒：次はもっと複雑な画面にも挑戦してみたいです。たとえば複数階層のデータや、状態によって表示内容が変わる画面なども作れそうです。
先生：ぜひ挑戦してください。Thymeleaf は奥深いですが、基本を押さえればどんどん応用が利くようになりますよ。
この記事を読んだ人からの質問
