新人と先輩の会話形式で理解しよう

新人

「PleiadesでSpring Bootを作るときに、Thymeleafを使いたいんですけど、どう始めたらいいか分かりません。」

先輩

「ThymeleafはSpring Bootと相性が良いテンプレートエンジンですよ。Pleiadesで作ったGradleプロジェクトなら、依存関係を追加して、@ControllerでHTMLを返す仕組みがすぐに使えます。」

新人

「なるほど。どんな特徴があるのか教えてもらえますか？」

先輩

「まずはThymeleafがどういうものかを説明して、その後に導入方法を詳しく見ていきましょう。」

1. Thymeleafとは？

Thymeleaf（タイムリーフ）はJava向けのサーバサイドHTMLテンプレートエンジンです。PleiadesのGradleプロジェクトにおいて、HTMLをサーバサイドでレンダリングするときに非常に便利です。Spring Bootの公式スターターにも標準で含まれているため、特別な設定をしなくてもスムーズに使い始められます。

Thymeleafの最大の特長は、HTMLの骨格をそのままに、th:textやth:ifなどの属性を付けるだけで動的な表示や条件分岐ができる点です。そのため、デザイナーと開発者が同じHTMLを共有しやすく、保守性や可読性が高くなります。

また、Pleiades環境での開発では、依存関係の追加も簡単に行えるため、初心者でも迷わずに導入できます。例えば、Googleなどで「Thymeleaf 入門」「Thymeleaf 使い方 Pleiades」などのキーワードで調べると、たくさんの情報が出てきて安心です。

2. Thymeleafの導入方法と基本的なセットアップ手順

ここからは、Thymeleafを実際にSpring Bootプロジェクトに導入する流れを解説します。開発環境はPleiadesで、Gradleを使ったプロジェクトを想定しています。

● Gradleでの依存関係の追加

Pleiadesの「Gradle」タブから「dependencies」を開き、必要な依存関係にチェックを入れるだけでOKです。手動でbuild.gradleに書く場合は、次のようにします。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

これにより、ThymeleafとSpring MVCがすぐに使えるようになります。PleiadesのGradle管理は自動的に反映されるので便利です。

● HTMLテンプレートファイルの作成

テンプレートファイルは、src/main/resources/templatesフォルダに配置します。例えば、トップページ用にindex.htmlを作ります。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="UTF-8">
  <title>Thymeleaf 入門</title>
</head>
<body>
  <h1 th:text="'こんにちは、' + ${name} + 'さん！'">デフォルトメッセージ</h1>
</body>
</html>

このように、th:textを使ってJavaの変数をHTMLに埋め込めます。

● @Controllerでの設定

最後に、@Controllerを使って値を渡し、HTMLを返す部分を作ります。下記はサンプルのコントローラ例です。


@Controller
public class HomeController {
    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("name", "新人さん");
        return "index";
    }
}

これで、ブラウザで http://localhost:8080/ にアクセスすると、「こんにちは、新人さん！」と表示されます。

3. Thymeleafの基本構文（th:if、th:each、th:textなど）

ここではThymeleafの代表的な構文を紹介します。初心者でも迷わず使えるようにわかりやすく解説します。

● th:text：テキストの埋め込み

Javaの変数をHTMLに表示したいときに使用します。@ControllerでModelに追加した値を埋め込みます。


<p th:text="${message}">メッセージが入ります</p>

● th:if／th:unless：条件分岐

表示／非表示の条件をつけたいときに便利です。Booleanやnull判定にも対応できます。


<p th:if="${user != null}">ようこそ、<span th:text="${user.name}">ユーザー</span>さん！</p>
<p th:unless="${user != null}">ログインしてください。</p>

● th:each：繰り返し処理

リストなどをループ表示するときに使用。変数名やインデックスも扱えます。


<ul>
  <li th:each="item, stat : ${items}">
    <span th:text="${stat.index + 1}">1</span>. <span th:text="${item}">項目</span>
  </li>
</ul>

4. Spring BootとThymeleafの連携方法

ここではSpring BootとThymeleafの基本的な連携手順を紹介します。Pleiades＋Gradle環境でも初心者が迷わないように解説します。

● ControllerでModelを使って値を渡す

@Controllerアノテーションを使ったJavaコードで、HTMLに表示する変数をModelにセットします。


@Controller
public class DemoController {
    @GetMapping("/demo")
    public String demo(Model model) {
        List<String> items = List.of("A", "B", "C");
        model.addAttribute("items", items);
        model.addAttribute("user", new User("太郎"));
        return "demo";
    }
}

このようにModelを通じて、HTMLテンプレートにデータを渡します。

