Thymeleafとは？初心者向けにやさしく解説！テンプレートエンジンの基本とSpringとの連携

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

新人

「SpringでWebアプリを作っていると、Thymeleafってよく聞くんですけど、それって何なんですか？」

先輩

「Thymeleafは、HTMLファイルにJavaのデータを埋め込んで、動的にページを生成するテンプレートエンジンの一つだよ。」

新人

「JSPとは違うんですか？なぜThymeleafが使われるんでしょう？」

先輩

「そのへんも含めて、今回はThymeleafの基本と使い方を順番に解説していくね。」

1. Thymeleafとは何か？

Thymeleaf（タイムリーフ）は、Javaで書かれたWebアプリケーションにおいて、HTMLを動的に生成するためのテンプレートエンジンです。Spring Framework、特にSpring MVCとの親和性が高く、HTML出力に特化した機能を多く持っています。

Thymeleafを使うと、HTMLファイルにJavaのデータや処理結果を埋め込むことができ、ユーザーの操作やデータに応じてページ内容を動的に切り替えることができます。

Springプロジェクトでは、ビューのレンダリングをThymeleafで行うケースが増えており、JSPの代替として注目されています。

2. HTMLテンプレートエンジンとしての役割

Thymeleafの役割は、JavaアプリケーションとHTMLをつなぐことです。コントローラで処理したJavaのオブジェクトを、Thymeleafを使ってHTMLページに反映させることができます。

例えば、Java側で「ユーザー情報」を取得したときに、Thymeleafを使えばその情報をHTMLに自然な形で表示できます。これにより、JavaとHTMLの連携がとてもスムーズになります。

Thymeleafの特徴は、通常のHTMLとしても表示可能なことです。これは、ブラウザでHTMLファイルを直接開いたときにもエラーにならず、構文が破綻しないという意味です。静的ページとしても確認しやすいため、デザイナーとエンジニアの共同作業にも向いています。

以下は、Thymeleafを使ってSpringの@Controllerから値を受け取り、HTMLに表示する基本的な例です。


@Controller
public class GreetingController {

    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("message", "こんにちは、Thymeleaf！");
        return "hello";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>挨拶ページ</title>
</head>
<body>
    <p th:text="${message}">ここにメッセージが表示されます</p>
</body>
</html>

テンプレートエンジンとしてのThymeleafは、HTMLとの整合性を保ちつつ、Javaから渡された情報をシンプルに埋め込めるのが魅力です。

3. なぜJSPではなくThymeleafが選ばれるのか？

以前は、Spring MVCのビューとしてJSP（JavaServer Pages）が一般的に使われていましたが、最近では多くのプロジェクトでThymeleafが選ばれています。その理由は以下のとおりです。

HTMLファイルとして自然な構造：JSPではタグライブラリが多く、HTMLとして崩れやすいが、ThymeleafはそのままHTMLとして開ける。
サーバーサイドでの処理の明確化：条件分岐やループ処理などが明示的に記述でき、コードの可読性が高い。
Springとの親和性が高い：Spring Bootのstarter依存関係にThymeleafが標準で組み込まれており、設定も簡単。
JSPに比べて学習コストが低い：HTMLの構文を崩さずに使えるため、初心者でも直感的に理解しやすい。

また、JSPではWebサーバーにTomcatなどのサーブレットコンテナが必要ですが、ThymeleafはSpring Bootと組み合わせることで、より簡潔な構成でWebアプリケーションを開発できます。

このように、ThymeleafはHTMLテンプレートエンジンとして、Springアプリケーション開発において理想的な選択肢となっており、今後も使用が拡大していくことが予想されます。

次回は、実際にThymeleafの構文や、具体的なHTMLファイルの書き方について、もっと詳しく解説していきましょう。

4. Thymeleafの基本構文と記法を理解しよう

Thymeleafでは、Javaで用意したデータをHTMLに埋め込むために、専用の属性（th属性）を使います。これにより、動的なHTML出力が可能になります。ここでは基本的な記法について学びましょう。

変数の出力（th:textの使い方）

th:textは、HTMLタグのテキスト部分に値を埋め込むために使います。Thymeleaf 変数の表示で最も基本となる構文です。


<p th:text="${userName}">名前が入ります</p>

このように書くと、Java側でmodel.addAttribute("userName", "田中太郎");と渡したデータが、HTML上に表示されます。

条件分岐（th:if / th:unless）

Thymeleafでは、HTMLの表示を条件によって制御できます。これはth:ifやth:unlessという属性を使って実現します。


<p th:if="${isLogin}">ログイン中のユーザーです</p>
<p th:unless="${isLogin}">ログインしてください</p>

この例では、isLoginという変数がtrueなら最初の文が、falseなら次の文が表示されます。th:ifは「表示する」、th:unlessは「表示しない」という意味です。

繰り返し（th:each）

th:eachを使えば、リストなどのコレクションを繰り返し表示できます。ループの中で使える変数名を自由に設定できるのが特徴です。


<ul>
    <li th:each="item : ${itemList}" th:text="${item}">商品名</li>
</ul>

このコードでは、Javaでmodel.addAttribute("itemList", List.of("りんご", "バナナ", "ぶどう"));と渡しておくと、リストの内容が順番に表示されます。

5. Spring MVCとの連携方法（@ControllerからHTMLへ）

Spring Controller HTML連携は、Thymeleafを使ううえで最も重要なポイントです。Springの@ControllerからデータをModelに追加し、HTMLテンプレートに渡すことで、画面に動的な情報を表示できます。


@Controller
public class UserController {

