2024.08.29 Thymeleaf

Thymeleaf（タイムリーフ）とは？特徴・導入・基本的な使い方をわかりやすく解説

Thymeleaf（タイムリーフ）とは、Javaで使われるテンプレートエンジンの一つです。コントローラーから渡したデータをHTMLに埋め込み、内容が動的に変化するWebページを生成するために使われます。特にSpring Bootの標準テンプレートエンジンとして広く利用されており、Javaでサーバーサイドの画面を作る際の定番です。本記事では、Thymeleafの特徴、導入方法、th:text・th:each・th:hrefといった基本構文の使い方を、初心者向けにわかりやすく解説します。

※本記事のコード例や仕様は執筆時点の情報です。詳細や最新の仕様はThymeleaf公式ドキュメントで確認してください。

Thymeleafとは

Thymeleafは、サーバーサイドでHTMLを生成するためのJavaライブラリです。「テンプレート」と呼ばれるHTMLファイルに、Javaから渡したデータ（変数）を流し込み、最終的なWebページを組み立てます。たとえば、データベースから取得したユーザー名や商品一覧を、HTML上に動的に表示するといった用途で使われます。

Javaのテンプレートエンジンには、かつて主流だったJSPや、FreeMarkerなどもありますが、現在のSpring BootではThymeleafが標準的に推奨されており、最もよく使われる選択肢の一つになっています。

Thymeleafの特徴

Thymeleafには、ほかのテンプレートエンジンと比べて次のような特徴があります。

  • HTMLをそのままブラウザで確認できる（ナチュラルテンプレート）：Thymeleafのテンプレートは、th: という独自の属性をHTMLタグに追加する形で書きます。これらは通常のHTML属性を拡張したものなので、テンプレートファイルをそのままブラウザで開いても、レイアウトが崩れずに表示できます。デザイナーと開発者が同じファイルを共有しやすいのが大きな利点です。
  • Spring Bootとの統合が容易：Spring Bootでは、依存関係を追加するだけでほぼ設定なしに使い始められます。Spring MVCのコントローラーから渡したデータを、自然な形で画面に表示できます。
  • 学習コストが低い：HTMLの知識があれば直感的に書けるため、初心者でも比較的習得しやすいエンジンです。
  • デザインとロジックの分離：表示の制御はテンプレート側の th: 属性で行うため、JavaコードとHTMLを分離しやすく、保守性の高い構成になります。

Thymeleafの導入方法

Spring Bootプロジェクトであれば、Thymeleafの導入はとても簡単です。MavenまたはGradleに、Thymeleaf用のスターター依存関係を追加するだけです。

Mavenの場合は pom.xml に次を追加します。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

これだけで、Spring Bootの自動設定が働き、特別な設定なしにThymeleafが使えるようになります。テンプレートのHTMLファイルは、デフォルトで src/main/resources/templates フォルダに配置します。

なお開発中は、テンプレートの変更がすぐ反映されるよう、application.properties に spring.thymeleaf.cache=false を設定してキャッシュを無効にしておくと便利です（本番では有効に戻します）。

Thymeleafの基本的な使い方（主要な構文）

Thymeleafでは、HTMLタグに th: で始まる属性を付けることで、データの表示や制御を行います。よく使う基本構文を見ていきましょう。冒頭で <html xmlns:th="http://www.thymeleaf.org"> のように名前空間を宣言しておきます。

th:text（テキストの表示）

最もよく使う属性です。コントローラーから渡した変数を、要素のテキストとして表示します。変数は ${...} で参照します。

<!-- Javaで model.addAttribute("message", "こんにちは"); を渡した場合 -->
<p th:text="${message}">ここにメッセージが表示されます</p>
<!-- 出力結果: <p>こんにちは</p> -->

タグの中に書いたダミーテキスト（「ここにメッセージ〜」）は、ブラウザで直接開いたときのプレビュー用で、実際の表示時には変数の値に置き換わります。

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

条件によって要素を表示・非表示にします。th:if は条件が真のとき、th:unless は偽のときに表示します。

<div th:if="${user.admin}">管理者向けメニュー</div>
<p th:unless="${user.admin}">一般ユーザー向けの表示</p>

複数の状態で切り替えたい場合は、th:switch と th:case を使うと見やすく書けます。

th:each（繰り返し処理）

リストや配列の要素を順に表示します。一覧表示で頻繁に使う構文です。

<!-- model.addAttribute("items", List.of("リンゴ", "バナナ")); -->
<ul>
  <li th:each="item : ${items}" th:text="${item}"></li>