● Thymeleafテンプレートでの表示

先ほどのControllerで渡したデータを、テンプレート内でth:eachやth:textなどを使って表示します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>デモページ</title></head>
<body>
  <h2 th:text="'こんにちは、' + ${user.name} + 'さん'">ようこそ</h2>
  <ul>
    <li th:each="item : ${items}" th:text="${item}">項目</li>
  </ul>
</body>
</html>

5. 簡単なサンプルプロジェクトの作成と実行方法

実際に動くサンプルを通じて、Thymeleafの使い方を体感していきましょう。

● プロジェクト作成の流れ

Pleiadesで「Spring Boot + Thymeleaf」テンプレートのプロジェクトを作成します。依存にspring-boot-starter-thymeleafとspring-boot-starter-webを追加してください。

● コードとテンプレートの配置例


@Controller
public class SampleController {
    @GetMapping("/sample")
    public String sample(Model model) {
        model.addAttribute("title", "サンプルページ");
        model.addAttribute("numbers", List.of(1,2,3,4,5));
        return "sample";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title th:text="${title}">タイトル</title></head>
<body>
  <h1 th:text="${title}">タイトル</h1>
  <ul>
    <li th:each="num : ${numbers}" th:text="'No.' + ${num}">数字</li>
  </ul>
</body>
</html>

これでSpring Bootアプリを実行し、http://localhost:8080/sampleにアクセスすると、変数とループが反映されたページが表示されます。

6. Thymeleafを使うメリット（可読性、学習コストの低さなど）

Thymeleafを使うとJavaの変数や条件分岐、繰り返し処理をHTMLに直接書けるので、画面の設計がとても分かりやすくなります。特にPleiades環境でGradle管理のプロジェクトに導入すると、HTMLテンプレートがそのままプレビューできるので、デザイナーと開発者が一緒に確認しやすく、修正もしやすくなります。

また、Gradleの依存関係設定はPleiadesのチェックだけで完了するため、複雑なXML設定やMaven設定を覚える必要がありません。そのため、初心者でも導入や設定の学習コストが低く、スムーズに開発を進められます。

さらに、Spring Bootの標準機能としてサポートされているため、@Controllerで値を渡してHTMLを返す基本パターンを覚えるだけで、Web開発の基礎をしっかり身につけられます。SEO視点でも、静的なHTMLライクな構成で適切なメタタグを指定すれば、検索エンジンに評価されやすい構造になります。

7. よくあるエラーや注意点とその対処法

Thymeleafを使う際によく出るエラーと、その簡単な対処法を紹介します。

● テンプレートが見つからないエラー

エラー例：「Whitelabel Error Page ○○○○ Template \"index\" not found」。これはHTMLファイルが src/main/resources/templates にないときに出ます。テンプレート名とファイル名（拡張子なし）を一致させてください。

● 変数が空（null）でエラー

例：th:text="${user.name}" で NullPointerException。対策として th:if="${user != null}" を使って、nullチェックを追加します。


<p th:if="${user != null}" th:text="'こんにちは、' + ${user.name} + 'さん！'">デフォルトメッセージ</p>
<p th:unless="${user != null}">ユーザー情報がありません。</p>

● Java側でModelに項目追加忘れ

Thymeleafテンプレート内で参照する変数をControllerで model.addAttribute(...) を忘れることがあります。実行時に「Could not resolve variable 'foo'」と出たら、Controllerを確認して変数を追加してください。

● HTML構文エラーによる表示崩れ

Thymeleafでは th:* 属性も含めてHTML構文が重要です。タグの閉じ忘れやネストミスに注意し、PleiadesのHTMLエディタで構文チェックを活用してください。

8. Thymeleafを学ぶためのおすすめの方法

Thymeleafを習得するには、実際に手を動かして体験するのがもっとも効果的です。以下のステップで学ぶのがおすすめです。

● 公式ドキュメントで基本構文を確認

まずは th:text、th:if、th:each、th:unless などの属性の使い方を公式ドキュメントでざっと確認しましょう。基本を押さえることでテンプレートが理解しやすくなります。

● 小さなサンプルを作って動かす

実際に Pleiades＋Gradleプロジェクトで ControllerとHTMLを用意し、動かしてみましょう。変数の受け渡しや条件分岐、ループ処理など、自分の手で体験すると理解が深まります。

● 実務に近いページを作ってみる

簡単なフォーム画面やToDoリストなどの小さなWebアプリを作ると、エラーへの対応力や構造設計の経験が身につきます。ここで ModelやControllerの設計、エラーハンドリングも一緒に学べます。

● コミュニティで質問・共有する

困ったときは Stack Overflow や日本語のQ&Aサイトで検索・投稿してみましょう。同じ環境（Thymeleaf＋Spring＋Pleiades＋Gradle）で学んでいる人の情報が見つかりやすく、Google検索でも「Thymeleaf Pleiades Gradle」などのキーワードでヒットしやすくなります。

まとめ

Thymeleaf入門として押さえておきたい全体像

ここまでの記事では、Thymeleafの基本的な考え方から、Spring Bootとの連携方法、Pleiades＋Gradle環境での導入手順、そして実際の使い方までを一通り確認してきました。 Thymeleafは、Javaで作られたWebアプリケーションにおいて、HTMLを動的に生成するためのテンプレートエンジンとして非常に扱いやすく、初心者にも学びやすい特徴があります。特に、HTMLタグの中に th:text や th:if、th:each といった属性を追加するだけで、条件分岐や繰り返し処理が書ける点は大きな魅力です。従来のテンプレートエンジンに比べて、HTMLとしての見た目を保ったまま開発できるため、コードの可読性や保守性が高くなります。

また、Spring BootとThymeleafの組み合わせは定番ともいえる構成で、@Controllerを使ってModelに値を詰め、HTMLテンプレートを返すという流れを覚えるだけで、基本的なWeb画面をすぐに作れるようになります。 Pleiades環境では、Gradleによる依存関係管理も直感的に行えるため、初期設定でつまずきにくい点も初心者にとって安心材料です。「Thymeleaf 入門」「Thymeleaf 使い方」「Spring Boot Thymeleaf 初心者」といったキーワードで調べたときに、本記事の内容が自然と結びつくような基礎知識を身につけられたはずです。

Controllerとテンプレートの役割を理解することが重要

記事を通して何度も登場したのが、@ControllerとThymeleafテンプレートの役割分担です。 Java側のControllerでは、画面に必要なデータを準備し、Modelに詰めることに専念します。一方、HTMLテンプレート側では、そのデータをどう表示するか、どの条件で表示・非表示を切り替えるかをThymeleafの属性で制御します。この役割分担を意識することで、コードが整理され、後から修正しやすい構成になります。

例えば、リスト表示や条件分岐をすべてHTML側で複雑に書いてしまうと、テンプレートが読みにくくなります。その場合は、Controller側であらかじめ判定用の値を用意し、Thymeleafではシンプルな th:if だけを書く、といった工夫が有効です。こうした設計の考え方は、実務に入ったときにも必ず役立つポイントになります。

基本構文を組み合わせるだけで多くの画面が作れる

Thymeleafの学習では、たくさんの機能を一度に覚える必要はありません。まずは th:text、th:if、th:unless、th:each といった基本構文を確実に理解することが大切です。これらを組み合わせるだけで、一覧画面、詳細画面、条件付きメッセージ表示など、多くのWeb画面を表現できます。初心者のうちは「なぜ表示されるのか」「なぜ表示されないのか」を一つひとつ確認しながら進めると、理解が深まります。

以下は、Controllerから渡された値を使って、条件分岐と繰り返し処理を行うシンプルなサンプルです。記事中で紹介した内容の復習として、ぜひ見返してみてください。


<div th:if="${items != null}">
    <ul>
        <li th:each="item : ${items}" th:text="${item}">項目</li>
    </ul>
</div>
<div th:unless="${items != null}">
    <p>表示するデータがありません。</p>
</div>

このような書き方に慣れてくると、Thymeleafでの画面作成が一気に楽になります。 Spring Bootと組み合わせたWebアプリケーション開発の土台として、非常に重要なポイントです。

先生と生徒の振り返り会話

生徒：Thymeleafって難しそうなイメージがありましたけど、HTMLに属性を足していくだけなんですね。

先生：そうだね。まずは普通のHTMLとして書いて、あとから th:text や th:if を付け足す感覚で大丈夫だよ。

生徒：@Controllerで値を渡して、テンプレートで表示する流れも少しずつ分かってきました。

先生：その理解はとても大事だよ。Controllerと画面の役割を分けて考えられるようになると、コードが整理されてくる。

生徒：まずは基本構文をしっかり使いこなせるように練習してみます。

先生：それが一番の近道だね。小さなサンプルをたくさん作って、Thymeleafに慣れていこう。

Thymeleafは、Spring BootでWebアプリケーションを開発するうえで避けて通れない重要な技術です。入門段階では、環境構築、Controllerとの連携、基本構文の理解を丁寧に積み重ねることが成功への近道になります。本記事で学んだ内容を土台に、ぜひ実際のアプリケーション作成に挑戦し、Thymeleafの使い方を自分のものにしていってください。