    @GetMapping("/user")
    public String userPage(Model model) {
        model.addAttribute("userName", "佐藤花子");
        model.addAttribute("age", 28);
        return "user";
    }
}

上記の@Controllerでは、userNameとageという変数をHTMLに渡しています。この値をテンプレート側で次のように使います。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ユーザー情報</title>
</head>
<body>
    <h1 th:text="${userName}">ユーザー名</h1>
    <p th:text="'年齢：' + ${age} + '歳'">年齢</p>
</body>
</html>

このように、コントローラーから渡されたデータは、${変数名}の形で参照できます。文字列の連結などもテンプレート内で簡単にできます。

注意点としては、HTMLファイルの保存場所をsrc/main/resources/templatesフォルダにする必要があります。また、ファイル名の拡張子は.htmlにしてください。

6. HTMLとの親和性が高いThymeleafの魅力

Thymeleafは、静的HTMLとしても表示できるテンプレートエンジンという点が大きな特徴です。これは、テンプレート内で使われる構文が通常のHTMLに近く、特殊なタグや構文が少ないためです。

例えば、HTMLをブラウザで直接開いても、Javaのデータがない場合はデフォルトの内容が表示されるだけで、構文エラーにはなりません。


<p th:text="${message}">ここにメッセージが表示されます</p>

この例をそのままブラウザで開くと、「ここにメッセージが表示されます」と表示されます。つまり、Thymeleafの構文を使っても、HTMLとしての構造は壊れないのです。

これはデザイナーやフロントエンド開発者にとっても非常に助かるポイントで、Thymeleafを使えば、デザインとロジックの分離が自然に行えます。

さらに、フォームとの連携にも強く、th:actionやth:fieldを使えば、Javaオブジェクトとフォームの自動バインディングも簡単に行えます。これらは次回以降の記事で詳しく取り上げる予定です。

Thymeleafの親和性の高さは、チーム開発においても力を発揮します。静的HTMLとしてブラウザ確認ができるので、エンジニアとデザイナーが並行して作業することが可能になります。

7. よく使うth属性の一覧と使い方

Thymeleafには、テンプレートでのHTML出力を制御するための専用属性が多数用意されています。ここではテンプレートエンジン初心者でも理解しやすいよう、特によく使われるth属性の使い方を実例と一緒に解説していきます。

th:text：テキスト出力

Thymeleaf th:textは最もよく使われる属性で、HTMLの要素にテキストを挿入するために使います。エスケープ処理が自動で行われるため、XSS対策としても有効です。


<p th:text="${message}">ここにメッセージが表示されます</p>

th:if / th:unless：条件による表示制御

表示したい内容を条件によって切り替える場合は、th:ifまたはth:unlessを使います。


<p th:if="${isAdmin}">管理者専用メニュー</p>
<p th:unless="${isAdmin}">一般ユーザー用メニュー</p>

th:each：繰り返し処理

リストなどの繰り返しにはth:eachを使います。HTMLの構造そのままでループを実現できます。


<ul>
    <li th:each="user : ${userList}" th:text="${user.name}">ユーザー名</li>
</ul>

th:href：リンクの動的生成

th:hrefは、リンクのURLを動的に生成したい場合に使用します。


<a th:href="@{/user/edit/{id}(id=${user.id})}">編集</a>

このように書くことで、/user/edit/3のようなURLを自動生成できます。

8. 実際の画面を表示するサンプルフロー

ここでは、Spring MVC ビューでの処理フローを簡単な例で確認しましょう。データをコントローラからHTMLテンプレートへ渡して表示する、Thymeleafの基本的な流れです。

ステップ1：コントローラの作成


@Controller
public class BookController {