</ul>
<!-- 出力: <li>リンゴ</li> <li>バナナ</li> -->

商品一覧やユーザー一覧をテーブルで表示するときにも、<tr th:each="..."> の形でそのまま使えます。

th:href（リンクURLの生成）

リンクのURLを生成します。@{...} というURL式を使い、パラメータも安全に埋め込めます。

<!-- 静的なリンク -->
<a th:href="@{/products}">商品一覧</a>

<!-- パラメータ付きの動的リンク -->
<a th:href="@{/products/{id}(id=${product.id})}">詳細を見る</a>

@{...} を使うと、アプリケーションのルートからのパスが自動的に補われ、パラメータのエンコードも適切に処理されます。

フォームの扱いとフラグメント（少し進んだ使い方）

基本構文に慣れたら、次のような機能も便利です。

フォームのバインディングでは、th:object でフォーム全体に対応するオブジェクトを指定し、各入力欄を th:field でそのプロパティに結びつけます。Spring MVCと組み合わせると、入力値をJavaオブジェクトとしてそのまま受け取れ、入力チェック（バリデーション）のエラーメッセージも th:errors で表示できます。

<form th:action="@{/user/save}" th:object="${user}" method="post">
  <input type="text" th:field="*{name}" />
  <button type="submit">保存</button>
</form>

フラグメントは、ヘッダーやフッターなど複数ページで共通する部分を部品化する機能です。th:fragment で定義した部品を、他のテンプレートから th:insert や th:replace で読み込んで再利用できます。共通部分を一か所で管理できるため、デザイン変更時の修正が一度で済みます。

Thymeleafと他のテンプレートエンジンの違い

Javaの代表的なテンプレートエンジンと比べると、Thymeleafの位置づけがわかりやすくなります。

エンジン 特徴
Thymeleaf HTMLをそのままブラウザで確認できる。Spring Boot標準で相性が良い。デザインとロジックを分離しやすい
JSP 古くからあるが、Spring Bootでは推奨されず、ブラウザでそのまま表示できない
FreeMarker 高速で柔軟だが、独自記法のためHTMLとしてそのまま表示はできない

「HTMLとして自然に扱えること」を重視するならThymeleaf、というのが大まかな選び方の目安です。特にSpring Bootを使う場合は、標準サポートのThymeleafが第一候補になります。

まとめ

Thymeleafの要点を整理します。

  • Thymeleafとは、Javaで使われるテンプレートエンジン。Spring Bootの標準として広く使われている
  • HTMLに th: 属性を足す形で書くため、ブラウザでそのまま確認でき、デザインとロジックを分離しやすい
  • 導入はスターター依存関係を追加するだけ。テンプレートは templates フォルダに配置
  • 基本構文は th:text（表示）、th:if（条件）、th:each（繰り返し）、th:href（リンク）
  • フォームのバインディングやフラグメントによる部品化も可能

Thymeleafは、JavaとHTMLをきれいに分離しながら動的な画面を作れる、扱いやすいテンプレートエンジンです。まずは th:text と th:each から試し、少しずつ使える構文を増やしていくとよいでしょう。

よくある質問（FAQ）

Q. Thymeleafの読み方は?
A. 「タイムリーフ」と読みます。英語の thyme（タイム、ハーブの一種）と leaf（葉）を組み合わせた名称です。

Q. ThymeleafはSpring Bootでないと使えませんか?
A. Spring Boot以外でも利用できますが、Spring Bootでは標準サポートにより設定がほぼ不要で、最も導入が簡単です。実際の利用例の多くはSpring Bootとの組み合わせです。

Q. テンプレートの変更が反映されないのですが?
A. 開発中はテンプレートキャッシュが原因のことがあります。application.properties に spring.thymeleaf.cache=false を設定するとキャッシュが無効になり、変更がすぐ反映されます。

Q. ThymeleafとJSPはどちらを使うべきですか?
A. これから新規に開発するなら、Spring Bootで標準推奨されているThymeleafが無難です。JSPは古くからの資産がある場合に使われますが、Spring Bootでは推奨されていません。

Q. ${...}、*{...}、@{...}、#{...}の違いは?
A. ${...}は変数式（データの参照）、*{...}はth:objectで指定したオブジェクトのプロパティ参照、@{...}はURL式、#{...}はメッセージ（多言語対応の文言）参照です。用途ごとに使い分けます。

資料請求

RELATED POSTS 関連記事

一覧へ戻る