    @GetMapping("/books")
    public String bookList(Model model) {
        List<String> books = List.of("Java入門", "Spring徹底解説", "Thymeleafガイド");
        model.addAttribute("bookList", books);
        return "book-list";
    }
}

ステップ2：テンプレートファイル（book-list.html）の作成


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>書籍一覧</title>
</head>
<body>
    <h1>おすすめ書籍一覧</h1>
    <ul>
        <li th:each="book : ${bookList}" th:text="${book}">書籍名</li>
    </ul>
</body>
</html>

ステップ3：表示結果


おすすめ書籍一覧
- Java入門
- Spring徹底解説
- Thymeleafガイド

このように、Modelに追加したデータは、Thymeleafテンプレートで繰り返し表示され、HTMLとして自然に出力されます。

9. Thymeleafを使うときの注意点とベストプラクティス

ここでは、テンプレートエンジン初心者が陥りがちな落とし穴や、実務で役立つベストプラクティスを紹介します。

th属性の優先順位に注意

Thymeleafではth:*属性が指定されている場合、元のHTML属性より優先されます。たとえば、th:hrefが指定されると、hrefの値は上書きされます。

HTML構造を守ること

ThymeleafはHTMLとの親和性が高い反面、構文エラーや属性の書き忘れがあると、画面に表示されない原因になります。要素の閉じタグ漏れや属性の記述ミスに注意しましょう。

nullチェックを忘れずに

Javaで渡した変数がnullだった場合、Thymeleaf側でうまく表示されないことがあります。th:ifでのnullチェックや、EL式内の?:（三項演算子）を活用しましょう。


<p th:text="${userName ?: 'ゲスト'}">ユーザー名</p>

テンプレートはtemplatesフォルダに配置する

HTMLファイルは必ずsrc/main/resources/templates内に配置してください。設定を変更していない限り、Spring Bootはこの場所をテンプレートの読み込み先として使用します。

動的なリンク生成はth:hrefで行う

URLのパラメータを動的に組み合わせるときは、th:hrefを使って記述します。Javaのルーティングと一致させることで、URL変更にも強い構造になります。


<a th:href="@{/detail/{id}(id=${item.id})}">詳細ページ</a>

このような小さな工夫が、保守性や可読性の向上につながります。

以上が、Thymeleafを実務で使うための基礎知識と活用法です。これらを意識することで、Spring MVCとの連携がスムーズになり、テンプレートエンジンとしての強みを十分に活かせるようになります。

次回は、フォーム入力のバインディングやバリデーションとの組み合わせなど、さらに実践的なThymeleafの使い方を掘り下げていきます。